WebUSB实战指南：用JavaScript在浏览器中直接读写USB设备

1. 一台浏览器，一群设备：WebUSB要解决的真实痛点

做前端这些年，我一直在琢磨一件事：浏览器到底能碰硬件的边界在哪里？早年做工业看板项目，客户要求网页上直接读一台称重仪表的实时数据。当时所有人的第一反应是上ActiveX控件，装完插件还要再调IE的安全设置，Windows Defender时不时弹窗拦截，换个电脑就得重新折腾一遍。后来换成了WebSocket中转的方案，数据要走一条"仪表→串口服务器→后端服务→浏览器"的长链路，部署成本高不说，中间任何一个环节挂掉，排查链路就像剥洋葱。

那是我第一次意识到，前端不是不能碰硬件，而是缺少一条足够短、足够干净的通路。直到后来接触到WebUSB，这种"浏览器直接和USB设备对话"的能力，才真正把硬件通信的复杂度从后端转移到了前端，用JavaScript就能在Windows、macOS、Linux和Android的Chrome上直接收发USB数据，跨平台、免驱动安装、不需要任何原生插件。WebUSB解决的核心问题，就是把过去必须靠C++、Electron或者Java Applet才能做的USB通信，压缩成了一百多行JavaScript代码。

什么人会需要它？我总结下来大致有三类：一是做物联网和硬件调试工具链的开发者，想给设备做一个网页端的配置面板；二是做产线测试系统的工程师，浏览器就是现成的测试终端；三是做消费级外设厂商，比如USB扫码枪、硬件加密狗、LED控制器，希望在网页里直接和自家硬件交互，省掉各平台驱动的维护成本。

当然，它的边界也很清晰。WebUSB不是万能的，它在iOS和Safari上完全没有支持；只能跑在安全上下文（HTTPS或localhost）里；而且它操作的是USB协议层，你必须对自己设备的接口、端点、传输类型有一定了解，不能指望"插上就能用"。理解了这些边界，后面踩坑的时候心态才会稳。

2. 先把USB协议层的四件套搞清楚

很多前端同学第一次接触WebUSB，容易一上来就写代码，然后被各种报错打懵。因为WebUSB给JavaScript暴露的是贴近协议层的API，而不是封装好的"读取设备数据"这么简单。你得先知道USB设备在协议层长什么样，才能理解WebUSB的每一步调用在做什么。

2.1 USB描述符树：设备、配置、接口、端点

一条USB设备，从协议视角看是一棵清晰的树。最顶层是设备描述符，包含VID（厂商ID）、PID（产品ID）和设备的全局信息；往下是配置描述符，一个设备可以有好几套配置，比如低功耗模式和高性能模式各自独立的一套；再往下是接口描述符，接口是"这个设备在干什么"的抽象，比如一个USB声卡可能同时有音频接口和HID控制接口；最底层的端点是真正的数据通道，有方向（IN代表设备到主机，OUT代表主机到设备）、有传输类型（控制、批量、中断、等时四种）、有最大包长度。

WebUSB里你不需要手动解析这些描述符的原始字节，API已经帮你封装好了。设备对象上有configurations数组，配置对象里有interfaces数组，接口对象里有alternates和endpoints数组。当你调用claimInterface()时，等于是在告诉系统："这个接口的通道归我管了，别的驱动别碰。"这个动作非常关键，不做这一步，后面所有数据传输都是空的。

2.2 设备类型兼容度：为什么有些设备能连、有些连不上

这是WebUSB最容易让人困惑的地方。并非所有USB设备都能被WebUSB直接访问，能不能连，取决于该设备的操作系统驱动绑定情况。

在Windows上，一个USB设备通常会被系统自带的类驱动接管，比如HID设备被hidusb.sys接管，大容量存储被USBSTOR接管，音频类设备被usbaudio接管。如果设备已经被这类驱动绑定了，WebUSB的requestDevice压根不会把它列出来，因为浏览器没权限抢占已经被系统占用的设备。

所以WebUSB实际最适合的设备类型，是那些没有固定类驱动的设备——比如自定义HID之外的自定义设备，或者是厂商自己提供了WinUSB驱动并声明了MSOS描述符的设备。凡是能在设备管理器里看到"WinUSB"或者"USB输入设备"但被标记为"vendor-specific"的外设，大概率能被WebUSB用起来。这也是为什么好多开发者在量产的USB外设上做WebUSB时，先要烧写一段特殊的描述符或者改驱动。

2.3 安全模型：为什么不能"静默连接"一座设备桥

WebUSB的安全模型，核心是"用户知情+授权"。它做了三层约束。

第一，navigator.usb.requestDevice()必须在用户手势中调用，比如点击按钮的回调里。你不能在页面加载完成后悄悄弹设备选择框。

第二，调用时会弹出浏览器的原生对话框，列出所有匹配过滤条件的设备，用户必须主动勾选授权。这一步和摄像头、麦克风的授权逻辑类似，但更严格——每次授权只对当前页面源生效，用户关闭页面后再回来，需要重新授权。

第三，设备接口一旦被声明（claimInterface），该标签页就等于把这个USB设备独占住了。另一个标签页即使同一站点，也无法同时操作同一个接口，除非当前页面释放或关闭。

这套机制保证了WebUSB不会被恶意网页当作隐蔽通道来扫描和操控用户外设。从我的体验看，它虽然让开发者在"自动重连"和"免打扰"上多费些心思，但它换来的信任边界是值得的——至少用户能明确看到浏览器弹窗，知道自己正在把哪台设备交给一个网页。

3. 实战：一百行JavaScript让浏览器读写一台USB设备

讲完理论，直接上一个能跑起来的例子。我用一台常见的USB转串口芯片CH340外接的单片机开发板来做演示目标。这里你不需要有完全一样的硬件，重点是理解整个调用链：请求设备→打开→选择配置→声明接口→收发数据。

3.1 环境准备：HTTPS或localhost + Chrome系浏览器

WebUSB只在安全上下文中可用。你把页面部署到HTTPS域名下，或者本地开发直接跑http://localhost，都算安全上下文。浏览器方面，Chrome、Edge、Opera这些都基于Chromium，支持没问题；Firefox和Safari至今不支持，注意别在客户现场用Firefox演示翻车。

确认当前浏览器是否支持，一行代码：

javascript复制if (!navigator.usb) {
  alert('当前浏览器不支持WebUSB，请使用最新版Chrome或Edge');
}

3.2 请求并授权设备

requestDevice接收一个filters参数，用来缩小设备列表。最常用的是按VID和PID过滤：

javascript复制let device;

async function connectUSB() {
  try {
    device = await navigator.usb.requestDevice({
      filters: [
        { vendorId: 0x1a86 },  // CH340的VID，实际换成你自己的
        // 更精确可以加上 productId
        // { vendorId: 0x1a86, productId: 0x7523 }
      ]
    });
    console.log('已选择设备：', device.productName);
  } catch (err) {
    if (err.name === 'NotFoundError') {
      console.log('用户取消了设备选择');
    }
  }
}

这里有个细节：filters是数组，数组里每一项是"或"的关系，匹配任意一项就展示。如果不传任何过滤条件，浏览器会把当前系统上所有可访问的USB设备全部列出来，生产环境下通常不这么干，用户体验太差。

3.3 打开设备、选择配置、声明接口

拿到设备对象后，按顺序做三件事：

javascript复制async function openDevice() {
  // 1. 打开设备，相当于建立会话
  await device.open();

  // 2. 选择配置。大多数设备只有一套配置，取第一个即可
  //    如果你的设备有多个配置，要根据需求选
  const config = device.configurations[0];
  await device.selectConfiguration(config.configurationValue);

  // 3. 声明接口。接口，通常取第一个
  const interface = config.interfaces[0];
  await device.claimInterface(interface.interfaceNumber);

  console.log('设备已就绪');
}

selectConfiguration这一步很坑，因为多数设备的PDF手册根本不会写配置编号。稳妥做法是枚举device.configurations，挑第一个就够用。声明接口时，如果设备被其它程序占用，比如串口工具已经打开了这个设备，claimInterface会直接抛错。所以调试时务必先关掉所有占用设备的程序。

3.4 发送数据：找到正确的OUT端点

USB的每一个端点都有一个方向和一个端点号，WebUSB的端点对象上有direction属性，值为"in"或"out"。发送数据就要找到方向为"out"的那个端点：

javascript复制function getOutEndpoint(interface) {
  for (const endpoint of interface.alternate.endpoints) {
    if (endpoint.direction === 'out') {
      return endpoint;
    }
  }
  throw new Error('没有找到OUT端点');
}

async function sendData(data) {
  const endpoint = getOutEndpoint(device.configurations[0].interfaces[0]);
  // 注意：transferOut的第一个参数是端点号，不是端点对象
  const result = await device.transferOut(endpoint.endpointNumber, data);
  console.log(`已发送 ${result.bytesWritten} 字节`);
}

transferOut的第二个参数，可以传BufferSource，比如Uint8Array。如果你要发送文本，先做编码：

javascript复制const encoder = new TextEncoder();
await sendData(encoder.encode('AT+RESET\r\n'));

3.5 接收数据：transferIn和inputreport两种姿势

接收数据有两条路。第一是主动轮询，调用transferIn(endpointNumber, bufferSize)，第二个参数是缓冲区长度，不是要读的字节数，最多一次性读这么多过来：

javascript复制async function readData() {
  const endpoint = getInEndpoint(device.configurations[0].interfaces[0]);
  const result = await device.transferIn(endpoint.endpointNumber, 64);
  const decoder = new TextDecoder();
  const text = decoder.decode(result.data);
  console.log('收到数据：', text);
  return text;
}

注意，设备上报数据不是"有就立刻到"的，transferIn会一直挂起等待直到设备真的有数据送过来，所以通常配合Promise来做超时处理，避免界面一直挂死。

第二是针对中断传输类型和HID类设备的监听方式，用inputreport事件：

javascript复制device.addEventListener('inputreport', (event) => {
  if (event.endpointNumber === inEndpointNum) {
    const data = new Uint8Array(event.data.buffer);
    handleReport(data);
  }
});

如果设备是自定义设备，一般用transferIn；如果是HID类的报表设备（比如扫码枪、键盘），一般走inputreport事件。

3.6 断开与重连：别把设备状态焊死在页面上

拔线这件事在用户手里稀松平常，但代码必须设计好。WebUSB提供了disconnect事件，设备断开时触发，同时device对象的opened属性会变成false：

javascript复制navigator.usb.addEventListener('disconnect', (event) => {
  if (event.device === device) {
    console.log('设备已断开');
    // 更新UI状态，禁用发送按钮等
  }
});

重连的逻辑我一般这样设计：页面上放一个"连接设备"按钮，点击后先调用navigator.usb.getDevices()拿到当前页面之前授权过的设备列表，如果有就直接open()，没有才走requestDevice()让用户重新选：

javascript复制async function reconnect() {
  const devices = await navigator.usb.getDevices();
  if (devices.length > 0) {
    device = devices[0];
    await openDevice();
  } else {
    await connectUSB();
  }
}

这个设计可以显著减少"每次刷新页面都要重新弹窗选设备"的烦躁感，尤其是自动化产线场景下，一天开关机几十次，体验差距很大。

4. 我实际项目中踩过的五个WebUSB的坑

这部分是我的经验重点。WebUSB的API长得不算复杂，但实际用起来有不少隐蔽的坑。我按踩坑顺序盘点一下，每一个都是真金白银换来的。

4.1 坑一：在Electron或内嵌WebView里，navigator.usb为什么是undefined？

有段时间我在做桌面端工具，觉得Electron能直接复用WebUSB代码，省得再写一套Node原生通信。结果在Electron主进程里打开页面，navigator.usb一直是undefined。查了才发现，Electron默认nodeIntegration和contextIsolation等配置会影响部分Web API的暴露，而且WebUSB这种API在Electron的某些版本里默认没有启用。

解决方案有两个方向：一是把USB通信下沉到主进程，用webContents.session.setDevicePermissionHandler和select-usb-device等事件去处理授权和转发；二是直接改用node-usb这类Node原生模块，不走浏览器API。如果你只是想在桌面端包装一个网页工具，我建议直接走方案二，省心很多。Electron下强行桥接WebUSB，权限会话管理复杂，收益又不大。

4.2 坑二：claimInterface报"Access denied"，但设备明明没被占用

这个问题的根源，很多时候在selectConfiguration之后没有等一下，设备还没就绪就去抢占接口。USB协议层有自己的枚举和初始化时序，你在代码里连续执行open()、selectConfiguration()、claimInterface()三步，操作系统可能还没把接口的驱动绑定完成。

我后来在每次selectConfiguration之后加了一个await new Promise(r => setTimeout(r, 100))，问题就消失了。听起来很玄学，但USB设备的启动延迟是真实存在的。当然，更好的做法是监听设备状态变化或者轮询读取设备状态寄存器，但100毫秒延时的成本几乎为零，优先用它解决。

4.3 坑三：端点的方向搞反了，transferOut一直说不存在

USB协议很严谨：端点号相同、方向不同的两个端点，是两个完全独立的端点。比如端点号是0x01，那它同时可能有0x01 OUT和0x81 IN（高位bit表示方向）。WebUSB的端点枚举里，这两个端点是分开列出的。

我之前在一个设备上，固件手册里写"端点1发送数据"，我顺理成章去找endpointNumber === 1的端点，结果发现方向是in。后来把设备描述符导出来一看，才知道该设备是端点1 OUT、端点2 IN。很多廉价设备的固件为了省资源，端点编号并不连续，千万不要依靠"猜"来选端点，一定要遍历interface.alternate.endpoints，把每个端点的endpointNumber和direction都打印出来，再写死选择逻辑。

4.4 坑四：transferIn挂起后，设备拔掉，Promise永远不resolve

这是个非常容易让页面崩溃的坑。假设你调用了一次transferIn等待设备数据，这时用户拔掉了USB线。disconnect事件虽然触发了，但那个挂起的transferIn Promise不会自动reject，它会一直卡在那里。如果你之后又调用了close()，可能还会抛一个NotFoundError。

我的处理方式是在disconnect事件里，手动打断所有的挂起等待。用一个AbortController或者一个标志位，在transferIn外层包一层竞速逻辑：

javascript复制function withTimeout(promise, ms = 5000) {
  return Promise.race([
    promise,
    new Promise((_, reject) =>
      setTimeout(() => reject(new Error('读数据超时')), ms)
    )
  ]);
}

async function safeRead() {
  try {
    const result = await withTimeout(device.transferIn(inEp, 64), 3000);
    return result;
  } catch (err) {
    if (err.message === '读数据超时') {
      console.log('这次读取超时，忽略即可');
    }
  }
}

这个方式虽然不能解决Promise永不resolve的底层问题，但至少保证了前端代码不会因为一次拔线就整体卡死，用户刷新页面就能恢复正常。

4.5 坑五：Android Chrome上的行为差异

WebUSB在Android Chrome上是支持的，但移动端和桌面端的行为差异很大。首先是设备列表：Android上USB主机接口很少，绝大多数手机只有Type-C口直连设备时才弹窗；如果你的设备走的是OTG转接，部分安卓机型在协议协商上会有兼容性问题。其次是界面：桌面端的授权弹窗是居中弹窗，Android端则是底部弹出的模态框，而且对连接不稳定的廉价设备，弹窗经常出现设备突然消失的情况。

我的建议是：如果目标用户里有移动端，一定要在真机上测几轮再交付。开发时可以用navigator.usb.getDevices()做自动重连，减少用户反复插拔授权的痛苦，但不要在安卓上对USB枚举速度抱太高期望。

5. 选型对比：WebUSB、WebHID、Web Serial到底该用哪个

做硬件通信的前端方案，其实不只WebUSB一个选择。这几年浏览器陆续推出了Web Serial（串口）、WebHID（人机交互设备）、Web Bluetooth（蓝牙）。很多开发者一开始就搞混，不知道自己的设备该用哪个API。我把这几个API做个横向对比。

看到这里你就明白了，选型的第一原则是：先看设备属于哪一类协议，再选API，而不是反过来。

如果你的设备是标准HID类的，比如USB扫码枪、USB指纹采集器，优先考虑WebHID。它的API比WebUSB更上层一点，直接操作用户能看懂的报告数据，不需要自己组装USB传输包。WebHID还提供hidinputreport事件，设备一有数据就推过来，省得你自己轮询transferIn，代码量少很多。

如果你的设备本质上是个串口，只是通过USB转串口芯片（CH340、CP2102、FT232）接出来的，那用Web Serial更合适。你只需要指定波特率和数据位，直接读写"像流一样"的数据，不用理解端点、配置、接口这些USB概念。而且Web Serial还支持蓝牙串口（RFCOMM），在有些场景下比USB更灵活。

但如果你的设备是裸的USB自定义设备——比如自研的USB数据采集卡、USB继电器控制板、USB自定义加密芯片，没有现成的类驱动适配，那就是WebUSB的主场。这些设备在系统里显示为"未知设备"或"vendor-specific"设备，只有WebUSB能直接操作协议层的端点通道。

还有一个容易被忽略的坑：驱动绑定关系会影响API选择。比如同一台USB设备，在Windows上被HID驱动绑定了，你用WebUSB就发现不了它；只有被WinUSB或系统判定为vendor-specific时，WebUSB才能用。所以做方案前，建议先在目标操作系统上插上设备，然后在Chrome的chrome://device-log里看看系统实际识别成了什么类型。这一步花五分钟，能省掉后面几天的返工。

6. 一些收尾的实操心得

写到这里，WebUSB的核心实践基本都过了一遍。如果你正在评估自己的设备能不能上WebUSB，我建议你先按这三个步骤走一遍：第一，在系统设备管理器里确认设备类型是不是vendor-specific或者WinUSB绑定；第二，在Chrome里跑一个简单的navigator.usb.requestDevice，看看设备能不能出现在选择列表里；第三，把上一节的完整示例代码跑通，确认端点和传输类型没搞错。这三步最快半小时就能给出结论，比翻完整个协议手册再动手要高效得多。

关于这套API的未来，我个人持乐观态度。虽然苹果Safari至今没有实现，Firefox也一直处于实验阶段，但在工业调试、产线测试、IoT设备配置这些垂直场景里，Chromium内核的浏览器已经是事实标准。与其抱怨兼容性，不如在架构设计上做一次隔离：通信层封装成独立模块，后面如果WebUSB不可用，可以无缝切换到Web Serial或者WebSocket中转方案，前端业务代码完全不用动。我现在的项目基本都是这个结构，效果很好。

最后分享一个小技巧：调试WebUSB时，别只盯着DevTools的Console。打开chrome://device-log，可以看到系统级的USB事件日志——连接、断开、枚举失败、驱动绑定失败，全都有记录。很多WebUSB的诡异问题，其实根源在操作系统驱动层面，Browser Console里看不到任何线索，但chrome://device-log会把真相直接摆在你面前。这算是我调试USB类问题最常用也最容易被忽略的一招。