Web 蓝牙连接失败？三步快速排查浏览器兼容性与设备配对难题

连不上。

真的，那种点击“扫描”后屏幕一片死寂的挫败感，搞过 Web Bluetooth 的人都懂。

你以为代码写得天衣无缝，逻辑严丝合缝，结果浏览器直接甩给你一个 NotFoundError 或者干脆没反应。这时候别急着去重构你的 JavaScript 异步流程，也别忙着怀疑人生。很多时候，问题压根就不在你那几百行精心编写的业务逻辑当中，而是卡在了浏览器权限、系统底层协议栈或者是那个该死的设备广播包上。

咱们今天不聊那些虚头巴脑的理论架构，直接上手。

就像你在机房里跟同事蹲在地上查线一样，我们借助几个现成的在线工具，把那些隐藏在表象之下的故障根源给揪出来。无需安装任何额外的驱动程序，也不用把开发环境搞得一团糟，只要打开浏览器，就能开展对连接故障的深度诊断工作。

第一步：把浏览器的“嘴”撬开，确认它到底有没有在说话

很多开发者遇到的第一个坑，就是误以为自己的代码没执行。

其实不是。

是浏览器根本就没打算让你去扫描设备。Web Bluetooth API 可不是你想用就能用的，它被牢牢地锁在 HTTPS 的安全沙箱里，并且需要用户显式地进行授权操作。要是你连这个前置条件都没满足，后续所有的调试工作都是在浪费生命。

先别管你的业务代码。

找一个纯粹的、只负责调用 navigator.bluetooth.requestDevice 的在线测试页面。这种页面通常没有任何复杂的 UI 干扰，就是把原生的 API 能力赤裸裸地暴露出来。

当你在这个页面上点击扫描按钮时，仔细盯着浏览器的地址栏或者弹窗提示看。

要是连设备选择对话框都弹不出来，那就说明问题出在权限层面。

你要知道，Chrome 以及其他基于 Chromium 内核的浏览器，对于本地文件协议 file:// 是默认禁用蓝牙访问的。你必须得把项目部署在本地服务器 localhost 上，或者配置好有效的 SSL 证书通过 https 协议来开展访问工作。这一点经常被忽视，导致很多人在本地开发阶段就卡住了，还以为是硬件坏了。

还有那个容易被遗忘的细节：实验性功能开关。

虽然现在的稳定版浏览器大多已经原生支持了，但在某些旧版本或者特定的企业策略管控环境下，你可能还得手动去 chrome://flags 里面把 #enable-web-bluetooth-new-permissions-backend 这类标志位给开启才行。把这个开关当作一把钥匙，只有插进去了，浏览器才会允许你去进行设备的发现工作。

如果对话框出来了，但是列表里空空如也，那咱们就得进入下一个环节了。

第二步：剥离业务逻辑，直接审视设备广播的真实面貌

这时候，最让人抓狂的情况发生了：手机能搜到，Native 应用能连上，唯独网页端像个瞎子。

这通常不是浏览器的问题，而是设备广播策略跟你设定的过滤条件不契合。

Web Bluetooth API 的设计哲学就是隐私优先。它不允许网页随意扫描周围的所有设备，你必须明确告诉浏览器你要找谁。这个“找谁”的依据，就是 filters 参数里的服务 UUID 或者设备名称。

很多物联网设备为了省电，或者出于厂商的自定义规范，它们在广播包里藏得很深。

有的设备根本不广播完整的服务 UUID，只广播一个厂商自定义的数据段。这时候，如果你还在代码里傻傻地等着匹配某个标准的服务 UUID，那永远也匹配不上。这就好比你去火车站接人，手里举着对方的身份证号，可对方只穿了件红衣服，你们当然遇不见。

借助通用的蓝牙扫描工具网页，你可以绕过你自己写的过滤逻辑，直接查看原始的设备广播数据。

把这些在线工具当作一个透明的透视镜。

你会发现，原来那个你以为会广播 0x180F (电池服务) 的设备，实际上只在广播数据里塞了一串私有的 Hex 字符串。或者，设备的名称被截断了，导致你用 namePrefix 去匹配的时候，因为长度不够而直接失败。

一旦看到了真实的广播内容，你就知道该怎么调整你的 filters 配置了。

是把匹配条件从 services 改成 namePrefix？还是说需要利用 acceptAllDevices: true 配合 optionalServices 来强制获取权限？这些决策，都得基于你亲眼看到的广播包结构来制定。不要猜，猜出来的配置全是坑。

有时候，设备本身也有点小脾气。

有些低功耗蓝牙 (BLE) 设备在进入深度睡眠后，广播间隔会变得极长，甚至完全停止广播，直到被特定的手势唤醒。你在网页上点扫描的那几秒钟，可能刚好错过了它的广播窗口。这种情况下，你得让硬件同事去调整固件的广播策略，或者在用户界面上增加更明显的“请唤醒设备”的提示信息。

第三步：验证数据传输通道，确保连接不仅仅是“连上了”

能搜到，也能配对，是不是就万事大吉了？

远没有。

真正的噩梦往往发生在连接建立之后的第一次数据读写操作中。你调用了 getPrimaryService，拿到了服务对象，接着去获取特征值 (Characteristic)，结果抛出了一个 SecurityError 或者 InvalidAccessError。

这说明什么？

说明权限没给够。

Web Bluetooth 的安全模型非常严格。你在连接时声明需要的服务，只是获得了连接的权利。要是你想读取或写入某个特定的特征值，而这个特征值所属的服务并没有在初始的 filters 或者 optionalServices 列表中明确声明，浏览器就会毫不留情地阻断你的操作。

这时候，你需要再次回到那个简单的测试工具中去。

尝试在连接成功后，立刻对目标特征值进行读取或写入测试。不要夹杂任何业务逻辑，就是单纯地发个指令，看看能不能通。

要是这里失败了，检查你的代码是不是漏掉了 optionalServices 的配置。这是一个极其常见的失误。很多开发者以为只要在 filters 里写了主服务就行，却忘了那些用于通信的次要服务必须显式地添加到可选列表当中，否则浏览器会认为你没有资格去触碰它们。

还有一种情况，就是 MTU (最大传输单元) 的问题。

不同的操作系统和蓝牙栈对 MTU 的支持程度不一样。要是你一次性往设备里塞了太大的数据包，超出了协商好的 MTU 限制，传输就会静默失败或者报错。这时候，你得把数据进行分片处理，或者在发送前先去查询一下当前连接的 MTU 大小，据此来调整单次写入的数据长度。

这个过程就像是疏通水管。

你得一段一段地试，看看水到底流到哪里堵住了。是阀门没开（权限问题），还是管子太细（MTU 限制），亦或是水压不够（信号强度弱）。

别让兼容性成为你的拦路虎

最后还得提一嘴浏览器的差异性。

虽然 Chromium 阵营对 Web Bluetooth 的支持已经相当成熟了，但 Firefox 和 Safari 的态度就比较暧昧了。特别是 Safari，在 macOS 和 iOS 上的支持进度一直是个谜。要是你的目标用户群体里有很多苹果设备使用者，那你可能得提前做好心理建设，甚至要考虑降级方案，比如引导用户下载专用的 App 来进行配对工作。

别指望一套代码走天下。

在实际的项目交付当中，我们通常会做一个特性检测。在页面加载的时候，先判断 navigator.bluetooth 是否存在。要是没有，那就直接隐藏相关的功能入口，或者弹出一个友好的提示框，告诉用户换个浏览器试试，而不是让程序在控制台里报一堆看不懂的错。

这不仅是技术上的必要措施，更是用户体验层面的基本素养。

排查 Web Bluetooth 的连接问题，本质上就是一个不断缩小范围的过程。

从浏览器的权限设置，到设备广播的真实内容，再到具体的服务与特征值权限，每一步都需要你把那些抽象的代码逻辑具象化，借助工具去“看见”那些看不见的无线电波交互过程。

下次再遇到连不上的情况，别慌。

把那复杂的业务逻辑先放一边，用最原始的工具去进行最直接的对话。很多时候，答案就在那个被你忽略的广播包字段里，或者在那行不起眼的 optionalServices 配置当中。

毕竟，解决问题的关键，往往不在于你写了多少代码，而在于你是否真正理解了设备与浏览器之间那场微妙而又严格的握手协议。