WebUSB与WebBluetooth设备连接教程

本文深入解析了WebUSB与WebBluetooth在浏览器中安全连接硬件设备的核心机制与实战要点，强调二者均强制依赖用户显式授权和安全上下文（HTTPS/localhost），绝无绕过权限的可能；详细拆解了WebUSB三大硬性条件（HTTPS/localhost、用户手势触发、精准设备过滤）和WebBluetooth四大常见连不上原因（系统蓝牙状态、权限弹窗拦截、设备可见性、过滤匹配），并通过对比通信模型、数据读写路径、断开清理方式及重连限制，揭示了二者本质差异——WebUSB面向底层字节流，适合高吞吐场景；WebBluetooth基于GATT协议，天然适配低功耗通知，但受BLE规范严格约束；无论是调试Arduino还是对接心率传感器，忽略这些设计原则都将导致连接失败或运行异常，堪称前端接入物理世界的必读安全与实践指南。

WebUSB 和 WebBluetooth 不能“直连”——它们必须经过用户显式授权，且只在安全上下文（HTTPS 或 localhost）中可用。浏览器强制介入权限流程，不是技术限制，而是安全模型的核心设计。跳过这一步的所有尝试都会失败。

WebUSB 连接设备前必须解决的三个硬性条件

缺一不可，否则 navigator.usb.requestDevice() 会直接抛出 SecurityError 或静默拒绝：

• 页面必须运行在 HTTPS 协议下（生产环境），或 localhost（开发时允许）
• 用户必须主动触发连接动作（比如点击按钮），不能在页面加载时自动调用 requestDevice()
• 目标 USB 设备需在 filters 中明确声明厂商 ID（vendorId）和/或产品 ID（productId），否则 Chrome 会过滤掉未匹配的设备

示例过滤器写法：

const device = await navigator.usb.requestDevice({  
  filters: [{ vendorId: 0x2341, productId: 0x0043 }] // Arduino Uno  
});

WebBluetooth 扫描不到设备？先检查这四件事

常见现象是 requestDevice() 返回空列表，或报错 NotFoundError。根本原因往往不在代码，而在环境配置：

• Windows/macOS 必须开启系统级蓝牙（不只是硬件开关），且设备处于“可被发现”模式（很多 BLE 模块默认关闭该功能）
• Chrome / Edge 要求站点有 bluetooth 权限，首次请求时弹窗可能被广告拦截器或扩展屏蔽
• 设备广播的 name 或 service UUID 必须与 filters 中声明的一致；若用 acceptAllDevices: true，部分 Android 设备仍会因系统策略返回空
• Mac 上 Safari 完全不支持 WebBluetooth；Windows 上旧版 Edge（非 Chromium 内核）也不支持

正确写法示例（按服务 UUID 过滤）：

await navigator.bluetooth.requestDevice({  
  filters: [{ services: ['heart_rate'] }],  
  optionalServices: ['battery_service']  
});

连接后读写数据的实际路径差异

WebUSB 和 WebBluetooth 的通信模型完全不同，不能套用同一套逻辑：

• WebUSB 面向的是通用 USB 接口，需手动处理配置、接口、端点，再调用 transferIn()/transferOut() 收发原始字节流；Arduino 类设备通常走 CDC ACM 类，得自己解析串口协议
• WebBluetooth 基于 GATT，必须先 getPrimaryService()，再 getCharacteristic()，最后用 readValue() 或 writeValue() —— 所有操作都是异步 Promise，且 characteristic 可能带属性（read、notify、write）限制
• WebUSB 数据吞吐量更高，适合传感器批量采样；WebBluetooth 天然支持 notify，适合低功耗心跳上报，但单次 write 建议控制在 20 字节内（BLE MTU 限制）

容易忽略的一点：WebBluetooth 的 characteristic.addEventListener('characteristicvaluechanged', ...) 必须在 startNotifications() 成功后才生效，否则监听无效。

断开连接不是“关闭”，而是释放引用 + 清理监听

用户关掉标签页或刷新页面时，浏览器会自动终止连接，但主动断开需要手动处理：

• WebUSB：调用 device.close()，否则下次 requestDevice() 可能返回已打开但未关闭的设备实例，导致 USBTransferError
• WebBluetooth：调用 device.gatt.disconnect()，同时移除所有 characteristicvaluechanged 监听器，否则内存泄漏风险高
• Edge 浏览器中，USB 设备需在地址栏点击“网站信息”图标手动删除；蓝牙设备则点“刷新”图标断开 —— 这些是 UI 层行为，不影响 JS 层的 close() 或 disconnect() 调用

真正复杂的是设备重连逻辑：WebUSB 没有自动重连机制，需监听 connect 事件并重新枚举；WebBluetooth 的 gattserverdisconnected 事件触发后，必须等用户再次点击才能重新 requestDevice() —— 浏览器不允许后台静默重连。

到这里，我们也就讲完了《WebUSB与WebBluetooth设备连接教程》的内容了。个人认为，基础知识的学习和巩固，是为了更好的将其运用到项目中，欢迎关注golang学习网公众号，带你了解更多关于的知识点！