浏览器直连硬件：Web Bluetooth/Serial/WebUSB 实战完全指南

你有没有想过，打开一个网页就能连接蓝牙心率带、读取 Arduino 传感器数据，甚至直接控制 USB 设备？2026 年，Web 硬件 API 已经从实验性特性走向生产可用——Chrome 120+ 全面支持 Web Bluetooth、Web Serial 和 WebUSB 三大 API，全球已有超过 5 万个活跃网站 使用这些 API 进行硬件交互。从医疗设备数据采集到工业物联网网关配置，浏览器正在成为硬件交互的新入口。本文将从零开始，用完整可运行的代码带你掌握这三个 API 的实战用法。

⚠️ 警告： Web Bluetooth、Web Serial、WebUSB 目前仅在 Chromium 内核浏览器（Chrome、Edge、Opera）中获得完整支持。Firefox 和 Safari 尚未实现这些 API。在生产项目中使用前，务必做好浏览器兼容性检测和降级方案。

🔌 一、三大硬件 API 全景对比

1.1 API 定位与适用场景

这三个 API 解决的是不同层面的硬件通信问题。选错 API 会导致开发成本翻倍，所以先搞清楚它们各自的定位：

💡 提示： 如果你的设备同时支持 BLE 和 USB 两种接口，优先选择 Web Bluetooth——无线连接的用户体验远好于有线，而且 BLE 的权限模型更简单。只有在需要高速数据传输或设备不支持蓝牙时，才考虑 Web Serial 或 WebUSB。

1.2 权限与安全模型

三个 API 共享一套相似的安全模型：用户必须主动选择设备，网页无法自动扫描或连接任何硬件。这是 Web 平台与原生应用最大的区别——浏览器充当了硬件访问的「守门人」。

用户点击按钮 → 浏览器弹出设备选择对话框 → 用户确认 → 网页获得访问权限

每个 API 的权限范围：

• Web Bluetooth：只能访问用户选择的 BLE 设备的 GATT 服务
• Web Serial：只能访问用户选择的串口设备
• WebUSB：只能访问用户选择的 USB 设备的特定接口

📌 记住： 这些 API 都要求页面必须通过 HTTPS 提供服务（localhost 除外）。这是 Chromium 的硬性要求，HTTP 页面上调用这些 API 会直接抛出 SecurityError。

🔵 二、Web Bluetooth：无线连接 BLE 设备

2.1 核心概念：GATT 服务与特征值

BLE（Bluetooth Low Energy）通信基于 GATT（Generic Attribute Profile）协议。理解 GATT 的层次结构是使用 Web Bluetooth 的前提：

设备 (Device)
  └── 服务 (Service) — 用 UUID 标识，如心率服务 0x180D
        └── 特征值 (Characteristic) — 用 UUID 标识，如心率测量值 0x2A37
              ├── 读取 (Read)
              ├── 写入 (Write)
              └── 通知 (Notify/Indicate)

2.2 实战：连接 BLE 心率监测器

以下是一个完整的 BLE 心率监测示例。代码可以直接在 Chrome 浏览器中运行：

// BLE 心率监测器 — 完整连接与数据读取示例
const HEART_RATE_SERVICE = 'heart_rate';
const HEART_RATE_MEASUREMENT = 'heart_rate_measurement';

async function connectHeartRateMonitor() {
  try {
    // 第一步：扫描并让用户选择 BLE 设备
    const device = await navigator.bluetooth.requestDevice({
      filters: [{ services: [HEART_RATE_SERVICE] }],
      // 或者用 acceptAllDevices: true 扫描所有设备
    });

    console.log(`已选择设备: ${device.name}`);

    // 监听设备断开事件
    device.addEventListener('gattserverdisconnected', () => {
      console.warn('设备已断开，尝试重连...');
      setTimeout(() => connectHeartRateMonitor(), 3000);
    });

    // 第二步：连接 GATT 服务器
    const server = await device.gatt.connect();
    console.log('GATT 服务器已连接');

    // 第三步：获取心率服务
    const service = await server.getPrimaryService(HEART_RATE_SERVICE);

    // 第四步：获取心率测量特征值
    const characteristic = await service.getCharacteristic(HEART_RATE_MEASUREMENT);

    // 第五步：订阅心率通知
    await characteristic.startNotifications();
    characteristic.addEventListener('characteristicvaluechanged', (event) => {
      const value = event.target.value;
      const heartRate = parseHeartRate(value);
      console.log(`❤️ 当前心率: ${heartRate} BPM`);
      updateUI(heartRate);
    });

    return { device, server, characteristic };
  } catch (error) {
    if (error.name === 'NotFoundError') {
      console.log('用户取消了设备选择');
    } else if (error.name === 'SecurityError') {
      console.error('安全错误：请确保使用 HTTPS');
    } else {
      console.error('连接失败:', error);
    }
    throw error;
  }
}

// 解析心率数据包（BLE 标准格式）
function parseHeartRate(value) {
  const flags = value.getUint8(0);
  const is16Bit = flags & 0x01;

  if (is16Bit) {
    return value.getUint16(1, true); // little-endian
  } else {
    return value.getUint8(1);
  }
}

function updateUI(heartRate) {
  document.getElementById('heart-rate-display').textContent = `${heartRate} BPM`;
}

2.3 自定义 BLE 服务读写

很多 IoT 设备使用自定义 GATT 服务。读写自定义特征值的模式如下：

// 读写自定义 BLE 服务 — 温湿度传感器示例
async function readCustomBLEDevice() {
  const device = await navigator.bluetooth.requestDevice({
    filters: [{ namePrefix: 'Sensor' }],
    optionalServices: ['environmental_sensing']  // 必须声明才能访问
  });

  const server = await device.gatt.connect();
  const service = await server.getPrimaryService('environmental_sensing');

  // 读取温度特征值
  const tempChar = await service.getCharacteristic('temperature');
  const tempValue = await tempChar.readValue();
  const temperature = tempValue.getInt16(0, true) / 100; // 单位：0.01°C
  console.log(`🌡️ 温度: ${temperature}°C`);

  // 读取湿度特征值
  const humidChar = await service.getCharacteristic('humidity');
  const humidValue = await humidChar.readValue();
  const humidity = humidValue.getUint16(0, true) / 100;
  console.log(`💧 湿度: ${humidity}%`);

  // 写入控制命令（如设置采样频率）
  const configChar = await service.getCharacteristic('measurement_interval');
  const interval = new Uint8Array([5]); // 5 秒采样一次
  await configChar.writeValue(interval);
  console.log('✅ 采样间隔已设置为 5 秒');

  return { temperature, humidity };
}

⚠️ 警告： optionalServices 字段经常被遗漏。如果你不声明设备可能用到的服务 UUID，getPrimaryService() 调用会抛出 NotFoundError。这是 Web Bluetooth 最常见的坑——设备明明支持该服务，但因为没在 optionalServices 中声明而无法访问。

🔌 三、Web Serial：串口通信实战

3.1 为什么需要 Web Serial？

Web Serial API 解决了一个长期痛点：在浏览器中直接与串口设备通信。在此之前，开发者必须依赖 Electron、NW.js 或原生应用才能访问串口。Web Serial 让以下场景成为可能：

• 在线 Arduino IDE（如 Arduino Cloud）
• 工业设备配置工具
• 嵌入式设备固件升级
• 串口调试终端

3.2 实战：与 Arduino 双向通信

以下代码实现了一个完整的串口终端，支持读写双向通信：

// Web Serial 串口终端 — Arduino 双向通信完整示例
class SerialTerminal {
  constructor() {
    this.port = null;
    this.reader = null;
    this.writer = null;
    this.readableStreamClosed = null;
    this.writableStreamClosed = null;
  }

  async connect(baudRate = 115200) {
    try {
      // 请求用户选择串口设备
      this.port = await navigator.serial.requestPort();

      // 打开串口连接
      await this.port.open({
        baudRate,
        dataBits: 8,
        stopBits: 1,
        parity: 'none',
        flowControl: 'none'
      });

      console.log(`串口已连接，波特率: ${baudRate}`);

      // 设置文本编解码器
      const textDecoder = new TextDecoderStream();
      this.readableStreamClosed = this.port.readable.pipeTo(textDecoder.writable);
      this.reader = textDecoder.readable.getReader();

      const textEncoder = new TextEncoderStream();
      this.writableStreamClosed = textEncoder.readable.pipeTo(this.port.writable);
      this.writer = textEncoder.writable.getWriter();

      // 开始读取数据
      this.startReading();

      return true;
    } catch (error) {
      if (error.name === 'NotFoundError') {
        console.log('用户取消了串口选择');
      } else {
        console.error('串口连接失败:', error);
      }
      return false;
    }
  }

  async startReading() {
    try {
      while (true) {
        const { value, done } = await this.reader.read();
        if (done) break;
        this.onDataReceived(value);
      }
    } catch (error) {
      console.error('读取错误:', error);
    }
  }

  onDataReceived(data) {
    // 处理接收到的数据
    const terminal = document.getElementById('terminal-output');
    terminal.textContent += data;
    terminal.scrollTop = terminal.scrollHeight;
  }

  async send(data) {
    if (!this.writer) {
      throw new Error('串口未连接');
    }
    await this.writer.write(data);
    console.log(`已发送: ${data}`);
  }

  async disconnect() {
    // 优雅关闭连接
    if (this.reader) {
      await this.reader.cancel();
      await this.readableStreamClosed.catch(() => {});
    }
    if (this.writer) {
      await this.writer.close();
      await this.writableStreamClosed.catch(() => {});
    }
    if (this.port) {
      await this.port.close();
    }
    console.log('串口已断开');
  }
}

// 使用示例
const terminal = new SerialTerminal();

document.getElementById('connect-btn').addEventListener('click', async () => {
  const connected = await terminal.connect(9600);
  if (connected) {
    document.getElementById('status').textContent = '✅ 已连接';
  }
});

document.getElementById('send-btn').addEventListener('click', async () => {
  const input = document.getElementById('command-input');
  await terminal.send(input.value + '\n');
  input.value = '';
});

document.getElementById('disconnect-btn').addEventListener('click', () => {
  terminal.disconnect();
  document.getElementById('status').textContent = '❌ 已断开';
});

3.3 二进制数据传输

很多嵌入式设备使用二进制协议而非文本协议。以下示例展示了如何发送和接收二进制数据：

// 二进制串口通信 — Modbus RTU 协议示例
async function readModbusRegister(slaveId, registerAddr) {
  const port = await navigator.serial.requestPort();
  await port.open({ baudRate: 9600 });

  const writer = port.writable.getWriter();
  const reader = port.readable.getReader();

  // 构造 Modbus RTU 请求帧
  const request = new Uint8Array([
    slaveId,                    // 从站地址
    0x03,                       // 功能码：读保持寄存器
    (registerAddr >> 8) & 0xFF, // 寄存器地址高字节
    registerAddr & 0xFF,        // 寄存器地址低字节
    0x00, 0x01                  // 读取 1 个寄存器
  ]);

  // 计算 CRC16
  const crc = calculateCRC16(request);
  const frame = new Uint8Array([...request, crc & 0xFF, (crc >> 8) & 0xFF]);

  // 发送请求
  await writer.write(frame);

  // 读取响应（带超时）
  const responsePromise = reader.read();
  const timeoutPromise = new Promise((_, reject) =>
    setTimeout(() => reject(new Error('读取超时')), 3000)
  );

  try {
    const { value } = await Promise.race([responsePromise, timeoutPromise]);
    const registerValue = (value[3] << 8) | value[4];
    console.log(`寄存器 ${registerAddr} 的值: ${registerValue}`);
    return registerValue;
  } finally {
    reader.releaseLock();
    writer.releaseLock();
    await port.close();
  }
}

// CRC16-Modbus 计算
function calculateCRC16(data) {
  let crc = 0xFFFF;
  for (const byte of data) {
    crc ^= byte;
    for (let i = 0; i < 8; i++) {
      crc = (crc & 1) ? ((crc >> 1) ^ 0xA001) : (crc >> 1);
    }
  }
  return crc;
}

💡 提示： Web Serial API 的 readable 流在设备断开时会自动关闭。但为了代码健壮性，建议在 port.ondisconnect 事件中做好清理工作，避免遗留的 reader/writer 导致资源泄漏。

🔲 四、WebUSB：直接 USB 通信

4.1 WebUSB vs Web Serial

很多开发者分不清 WebUSB 和 Web Serial 的区别。简单来说：

• Web Serial：通过 USB 转串口芯片（如 CH340、CP2102）与设备通信，本质上是模拟串口
• WebUSB：直接与 USB 设备的端点（Endpoint）通信，绕过操作系统串口驱动

WebUSB 适用于需要自定义 USB 协议的场景，比如调试 JTAG/SWD 调试器、控制 USB LED 灯条、读取 USB HID 设备等。

4.2 实战：控制 USB LED 设备

// WebUSB 控制 USB LED 灯条 — 完整示例
async function controlUSBLed() {
  // 请求 USB 设备（按 vendorId 和 productId 过滤）
  const device = await navigator.usb.requestDevice({
    filters: [{ vendorId: 0x2341 }] // Arduino vendor ID
  });

  await device.open();

  // 选择配置（大多数设备只有 1 个配置）
  if (device.configuration === null) {
    await device.selectConfiguration(1);
  }

  // 找到正确的接口和端点
  const iface = device.configuration.interfaces[0];
  const endpoint = iface.alternate.endpoints.find(
    ep => ep.direction === 'out' && ep.type === 'bulk'
  );

  if (!endpoint) {
    throw new Error('未找到 Bulk OUT 端点');
  }

  // 声明接口
  await device.claimInterface(iface.interfaceNumber);

  // 发送 LED 控制命令
  const colors = [
    [255, 0, 0],    // 红色
    [0, 255, 0],    // 绿色
    [0, 0, 255],    // 蓝色
    [255, 255, 0],  // 黄色
    [128, 0, 255],  // 紫色
  ];

  for (const [r, g, b] of colors) {
    const command = new Uint8Array([0x01, r, g, b]); // 协议：[命令码, R, G, B]
    await device.transferOut(endpoint.endpointNumber, command);
    console.log(`🎨 LED 颜色已设置: RGB(${r}, ${g}, ${b})`);
    await new Promise(resolve => setTimeout(resolve, 1000));
  }

  // 读取设备状态（如果有 IN 端点）
  const inEndpoint = iface.alternate.endpoints.find(
    ep => ep.direction === 'in' && ep.type === 'bulk'
  );

  if (inEndpoint) {
    const result = await device.transferIn(inEndpoint.endpointNumber, 64);
    const decoder = new TextDecoder();
    console.log(`设备状态: ${decoder.decode(result.data)}`);
  }

  await device.close();
}

4.3 USB 控制传输（Control Transfer）

控制传输用于设备配置和命令发送，不依赖特定端点：

// USB 控制传输 — 设备固件版本查询示例
async function queryDeviceVersion(device) {
  // 控制传输参数
  const result = await device.controlTransferIn({
    requestType: 'vendor',    // 厂商自定义请求
    recipient: 'device',
    request: 0x01,            // 自定义请求码
    value: 0x0000,
    index: 0x0000
  }, 64); // 期望接收 64 字节

  if (result.status === 'ok') {
    const version = new TextDecoder().decode(result.data).trim();
    console.log(`设备固件版本: ${version}`);
    return version;
  } else {
    throw new Error(`控制传输失败: ${result.status}`);
  }
}

⚠️ 警告： WebUSB 的 controlTransferIn/Out 方法的参数含义取决于具体的 USB 设备协议。不同厂商的设备使用不同的 request、value、index 参数。务必参考设备的 USB 描述符文档。

🛡️ 五、生产环境最佳实践

5.1 浏览器兼容性检测

在使用任何硬件 API 前，必须检测浏览器支持情况：

// 浏览器硬件 API 兼容性检测工具
const HardwareAPIChecker = {
  checkWebBluetooth() {
    return 'bluetooth' in navigator;
  },

  checkWebSerial() {
    return 'serial' in navigator;
  },

  checkWebUSB() {
    return 'usb' in navigator;
  },

  checkAll() {
    const results = {
      webBluetooth: this.checkWebBluetooth(),
      webSerial: this.checkWebSerial(),
      webUSB: this.checkWebUSB(),
      isSecureContext: window.isSecureContext,
      isChromium: /Chrome|Edg|OPR/.test(navigator.userAgent)
    };

    console.table(results);

    if (!results.isSecureContext) {
      console.error('❌ 必须通过 HTTPS 访问才能使用硬件 API');
    }
    if (!results.isChromium) {
      console.warn('⚠️ 当前浏览器不是 Chromium 内核，硬件 API 可能不可用');
    }

    return results;
  }
};

5.2 优雅降级方案

当浏览器不支持硬件 API 时，提供替代方案：

5.3 连接稳定性保障

硬件连接天然不稳定——设备可能随时断电、超出蓝牙范围或被操作系统抢占。生产级代码必须处理这些情况：

// 硬件连接管理器 — 自动重连与心跳检测
class HardwareConnectionManager {
  constructor(reconnectInterval = 5000, maxRetries = 5) {
    this.reconnectInterval = reconnectInterval;
    this.maxRetries = maxRetries;
    this.retryCount = 0;
    this.isConnected = false;
    this.connectionFn = null;
  }

  setConnectionFn(fn) {
    this.connectionFn = fn;
  }

  async connect() {
    try {
      await this.connectionFn();
      this.isConnected = true;
      this.retryCount = 0;
      console.log('✅ 设备已连接');
    } catch (error) {
      this.isConnected = false;
      console.error(`连接失败 (第 ${this.retryCount + 1} 次):`, error.message);

      if (this.retryCount < this.maxRetries) {
        this.retryCount++;
        const delay = this.reconnectInterval * Math.pow(2, this.retryCount - 1);
        console.log(`${delay / 1000} 秒后重试...`);
        setTimeout(() => this.connect(), delay);
      } else {
        console.error('❌ 已达最大重试次数，请检查设备状态');
      }
    }
  }

  onDisconnect() {
    this.isConnected = false;
    console.warn('设备断开，启动自动重连...');
    this.retryCount = 0;
    this.connect();
  }
}

📊 六、各 API 性能实测数据

基于 Chrome 126 在 macOS 上的实际测试（M1 MacBook Pro）：

⚡ 关键结论： 如果需要高速数据传输，WebUSB 是唯一选择（吞吐量是 Web Serial 的 40 倍）。如果需要无线连接，Web Bluetooth 是唯一方案。Web Serial 在延迟和稳定性上表现最均衡，适合嵌入式开发场景。

💡 七、总结与建议

选择 API 的决策树：

• 🔵 设备支持蓝牙 BLE → 优先使用 Web Bluetooth（用户体验最佳）
• 🔌 设备通过 USB 转串口连接 → 使用 Web Serial（最简单、最稳定）
• 🔲 需要自定义 USB 协议或高速传输 → 使用 WebUSB（功能最强大）
• 📱 需要支持移动端 → 目前仅 Web Bluetooth 有部分支持（Android Chrome）

相关工具推荐：

• 🔧 Web Bluetooth Test — 在线 BLE 设备测试工具
• 🔧 Serial Studio — 开源串口数据可视化工具
• 🔧 Arduino Cloud — 基于 Web Serial 的在线 Arduino IDE
• 🔧 jsjson.com JSON 格式化工具 — 处理从硬件设备采集的 JSON 数据