#WebBluetoothAPI实战:在浏览器里直连蓝牙设备(requestDevice与GATT服务读写)去年冬天那次晨会,我到现在还记得清清楚楚。产品经理往白板前一站,特别轻描淡写地来了一句:「安卓端、iOS端、小程…
Web Bluetooth API 实战:在浏览器里直连蓝牙设备(requestDevice 与 GATT 服务读写)
Web Bluetooth API 实战:在浏览器里直连蓝牙设备(requestDevice 与 GATT 服务读写)
去年冬天那次晨会,我到现在还记得清清楚楚。产品经理往白板前一站,特别轻描淡写地来了一句:「安卓端、iOS 端、小程序端都能连咱们的蓝牙手环了,Web 端是不是也能搞一下?」我当时坐在工位上,手里那杯咖啡刚端起来,听到这句差点没喷出来。
说实话,我第一反应是「这不可能吧」。在我的固有认知里,蓝牙这种硬件级别的东西,向来是原生 App 的专属地盘——你要么用 Android 的 BluetoothAdapter,要么用 iOS 的 CoreBluetooth,再不济用小程序那一套封装好的 wx 接口。浏览器?浏览器能干的活儿不就是发发请求、渲染渲染页面吗,还能隔空去摸硬件?我当时甚至还想当然地跟产品经理说:「这个得装个插件或者下个客户端吧,纯网页搞不定。」现在回头看,这句话暴露了我对现代浏览器能力的一无所知。
结果打脸来得特别快。我回去一查资料才知道,原来早在 Chrome 56 时代,浏览器就提供了一个叫 Web Bluetooth API 的东西,能让网页在用户授权的前提下,直接跟周围的蓝牙低功耗(BLE)设备通信。不用装驱动,不用下 App,不用插 USB 线,一串 navigator.bluetooth打头的代码就能弹出系统的设备选择器,选中之后就能读写设备上的数据。那种感觉就像你一直以为自家小区只有楼梯,某天突然发现墙后头藏着一部电梯——还是直通顶楼的那种。
于是我信心满满地开工了。然后,就没有然后了。接下来的一周,我经历了一连串现在想起来都想笑的坑:页面在 localhost 上跑得好好的,一部署到测试环境的 HTTP 地址上就彻底失灵;设备选择器弹出来了,周围明明有一堆蓝牙设备,死活一个都扫不出来;好不容易连上了,读取特征值又返回一堆看不懂的 DataView 字节;最要命的是,设备动不动就自己断开,重连逻辑写得我怀疑人生。那天下午我对着屏幕挠头挠了三个小时,头发都薅下来好几根,最后在系统的蓝牙设置里瞎点,才发现问题出在一个我压根没想到的开关上。
所以这篇东西,我不想写成那种干巴巴的 API 说明书。我更想把它写成一份「踩坑日记」——把我实际遇到过的困惑、误判和恍然大悟都摊开来讲,再配上能直接抄走改的代码。如果你也正准备在网页里接蓝牙设备,希望我踩过的这些坑,你能一个都别踩。
顺便说一句,浏览器原生能力这两年真的是突飞猛进。除了今天要聊的蓝牙,像加密、音视频编解码这些以前必须依赖第三方库才能做的事,现在浏览器自己就能干。我之前写过一篇Web Crypto API 实战:用浏览器原生 SubtleCrypto 做加密、哈希与密钥管理(AES-GCM 与 RSA),讲的就是浏览器内置的加密能力;还有一篇WebCodecs API 实战:用浏览器原生 VideoEncoder/VideoDecoder 做音视频编解码(帧处理与封装),说的是原生编解码。这些 API 有个共同点:都是「浏览器自己长出来的能力」,用好了能省掉一大堆依赖。今天这篇蓝牙,也是这个思路。
先别急着写代码,搞清楚它到底能在哪跑
我踩的第一个大坑,其实跟代码一行关系都没有。
当时我把示例.demo 页面丢到测试服务器上,用手机和笔记本分别打开,结果两个设备都跟没反应一样——navigator.bluetooth直接是undefined,连报错都懒得报。我一开始还以为是设备蓝牙没开,重启了蓝牙、重启了电脑、甚至怀疑是不是我那台笔记本的蓝牙适配器坏了。折腾大半天,最后才发现:Web Bluetooth API 要求页面必须运行在安全上下文(secure context)里。
什么叫安全上下文?简单说就是 HTTPS,或者本地开发时的 http://localhost、http://127.0.0.1。你把它部署到一个普通的 http 站点上,浏览器直接把这个 API 给你藏起来,连个提示都不给。这一点特别坑,因为本地开发时你用的就是 localhost,一切正常,你会以为万事大吉,直到部署上线才傻眼。所以记住:部署必须上 HTTPS,没有商量余地。
除了安全上下文,还有几个硬性前提,我一次性列清楚,省得你像我一样一个个试:
- 浏览器得支持。目前基本只有基于 Chromium 内核的浏览器支持,Chrome、Edge、Opera 都行,桌面端和安卓端都可以。但 Safari(包括 iOS Safari)和 Firefox 到目前为止都不支持,且短期内看不到支持的迹象。这意味着 iPhone 用户直接无缘——如果你的业务面向大众消费者,这一点可能是致命的,得提前想好降级方案。
- 用户设备得有蓝牙适配器,而且蓝牙得开着。台式机很多时候是没有蓝牙模块的,调试时你可能得插个 USB 蓝牙适配器。
- 必须由用户手势触发。也就是说,扫描设备这个动作必须放在点击按钮之类的事件里,你不能在页面加载时偷偷扫描——这是隐私保护的硬性要求。
- 权限策略(Permissions Policy)不能把它禁掉。如果页面嵌在 iframe 里,还可能受
bluetooth这条权限策略的限制。
我习惯在动手之前先做一层能力检测和权限查询,代码大概长这样:
js// ===== Web Bluetooth 能力检测与权限预检 =====async function checkBluetoothSupport() { // 1. 先看浏览器到底有没有暴露这个 API // 如果不支持,navigator.bluetooth 会是 undefined if (!navigator.bluetooth) { throw new Error('当前浏览器不支持 Web Bluetooth,建议使用 Chrome 或 Edge'); } // 2. 再看设备本身有没有蓝牙适配器、蓝牙是否开启 // getAvailability() 返回 true 才代表硬件层面可用 const available = await navigator.bluetooth.getAvailability(); if (!available) { throw new Error('未检测到可用的蓝牙适配器,请确认蓝牙已开启'); } // 3. 通过 Permissions API 查询 bluetooth 权限状态 // 状态可能是 'granted'(已授权)、'denied'(已拒绝)、'prompt'(待询问) const permission = await navigator.permissions.query({ name: 'bluetooth' }); if (permission.state === 'denied') { throw new Error('蓝牙权限已被拒绝,请在浏览器设置里手动开启'); } return { available, permissionState: permission.state };}// 页面加载时先跑一遍,把结果展示在界面上checkBluetoothSupport() .then(info => console.log('蓝牙环境 OK:', info)) .catch(err => console.error('蓝牙环境异常:', err.message));

这段代码里,我最想强调的是第 3 步的 navigator.permissions.query({ name: 'bluetooth' })。很多人(包括最开始的我)压根不知道还能提前查权限状态,每次都是直接甩一个requestDevice()出去碰运气。其实提前查一下permission.state,如果是denied,你就能提前给用户一个明确的提示,而不是让用户对着一个没反应的按钮干瞪眼。这个体验差别,在真实项目里非常明显。
关于浏览器兼容性的最新情况,建议直接看MDN 的 Web Bluetooth API 文档和caniuse 的兼容表,这两个地方更新得比较及时。规范本身可以看W3C / Web Bluetooth Community Group 的官方文档。我第一次看官方文档的时候,因为英文实在太烂,对着transient activation这种词愣了半天,后来才反应过来它就是「用户手势」的另一种说法——血泪教训,英语不好的朋友可以先看中文社区资料补补概念,再回头啃文档。
requestDevice 与过滤条件:我在这儿栽了整个下午
能力检测通过之后,就到了设备发现这一步,核心就是navigator.bluetooth.requestDevice()。这个方法会弹出一个系统级的设备选择器,让用户手动挑一个设备——注意,网页自己是不能静默扫描并连接设备的,选择权永远在用户手里,这也是隐私设计的一部分。
最简单的写法是不加任何过滤,接受所有设备:
js// 弹出选择器,展示周围所有可发现的 BLE 设备// acceptAllDevices: true 表示不过滤,全部列出来const device = await navigator.bluetooth.requestDevice({ acceptAllDevices: true, // 注意:如果用了 acceptAllDevices,通常仍需在 optionalServices 里 // 声明你后续要访问的服务 UUID,否则连接后 getPrimaryService 会失败 optionalServices: ['battery_service']});console.log('用户选中的设备:', device.name, device.id);
就是这个看似人畜无害的acceptAllDevices: true,让我栽了整整一个下午。当时项目部署完,测试同学拿着她那台笔记本跑,周围明明有十几台蓝牙设备,选择器弹出来却空空如也,一个设备都不显示。我一会儿百度一会儿谷歌,搜了各种「Web Bluetooth 扫不到设备」的帖子,全都是让我检查 HTTPS、检查 filters,可我这边明明都对了。那天下午就这么耗过去了,一点头绪没有。
最后是我实在没辙,跑去翻 Windows 的系统蓝牙设置,瞎猫碰死耗子,发现有一个「允许蓝牙设备发现此电脑」之类的开关没打开。勾上之后,回到页面再试,设备唰地一下全出来了。我当时那个心情,真的是又想笑又想哭——笑的是问题这么简单,哭的是我居然找了一下午。所以记住:如果选择器里一台设备都没有,先别怀疑代码,去看看系统蓝牙设置里的「允许被发现」开关。
过滤条件这块,坑就更多了。requestDevice()支持好几种过滤方式,我把常用的整理成一段:
js// ===== requestDevice 的几种常见过滤条件 =====// 写法一:按服务 UUID 过滤(只列出提供指定服务的设备)const byService = await navigator.bluetooth.requestDevice({ filters: [{ services: ['heart_rate'] }], // 心率服务的标准别名 optionalServices: ['device_information'] // 额外想访问的服务要单独声明});// 写法二:按设备名称 / 名称前缀过滤const byName = await navigator.bluetooth.requestDevice({ filters: [{ namePrefix: 'HR-' }] // 只显示名字以 HR- 开头的设备 // 也可以精确匹配:filters: [{ name: 'MyBLESensor' }]});// 写法三:按广播数据里的厂商标识过滤(对付"同名设备"很有效)const byManufacturer = await navigator.bluetooth.requestDevice({ filters: [{ manufacturerData: [{ companyIdentifier: 0x0590 // 厂商 ID,按你设备的协议文档填 }] }], optionalServices: ['0000ffb0-0000-1000-8000-00805f9b34fb']});
这里的第二个大坑,是filters里的services。我一开始按设备的服务 UUID 去过滤,想着「我就要连这个服务的设备,应该很精准才对」。结果怪事又来了:设备上明明有这个服务,选择器却把很多设备都过滤掉了,真正想要的那个反而不出现。我一度怀疑是我司的硬件有问题,后来才想明白——有些设备的广播包里根本没有声明这个服务 UUID,你按 services过滤,它就直接被筛掉了。
最后我是改用广播包里的厂商标识manufacturerData.companyIdentifier 才把目标设备精准捞出来的。这个坑其实不是 Web Bluetooth 独有的,我之前做小程序和 uni-app 蓝牙时也遇到过类似的情况,所以我现在看到「按服务过滤」都会多留个心眼。顺便吐槽一句:filters和acceptAllDevices 不能同时用,你要是 both 写上,浏览器会直接抛错,别问我怎么知道的——我那会儿对着控制台的 InvalidAccessError看了半天才反应过来。
还有一点特别容易忘:optionalServices。你在filters里没提到的服务,如果想在连接后访问,就必须写进optionalServices,否则后面getPrimaryService() 会报「Service not found」。这个设计是为了保护隐私——你不声明,浏览器就不让你碰。我吃过亏之后,现在养成了习惯:只要后续要读写的服务不在 filters 里,一律先塞进 optionalServices。
连接与 GATT:把「服务器—服务—特征」这棵树捋直
选好设备之后,就进入连接环节了。这里必须先搞清楚 BLE 的层级模型,不然代码写着写着就会晕。BLE 设备内部的数据是用一棵树来组织的,从外到内依次是:
GATT 服务器(Server)→ 服务(Service)→ 特征(Characteristic)→ 描述符(Descriptor)
用个比方:GATT 服务器就像一栋大楼,服务是楼里的一个个房间,特征是房间里的一个个抽屉,描述符则是抽屉上的标签。你要读某个数据,就得先找到大楼,再找到房间,再打开对应的抽屉。这个层级在 Web Bluetooth 里是严格对应的,代码也是一层层往下钻。
另外要提一句 UUID。BLE 里服务和特征都是用 UUID 标识的,蓝牙联盟规定了一批「标准 UUID」,它们是 16 位的短值,比如电池服务是 0x180F、心率服务是0x180D。浏览器允许你直接用'battery_service'、'heart_rate'这样的别名,也能用'0000180f-0000-1000-8000-00805f9b34fb' 这种完整的 128 位 UUID。手动拼 128 位 UUID 又长又容易错,这里可以请出 BluetoothUUID.getService() 这个标准 API,它能把别名或短 UUID 转成完整的 128 位形式。
我把连接和逐层获取的代码写出来:
js// ===== 连接设备并逐层获取 GATT 结构 =====async function connectAndExplore() { // 第一步:请求设备(这里用电池服务做过滤) const device = await navigator.bluetooth.requestDevice({ filters: [{ services: ['battery_service'] }] }); // 重要:先挂上断线监听,别等断了再补——这点后面会专门讲 device.addEventListener('gattserverdisconnected', () => { console.warn('设备断开连接了:', device.name); }); // 第二步:连接 GATT 服务器,返回一个 BluetoothRemoteGATTServer const server = await device.gatt.connect(); console.log('GATT 是否已连接:', server.connected); // true // 第三步:获取主服务 // BluetoothUUID.getService 能把标准别名转换成完整 UUID const batteryUuid = BluetoothUUID.getService('battery_service'); console.log('电池服务完整 UUID:', batteryUuid); const service = await server.getPrimaryService(batteryUuid); // 如果想先看设备有哪些服务,可以用复数形式拿全部 // const services = await server.getPrimaryServices(); // console.log('所有服务:', services.map(s => s.uuid)); // 第四步:获取服务下的特征 const characteristic = await service.getCharacteristic('battery_level'); // 也可以一次拿全部:const chars = await service.getCharacteristics(); // 特征的属性决定了它能干什么,务必先看属性再操作 console.log('特征属性:', { read: characteristic.properties.read, write: characteristic.properties.write, notify: characteristic.properties.notify }); return { device, server, service, characteristic };}
这段代码里有个细节我想特别念叨一下——device.addEventListener('gattserverdisconnected', ...)这一步一定要在连接之前就挂好。我早期图省事,总是想着「等连上了再补监听」,结果有几次设备刚连上就因为信号问题断了,那几次断线我完全没捕获到,页面上的状态还傻傻地显示「已连接」。这种状态不一致的 bug 排查起来特别痛苦,因为你根本不知道断线发生过。养成习惯:拿到 device 的第一时间就把断线监听挂上。
再说说getPrimaryService()和getPrimaryServices() 的区别。前者传一个 UUID,只要某一个服务;后者不传参,返回所有服务的数组。调试陌生设备的时候,我一般会先用 getPrimaryServices() 把整棵树扫一遍,把所有服务和特征的 UUID 打出来看看,搞清楚设备到底暴露了哪些能力,再决定读写哪个特征。这比对着厂商那份语焉不详的协议文档猜半天靠谱多了。
顺便安利一下调试工具:nRF Connect 这类 App 能在手机上是把设备的服务树完整列出来,写 Web Bluetooth 代码之前先拿它把设备结构摸清楚,能省掉大量瞎猜的时间。我就是吃了没先摸底就开写的亏,才在服务 UUID 那个坑里转悠了半天。
读与写:DataView 这个「字节口袋」得会拆
拿到特征之后,就到了真正的数据交互环节。先说读——characteristic.readValue()返回的是一个DataView对象,而不是你想象的普通数字或字符串。这玩意儿说白了就是一个「字节口袋」,你得自己按协议规定的格式,一个字节一个字节地从里面取值。
js// ===== 读取特征值并解析 DataView =====async function readBatteryLevel(characteristic) { // readValue() 返回 DataView,注意它是一次性的快照 const dataView = await characteristic.readValue(); // 电池服务协议规定:第 0 个字节(offset 0)就是电量百分比,0-100 // getUint8(offset) 表示从指定偏移位置读一个无符号 8 位整数 const level = dataView.getUint8(0); console.log(`当前电量:${level}%`); // 如果协议是 16 位小端序数据,用 getUint16(offset, true) // 第二个参数 true 表示小端序(littleEndian) // const value16 = dataView.getUint16(0, true); // 如果是一段 UTF-8 字符串,可以借 TextDecoder 解码 // new Uint8Array(dataView.buffer).slice(...) 取出字节再解码 // const text = new TextDecoder().decode(dataView); return level;}
这里我踩过的坑是:拿到DataView之后想当然地console.log(value),结果控制台只打印一个[object DataView],啥也看不见。后来才知道要用getUint8、getUint16 这些方法按偏移量去读,而且读几位是几位、是大端还是小端,全都要严格对照设备的协议文档来。解析错了,数值就会离谱到离谱——我有次把小端当大端读,一个 25 的温度值被我读成了 25600,还以为是设备坏了。
再说写。写特征值有几个 API,这里有个坑必须提醒:writeValue()虽然现在还能用,但官方已经标记为废弃,未来版本会移除,推荐改用writeValueWithResponse()或writeValueWithoutResponse()。我一开始照着老教程用writeValue(),控制台就给我刷一条黄色警告,逼逼赖赖的,后来才换成新 API。
js// ===== 写入特征值:带响应 / 不带响应 =====async function writeData(characteristic, bytes) { const payload = new Uint8Array(bytes); // 写入数据必须是 BufferSource,如 Uint8Array // 1) writeValueWithResponse:写入后等待设备应答,可靠但稍慢 // 适合下发控制指令这类"必须确认送达"的场景 if (characteristic.properties.write) { await characteristic.writeValueWithResponse(payload); console.log('写入成功(已收到设备应答)'); } // 2) writeValueWithoutResponse:发完就走,不等应答,快但不可靠 // 适合高频、允许丢包的场景,比如连续上报传感器配置 if (characteristic.properties.writeWithoutResponse) { await characteristic.writeValueWithoutResponse(payload); console.log('已发出(不等待设备应答)'); } // 注意:写之前一定要看 properties,特征不支持写却硬写会抛异常 // 例如:properties.write 为 false 时调用 writeValueWithResponse 会 NotSupportedError}
写数据这块,我的经验法则是:控制类指令用writeValueWithResponse(),因为你需要知道设备到底收没收到;纯数据流、允许偶尔丢一点的,用writeValueWithoutResponse()图个快。别不分青红皂白全用不带响应的那个,我见过有人下发开关指令也用无响应写入,结果偶发地「指令明明发了设备却没动作」,排查半天才发现是应答机制的问题。
还有一点,writeValue、readValue操作的数据格式都是ArrayBuffer视图(比如Uint8Array、DataView),你不能直接扔一个普通数组或字符串进去。我最开始写writeValueWithResponse([0x01, 0x02])直接报错,改成new Uint8Array([0x01, 0x02])才对。这种小细节,文档里其实都写了,但真写起代码来就是容易忘。
通知订阅:别让设备"说话"时你没在听
如果设备会主动、持续地上报数据——比如心率监测、温度计、传感器——你总不能写个死循环一秒读八百次吧?那就太 low 了。BLE 提供了通知机制:你订阅某个特征之后,设备有新数据就会主动推给你。这里涉及 startNotifications()和characteristicvaluechanged事件。
js// ===== 订阅特征通知,持续接收设备上报的数据 =====async function subscribeNotifications(characteristic) { // 关键顺序:先绑监听函数,再开启通知 // 反过来写的话,开启通知后第一帧数据可能在监听器绑好之前就到了,直接丢失 characteristic.addEventListener('characteristicvaluechanged', (event) => { // event.target.value 就是最新的 DataView const dataView = event.target.value; const firstByte = dataView.getUint8(0); console.log('收到设备上报数据,首字节:', firstByte); // 在这里按协议解析数据、更新 UI、触发业务逻辑…… }); // 开启通知,本质上是往 CCCD(客户端特征配置描述符)写入开启标志 // 这一步浏览器帮你封装好了,不用手动操作描述符 await characteristic.startNotifications(); console.log('通知已开启'); // 不需要的时候记得关闭,并在卸载页面/断开连接前移除监听 // await characteristic.stopNotifications(); // characteristic.removeEventListener('characteristicvaluechanged', handler);}
这里有个顺序坑,我敢说十个人里有八个会踩:一定要先addEventListener,再startNotifications()。我自己就干过反过来的事,先开通知再绑监听,结果设备推送的头一两帧数据全丢了——因为通知一开设备马上就发,而你的监听器还没挂上,那几帧数据就像泼出去的水,收不回来。对于某些只在状态变化时才上报的设备,丢一两帧可能就要等很久才有下一条,排查起来非常诡异。所以记住这个顺序,能省你半天功夫。
另外,通知用完了要记得stopNotifications()关掉,尤其是在单页应用里切页面、组件卸载的时候。不然监听器还在,数据还在往里推,轻则浪费资源,重则造成内存泄漏——这种「事件监听没清理」的问题,跟PHP WeakRef 与 WeakMap 实战:用弱引用破解长驻进程的内存泄漏(缓存与监听器场景) 里聊的监听器泄漏是同一类思路,只不过一个跑在浏览器、一个跑在 PHP 长驻进程里,本质都是「引用没断开,对象回收不了」。前端这边虽然没人帮你做弱引用,但至少记得手动 removeEventListener。
断线重连:这才是真正折磨人的地方
前面那些坑,说到底都是「一次性」的,踩过就过了。真正让我在生产环境里睡不踏实的,是断线重连。
BLE 连接本来就不稳定。用户拿着设备走远了、信号被墙挡了、设备自己休眠了、手机息屏了……都可能触发断线。Web Bluetooth 里,断线会触发 gattserverdisconnected事件,但浏览器不会帮你自动重连。所以你得自己实现。这里最核心的一点是:重连的时候必须重新走一遍device.gatt.connect(),并且重新获取 service 和 characteristic——因为断开之后,之前拿到的那些对象是失效的,你不能拿着旧对象直接读写。
我早期就栽在这:断线后我傻乎乎地只调了device.gatt.connect(),然后继续用 Old 的 characteristic 去读,结果疯狂报错。折腾了好久才明白,GATT 对象树在断线后全部作废,必须整个重建。想通这一点之后,我写了带指数退避的重连逻辑:
js// ===== 带指数退避的断线重连 =====let device = null; // 保存当前 BluetoothDevicelet reconnectTimer = null; // 重连定时器let manualDisconnect = false; // 是否是主动断开(主动断开就不重连)// 等待指定毫秒的工具函数const sleep = (ms) => new Promise(resolve => setTimeout(resolve, ms));// 重新建立完整连接:connect + service + characteristic 全都要重来async function reestablishConnection() { if (!device) throw new Error('没有可重连的设备'); const server = await device.gatt.connect(); // 重新连 GATT const service = await server.getPrimaryService('battery_service'); const characteristic = await service.getCharacteristic('battery_level'); await characteristic.startNotifications(); // 重新挂通知 return characteristic;}// 指数退避重连:失败次数越多,重试间隔越长,避免疯狂重试async function reconnectWithBackoff(maxRetries = 5) { for (let attempt = 0; attempt < maxRetries; attempt++) { // 第 1 次等 1 秒,第 2 次等 2 秒,第 3 次等 4 秒…… const delay = Math.min(1000 * (2 ** attempt), 30000); // 上限 30 秒 console.log(`第 ${attempt + 1} 次重连,${delay}ms 后开始…`); await sleep(delay); try { const characteristic = await reestablishConnection(); console.log('重连成功,数据通道已恢复'); return characteristic; // 成功就返回新的 characteristic } catch (err) { console.warn('重连失败,准备下次尝试:', err.message); } } throw new Error('已达到最大重试次数,放弃重连');}// 在拿到 device 时挂上断线监听function watchDisconnect(targetDevice) { device = targetDevice; device.addEventListener('gattserverdisconnected', async () => { if (manualDisconnect) { console.log('这是主动断开,不触发重连'); return; } console.warn('设备意外断开,启动自动重连…'); try { const newChar = await reconnectWithBackoff(); // 用新的 characteristic 重新订阅通知、恢复业务 await subscribeNotifications(newChar); } catch (err) { console.error('自动重连彻底失败:', err.message); } });}
这套指数退避逻辑我后来是这么设计的:第一次失败等 1 秒,第二次等 2 秒,第三次等 4 秒,以此类推,但最多不超过 30 秒,重试 5 次还不行就放弃并提示用户。为什么要退避?因为如果设备真的没了或者没电了,你每秒重试一次纯属浪费资源,还可能把设备的连接资源占满。指数退避是网络重试里的经典套路,搬到蓝牙重连一样好使。
还有个manualDisconnect标志位,用来区分「主动断开」和「意外断开」。用户点了「断开连接」按钮触发的断线,你不应该傻乎乎地又给它连回去——我早期没做这个判断,结果用户点断开,页面转头又自动连上了,用户当场就懵了,以为按键失灵。加了个标志位就好了。
把收发放到一个上下文:发布订阅 + Promise 封装
最后聊聊我在实际项目里做的一个封装,我觉得这是整个方案里最有工程价值的部分。
我们公司的蓝牙设备有个很别扭的设计:下发指令是往「写特征」里写数据,而设备的响应却从「通知特征」里推出来。也就是说,收发不在同一个地方——你写了0xAA 0xFF,响应0xAA 0x01会从另一条通道冒出来。这在业务代码里就很麻烦:每发一条指令,都得去通知回调里找对应的响应,代码写得东一块西一块,跟打补丁似的。
后来我用「发布订阅 + Promise」把它包了一层,让上层写业务代码时,感觉就像在调一个普通的异步函数——发一条指令,await 一下,直接拿到响应。核心思路是:给每条指令按其首字节(标识位)分配一个订阅频道,写入指令后挂一个带超时的 Promise,等通知里出现对应标识的数据,就 resolve 掉这个 Promise。
js// ===== 用发布订阅 + Promise 把"写指令/收响应"收敛到同一个上下文 =====// 一个极简的事件总线(生产环境可用现成的库,这里手写示意)class EventBus { constructor() { this.handlers = new Map(); } on(type, fn) { if (!this.handlers.has(type)) this.handlers.set(type, new Set()); this.handlers.get(type).add(fn); } off(type, fn) { this.handlers.get(type)?.delete(fn); } emit(type, data) { this.handlers.get(type)?.forEach(fn => fn(data)); }}const bus = new EventBus();// 通知回调:收到数据后,按首字节标识投到对应频道// characteristic 是写响应所在的通知特征notifyCharacteristic.addEventListener('characteristicvaluechanged', (event) => { const dataView = event.target.value; const id = dataView.getUint8(0); // 首字节作为指令标识 bus.emit(id, dataView); // 发布到对应频道});// 封装:发一条指令,返回一个 Promise,收到响应或超时才结束function sendCommand(bytes, writeCharacteristic, timeout = 3000) { const payload = new Uint8Array(bytes); const id = payload[0]; // 用首字节作为这条指令的唯一标识 return new Promise((resolve, reject) => { // 超时定时器:3 秒没等到响应就 reject const timer = setTimeout(() => { bus.off(id, handler); // 超时后移除监听,防止泄漏 reject({ code: -1, msg: '指令超时' }); }, timeout); // 响应处理器:收到对应标识的响应就兑现 Promise const handler = (dataView) => { clearTimeout(timer); // 收到响应,取消超时 bus.off(id, handler); // 一次性监听,用完就摘 resolve({ code: 0, data: dataView, msg: '操作成功' }); }; bus.on(id, handler); // 先订阅,再发指令(顺序不能反) writeCharacteristic.writeValueWithoutResponse(payload); });}// 上层调用:写起来就像普通的异步请求,清爽多了// sendCommand([0xAA, 0xFF], writeChar)// .then(res => console.log('响应数据:', res.data))// .catch(err => console.error('指令失败:', err.msg));
这套封装上线之后,业务代码的整洁度提升了一大截。以前发一条指令要写十几行回调,现在一行await sendCommand(...)就搞定。这里有两个关键点:一是「先订阅再发送」的顺序,跟通知订阅那个坑是一个道理;二是超时之后一定要bus.off把监听摘掉,否则每条超时指令都会留下一个僵尸监听器,时间长了就是内存泄漏——这也是我一直念叨「事件监听要清理」的原因。
从架构角度看,这个做法其实跟前端里很多场景是相通的。比如浏览器里调度动画跟着滚动走,本质也是把「滚动事件」和「动画进度」两件事解耦,我之前那篇CSS 滚动驱动动画实战:用 animation-timeline 让动画跟随滚动进度(scroll() 与 view()) 讲的就是用声明式的方式把滚动和动画关联起来,省掉手动监听 scroll 的麻烦。虽然一个管蓝牙、一个管动画,但「别让回调散落一地,想办法收敛到一个上下文」这个思路,是通用的。
一些碎碎念:兼容性、安全,还有那些文档不告诉你的事
写到这儿,主体内容差不多了,再把几个零碎但重要的点补一补。
兼容性是硬伤。 Safari 和 Firefox 目前都不支持,这意味着 iOS 用户完全用不了。如果你的产品面向 C 端大众,Web Bluetooth 基本没法作为主方案,只能作为 Chromium 用户的一个「增强体验」。我们最后是把它定位成内部工具——比如产线工人用安卓平板连设备采集数据,场景可控,浏览器统一,这才敢上。这一点在做技术选型时一定要想清楚,别到时候才发现一半用户用不了。
安全限制要认。 Web Bluetooth 只能在安全上下文用、必须用户手势触发、权限按源(origin)隔离且用户随时可以撤销。这些限制不是故意为难你,而是为了防止恶意网页偷偷扫你身边的设备。理解了这层,你就不会去琢磨「怎么绕过用户授权静默连接」这种歪门邪道了——那不仅做不到,也不该做。
权限可以被撤销。用户在浏览器设置里可以随时撤销对某个站点的蓝牙授权。所以你的代码不能假设「授权过一次就永远有效」,每次requestDevice()都可能因为权限被拒而失败,错误处理要做足。
实验性 API 的风险。 Web Bluetooth 至今仍带着实验性质,规范还在演进,部分 API(比如前面提到的 writeValue())已经被标记废弃。生产环境用之前,务必确认目标浏览器的版本,并做好 API 变更的心理准备。我一般会在关键调用外面包一层 try-catch,把降级提示做友好一点,别让页面白屏。
调试建议。 强烈建议先把 nRF Connect 之类的工具装好,用它把设备的服务树、特征 UUID、属性、数据格式全部摸清楚,再写 Web Bluetooth 代码。对着协议文档两眼一抹黑就开写,是最低效的做法——我那个服务过滤的坑,本质就是没先把设备结构摸透。
小结
回顾这一整轮踩坑,其实技术本身没多难——requestDevice选设备、gatt.connect连服务器、getPrimaryService/getCharacteristic逐层下钻、readValue/writeValue读写、startNotifications 订阅通知,这套流程理顺了就是一层窗户纸。真正难的是那些文档不会重点强调的「工程细节」:HTTPS 的限制、系统蓝牙开关、过滤条件的诡异行为、optionalServices的坑、监听与通知的先后顺序、断线后对象全部失效、监听器的清理……
这些细节,几乎都是我拿时间和头发换来的。所以如果这篇东西能让你少熬一个通宵、少薅掉几根头发,那我这些坑就算没白踩。
Web Bluetooth 让浏览器第一次有了「伸手碰硬件」的能力,虽然它现在还有这样那样的限制,但在场景可控的内部工具、IoT 配置面板、教育实验这类领域,它已经足够好用。别被它实验性的标签吓退,也别盲目乐观忽视兼容性和安全限制——看清边界,用对场景,它是一个能实实在在提升效率的好工具。
最后照例提醒一句:真机上多测、多覆盖不同品牌和系统的设备,别像我一样只在自己的开发机上跑通就以为万事大吉。BLE 这东西,不同设备的兼容性差异,远超你的想象。好了,去连你的第一台蓝牙设备吧,祝你好运,愿你别踩我踩过的那些坑。
标签:javascript, 前端, html5描述:以第一人称踩坑叙事,实战讲解 Web Bluetooth API 从 requestDevice 过滤、GATT 服务与特征读写、通知订阅到断线重连的完整流程,附大量带中文注释代码与真实工程经验。

发表评论发布评论后审核成功,即可显示在列表中...