HTML实现蓝牙设备连接页面的Web Bluetooth小技巧

在进行Web Bluetooth开发时，尤其是使用Chrome浏览器，开发者常常会遇到几个“典型”的陷阱。虽然代码完全遵循文档编写，但设备却始终无法连接，或者频繁弹出令人困惑的错误信息。遇到这种情况不必急于否定自己，绝大多数时候问题并非出在代码逻辑上，而是源于一些极易被忽视的环境与配置细节。以下列出几个高频问题，相信你也曾遇到过。

Web Bluetooth API 在 Chrome 中无法调用 navigator.bluetooth

首先需要明确的是：这并非你的代码编写有误，而是运行环境未达标。Web Bluetooth API 出于安全考虑，强制要求运行在 HTTPS 或本地环回地址（localhost）下。如果你在普通的 HTTP 页面上尝试调用，navigator.bluetooth 会直接返回 undefined。

开发阶段使用 http://localhost:8080 一切正常，但一旦部署到线上非 HTTPS 的域名，这个 API 就会“凭空消失”。以下是几个常见的踩坑点：

• 本地文件直接打开：双击打开一个 HTML 文件（file:// 协议），navigator.bluetooth 必定是 undefined。
• 开发服务器配置：不要误以为 Vite 或 Webpack Dev Server 默认开启了 HTTPS，它们默认使用的是 HTTP。你需要显式配置 https: true 或者用 --https 参数启动。
• GitHub Pages 的陷阱：GitHub Pages 自身提供 HTTPS 支持，但如果你使用了自定义域名且未开启“强制 HTTPS”选项，页面可能回退到 HTTP 协议，从而导致 API 不可用。

调用 requestDevice() 后页面卡住或无响应

点击按钮后浏览器界面仿佛无响应，或者压根没有弹出设备选择窗口？这通常是权限设置与过滤器配置不当的典型表现。

请务必注意，requestDevice() 必须由用户手势（例如 click、tap）触发，并且默认不会展示任何设备——你需要明确告知浏览器希望扫描什么样的设备。

关键在于传入有效的 filters 或设置 acceptAllDevices: true：

• 只传一个空对象 {} 或空数组，浏览器很可能什么都不做（在 Android Chrome 上尤其突出）。
• 如果想扫描所有 BLE 设备，至少需要加上 acceptAllDevices: true。不过请注意，iOS Safari 不支持此选项，且部分安卓厂商也会对这种宽泛的扫描施加限制。
• 更常见的做法是连接特定设备，使用 filters 进行过滤，例如按名称前缀：filters: [{ namePrefix: "MySensor" }]，或按服务 UUID：filters: [{ services: ["battery_service"] }]。
• 还有一个关键步骤：成功选择设备后，必须调用 device.gatt.connect() 建立实际连接，之后的所有读写操作才能正常进行，否则后续每一步都会失败。

characteristic.readValue() 报错 NetworkError 或 UnknownError

当遇到 NetworkError 错误时，切勿误判为网络故障，这通常是 GATT 通信链路未就绪导致的。进行 BLE 读写操作之前，必须满足以下三个前提：

• 连接状态为真：device.gatt.connected === true。
• 已成功获取目标服务：service = await device.gatt.getPrimaryService("your_service_uuid")。
• 已成功获取目标特征值，并且确认该特征支持读操作：characteristic = await service.getCharacteristic("your_char_uuid")，且 characteristic.properties.read === true。

有一个容易被忽略的细节：某些设备要求必须先调用 characteristic.startNotifications() 开启通知，才允许执行读取；或者需要先向特定的客户端特征配置描述符（例如 0x2902）写入启用指令（例如 0x0100）。遇到疑难问题时，建议先用 nRF Connect 这类专业 App 验证设备的实际行为，然后在代码中进行对应实现。

Android Chrome 连不上设备，但桌面 Chrome 可以

这是平台差异的典型表现。Android 端对 Web Bluetooth 的限制比桌面版严格得多：

• 触发环境：从 Chrome 89 开始，requestDevice() 必须在顶层浏览上下文（即不能嵌套在 iframe 中）中由用户手势触发。
• 系统权限：Chrome 本身不会主动申请系统级的蓝牙扫描权限。在 Android 上，蓝牙扫描需要“位置信息”权限（因为系统使用位置服务来辅助蓝牙发现）。用户必须手动进入「设置 > 应用 > Chrome > 权限」，开启“位置信息”权限。

调试时可参考以下建议：

• 确认手机已同时开启蓝牙和定位服务（即使你不需要 GPS 功能）。
• 检查手机是否开启了省电模式，或者将 Chrome 加入了后台限制名单，这可能会中断蓝牙操作。
• 尽量避免使用精确的 name 过滤（如 { name: "ABC" }），因为设备广播的名称可能被截断。改用 namePrefix 或 services 过滤更可靠。
• 某些深度定制的国产手机系统（如 MIUI、EMUI）会对后台 BLE 扫描有额外限制。进行真机测试时，最好能用原生 Android 或 Pixel 设备做交叉验证。

总而言之，Web Bluetooth 并非一个“一次写完，到处运行”的接口。设备兼容性、系统策略、运行时权限这三者缺一不可。最稳妥的开发习惯是：对每一步操作都检查返回值，为每一个 Promise 添加 catch 处理，并且把 console.error 中输出的具体错误码（例如 "GATT operation not permitted"）当作排查问题的关键线索。