简介：基于 HBuilderX 开发的 HTML5 蓝牙通信示例项目，内置 Web 端与 Android 原生两套实现，适合前端开发者或物联网爱好者学习 BLE 连接、GATT 服务和串口透传。压缩包共 258 个文件，约 11.45MB，主要包括 Java/XML 原生工程、JS/HTML 前端脚本、APK 安装包及 Gradle 构建配置等，结构清晰便于对照学习。已有 5166 人浏览学习。资源覆盖蓝牙状态实时监控、数据收发完整逻辑，附带了 BleManager、BLE_DEMO 等多个可直接运行的 APK，可快速体验连接 MLT-BT05 等蓝牙模块；同时提供 Android 原生源码，方便在 Web Bluetooth API 受限或需要更稳定连接时迁移使用，配套的模块资料与截图也有助于降低调试门槛。
1. 蓝牙通讯为什么要用 HBuilderX 做：一个几分钟就能跑通的 HTML5+ 方案
做 App 的开发者第一次碰硬件蓝牙，多半是被需求逼的：给设备加个设置页，或者读一串传感器数据。用 HBuilderX 写页面很快，但一提到蓝牙通讯，第一反应就是“这不还得写原生”？html5-bluetooth-demo-HBuilderX 这类示例工程指明了一条近路——基于 HTML5+ 的 plus.bluetooth 接口，扫描、连接、收发数据可以在 JS 里全程完成，真机调试几分钟就能看到设备列表。这篇笔记按这个方向拆一套实践过的落地路径：选型依据、最小可运行代码、参数设置和踩坑记录，适合用 HBuilderX 做跨平台 App、想快速对接低功耗蓝牙硬件的开发者。要连门锁、体脂秤、打印机这类 BLE 设备，这个方向值得投入。
2. 蓝牙通讯为什么选 HTML5+ 接口：能力边界与选型逻辑
2.1 plus.bluetooth 能做什么：从扫描到读写的能力全景
HBuilderX 里跑的是 HTML5+ 的蓝牙封装，核心 API 都挂在plus.bluetooth命名空间下。BLE（低功耗蓝牙）的完整通讯链路就四步：扫描、连接、发现服务与特征值、读写数据。对应的接口也很清晰地做了拆分：
| 能力 | 接口 | 用途 |
|---|---|---|
| 初始化 | openBluetoothAdapter | 打开手机蓝牙适配器，所有操作的前置条件 |
| 扫描 | startBluetoothDevicesDiscovery | 启动扫描，可指定服务 UUID 过滤 |
| 扫描结果 | onBluetoothDeviceFound | 持续回调，一帧可能包含多个设备 |
| 连接 | createBLEConnection | 建立与设备的 GATT 连接 |
| 服务发现 | getBLEDeviceServices | 拿到设备广播的服务列表 |
| 特征值发现 | getBLEDeviceCharacteristics | 拿到服务下可读、可写、可通知的特征值 |
| 写入 | writeBLECharacteristicValue | 向指定特征值写入 ArrayBuffer 数据 |
| 通知 | notifyBLECharacteristicValueChange | 开启设备的主动上报通道 |
| 数据接收 | onBLECharacteristicValueChange | 接收设备主动推送的数据 |
| 状态监听 | onBLEConnectionStateChange | 监听连接断开等状态变化 |
| 断开 | closeBLEConnection | 主动断开连接 |
| 停止扫描 | stopBluetoothDevicesDiscovery | 找到设备后及时关闭扫描，省电 |
这套接口基本覆盖了 BLE 的日常使用。硬件设备常见的几种形态——传感器上报、门锁开锁指令、打印机打印数据、体脂秤测量结果——都能用同一套逻辑实现。而且接口命名和微信小程序蓝牙 API 几乎一致，做过小程序蓝牙开发的人切换过来基本零学习成本。
要特别注意接口边界：它只支持低功耗蓝牙（BLE），不支持经典蓝牙（SPP）。如果项目里要连老式蓝牙串口模块或者经典蓝牙打印机，这条路走不通，必须走原生。这是选型前第一个要确认的事，硬件不支持 BLE，后面全部白做。
2.2 对比原生与小程序蓝牙：什么场景该选这条路
同样是做蓝牙通讯，摆在面前的选择通常是三条路：原生开发、微信小程序、HBuilderX + HTML5+。三者的差异很实际。
| 维度 | HTML5+ 蓝牙 | 原生 Android/iOS | 微信小程序 |
|---|---|---|---|
| 开发语言 | JS，前端团队直接上手 | Java/Kotlin + Swift，两套代码 | JS，但要过微信审核 |
| 跨平台 | Android/iOS 一套代码 | 各写一套 | 只能在微信内运行 |
| BLE 链路 | 扫描到读写全支持 | 最全，可调底层 MTU、写类型 | 全支持，且暴露 writeType |
| 经典蓝牙 SPP | 不支持 | 支持 | 不支持 |
| 后台维持连接 | 弱，App 退后台容易断 | 可做长连接保活 | 微信限制严格 |
| 发布渠道 | 自有 App，可热更新资源 | 各自应用商店 | 微信审核 |
从成本看，如果团队里只有前端工程师，又没有一款现成的原生 App 外壳，HBuilderX 这条路是最短路径。调试时用真机跑一遍，改完代码刷新页面就能看到效果，不需要每次编译原生工程，迭代速度很快。
从能力边界看，这条路适合的场景是：硬件支持 BLE、连接过程是用户主动触发、数据交互是短时高频而非 7x24 小时后台常驻。典型如设备配置工具、体检仪数据读取、门店蓝牙打印机。反过来，如果要做手环那样的后台通知常驻，或者要自己控制 MTU 协商和写类型，前端接口就不够，得往原生层补。
小程序蓝牙看似接近，但有两个内伤：一是扫描同样要开定位权限，用户被权限弹窗吓退的概率高；二是业务数据量大了以后，微信对蓝牙后台的限制很麻烦。自己的 App 没有这个问题，这也是很多人最后回到 HBuilderX 的原因。
3. 让 html5-bluetooth-demo 在 HBuilderX 里跑起来：项目导入与真机验证
3.1 环境准备与项目导入：manifest 里的蓝牙模块配置
拿到 html5-bluetooth-demo 这类工程后，第一步不是看代码，而是确认工程能被 HBuilderX 正确识别并跑上真机。操作路径很固定：打开 HBuilderX，选择导入本地项目，定位到工程根目录；随后打开manifest.json，在可视化配置页里找到 App 模块配置，勾选 Bluetooth 模块。这一步不做，代码里调用plus.bluetooth会直接报“undefined”，这是最常见的第一个坑。
保存后，manifest.json源码里通常会多出这样一段：
"permissions": { "Bluetooth": { "description": "用于连接低功耗蓝牙设备" } }这段配置表示 App 打包时会把蓝牙模块打进去。云打包和本地打包都会读取它，缺了这一步，后面的代码写得再对也调不起接口。iOS 端还需要在 manifest 的可视化界面里填NSBluetoothAlwaysUsageDescription描述，否则 iOS 13 及以上首次触发蓝牙授权时可能直接闪退。
Android 端还有第二个权限问题：BLE 扫描在 Android 6.0+ 必须拿到定位权限，否则扫描不会回调。单纯在 manifest 里声明ACCESS_COARSE_LOCATION还不够，运行时还要动态申请。我一般会把权限申请包成一个函数，放到页面初始化时先执行：
function ensureBtPermission(callback) { // Android 6.0+ 扫描 BLE 必须动态申请定位权限 plus.android.requestPermissions( ['android.permission.ACCESS_FINE_LOCATION'], function(result) { if (result.granted && result.granted.length > 0) { callback(); } else { plus.ui.toast('需要定位权限才能扫描蓝牙设备'); } }, function(error) { plus.ui.toast('权限申请失败：' + error); } ); }这里的result.granted是授权返回的权限数组，虽然只申请了一个，也要判断长度而不是直接信任回调走 success。原因是部分定制 ROM 的授权回调行为不一致，有的拒绝也会走进来，加一层判断避免后续代码在无权限状态下继续执行。Android 12 以上还涉及BLUETOOTH_SCAN和BLUETOOTH_CONNECT权限，HBuilderX 新版打包时会连同蓝牙模块一起打进去，不需要手动处理，但如果是老版本打包环境，需要确认这两项已加入权限列表。
3.2 真机运行与首次扫描：三步验证蓝牙链路
环境配好后，验证链路是否通的流程只有三步：手机打开蓝牙和定位服务、USB 连接后运行到真机、在页面触发一次扫描。我把最小验证代码写在一个页面里，逻辑很简单，单看 console 输出就能判断：
document.addEventListener('plusready', onPlusReady); function onPlusReady() { // 1. 打开蓝牙适配器，模拟器里这一步经常失败 plus.bluetooth.openBluetoothAdapter({ success: function(e) { console.log('蓝牙已打开'); startScan(); }, fail: function(e) { console.log('打开蓝牙失败：' + JSON.stringify(e)); } }); } function startScan() { // 2. 不传 services 参数即扫描所有 BLE 设备 plus.bluetooth.startBluetoothDevicesDiscovery({ powerLevel: 'low', allowDuplicatesKey: false, success: function() { console.log('开始扫描'); }, fail: function(e) { console.log('启动扫描失败：' + JSON.stringify(e)); } }); // 3. 监听到设备上报，打印名称和 deviceId plus.bluetooth.onBluetoothDeviceFound(function(e) { var devices = e.devices || []; devices.forEach(function(device) { console.log('发现设备：' + (device.name || '未知') + ' ' + device.deviceId); }); }); }三段代码对应三个关键节点：适配器是否打开、扫描是否启动、设备是否上报。powerLevel参数有三个档位，low最省电但扫描慢，high响应快但耗电，调试阶段建议用low，扫不到再升档；allowDuplicatesKey设置为false表示同一设备只上报一次，设true会携带信号强度持续上报，做设备距离排序时用得上。
真机跑通后，console 里能看到一串带名称和设备 ID 的日志，说明这条链路已经通了。如果openBluetoothAdapter一直失败，先手动开关一次手机蓝牙，部分国产 ROM 在蓝牙服务异常时会出现假死状态；如果设备列表为空，优先检查定位权限和蓝牙开关的先后顺序，这个坑在第五章详细展开。
4. 自己写一个最小蓝牙通讯页：扫描、连接、读写特征值
4.1 扫描与设备列表：按信号强度过滤与排序
demo 跑通后，下一步是把扫描结果做成真正的列表。设备一多，直接全量展示没法用。我一般会先过滤无名称设备，再按RSSI信号强度排序，让用户优先看到身边的设备：
function onBtFound(e) { var list = []; (e.devices || []).forEach(function(d) { // 过滤掉广播里没带名字的设备，减少干扰项 if (d.name && d.name.length > 0) { list.push({ name: d.name, deviceId: d.deviceId, rssi: d.RSSI }); } }); // RSSI 越接近 0 说明信号越强，按从小到大排 list.sort(function(a, b) { return b.rssi - a.rssi; }); renderDeviceList(list); }这个过滤器能砍掉至少三分之一的无用设备，因为许多 BLE 外设广播包不带名称，只带一串 MAC 地址，展示出来没有辨识度。deviceId是后续所有操作的主键，要存好。注意 Android 上它是 MAC 地址形式，iOS 上是系统随机生成的 UUID，两者都不能当作设备的持久唯一标识，机型重启后可能变化。
4.2 连接与特征值发现：找到能读能写的句柄
用户点击列表某一项后，进入连接流程。连接成功不等于能通信，还要发现服务和特征值。前面提到过，BLE 数据的读写不是直接对设备操作，而是先找服务，再找服务下的特征值，特征值才是真正读写数据的“句柄”。
var currentDeviceId = ''; function connectDevice(deviceId) { currentDeviceId = deviceId; plus.bluetooth.createBLEConnection({ deviceId: deviceId, timeout: 8000, success: function() { console.log('连接成功，开始发现服务'); discoverServices(deviceId); }, fail: function(e) { console.log('连接失败：' + JSON.stringify(e)); // 把完整错误对象打出来，不要只看 message console.log(JSON.stringify(e)); } }); } function discoverServices(deviceId) { plus.bluetooth.getBLEDeviceServices({ deviceId: deviceId, success: function(e) { var services = e.services || []; services.forEach(function(s) { var uuid = s.uuid.toLowerCase(); // 常见厂商用 FFE0 这类自定义服务，按实际协议改 if (uuid.indexOf('ffe0') > -1) { discoverCharacteristics(deviceId, s.uuid); } }); }, fail: function(e) { console.log('获取服务失败：' + JSON.stringify(e)); } }); }createBLEConnection的timeout参数默认值在不同版本上表现不一致，我习惯显式传 8000 到 10000 毫秒。连接失败时，fail 回调里的错误对象必须完整打印出来，很多信息在message里看不到，嵌套在code和errMsg里。discoverServices返回的服务列表是全量的，通常有若干个标准服务，比如电池服务、设备信息服务，真正要用的业务服务一般以厂商自定义 UUID 出现，判断时用toLowerCase()统一大小写，设备和手机两端的 UUID 大小写不一致极易导致匹配失败。
4.3 写入指令：字符串转 ArrayBuffer 再发
找到目标服务后，下一步是拿到特征值。特征值有三个关键属性：可读、可写、可通知。很多新手在这里直接把 UUID 抄下来就发，却忽略了一个属性匹配问题。看这段代码：
var writeChar = null; function discoverCharacteristics(deviceId, serviceId) { plus.bluetooth.getBLEDeviceCharacteristics({ deviceId: deviceId, serviceId: serviceId, success: function(res) { var chars = res.characteristics || []; chars.forEach(function(char) { var p = char.properties; console.log('特征值：' + char.uuid + ' 可写：' + p.write); // 优先取带 write 属性的，其次才是 writeNoResponse if (p.write && !writeChar) { writeChar = { serviceId: serviceId, uuid: char.uuid }; } }); }, fail: function(e) { console.log('获取特征值失败：' + JSON.stringify(e)); } }); } function sendCmd(hexStr) { if (!writeChar) { console.log('还没找到可写特征值'); return; } plus.bluetooth.writeBLECharacteristicValue({ deviceId: currentDeviceId, serviceId: writeChar.serviceId, characteristicId: writeChar.uuid, value: hexToArrayBuffer(hexStr), success: function() { console.log('写入成功：' + hexStr); }, fail: function(e) { console.log('写入失败：' + JSON.stringify(e)); } }); } function hexToArrayBuffer(hex) { var clean = hex.replace(/\s/g, ''); var buf = new ArrayBuffer(clean.length / 2); var view = new Uint8Array(buf); for (var i = 0; i < view.length; i++) { view[i] = parseInt(clean.substr(i * 2, 2), 16); } return buf; }这里最关键的约束是value必须是ArrayBuffer，直接传字符串或普通数组都会失败。蓝牙协议里的指令绝大多数以 hex 形式约定，比如AA 55 01 02，所以要先转成字节数组再放入 ArrayBuffer。writeChar对象缓存的是特征值的 serviceId 和 uuid，后续所有写入都要用这两项精确定位，换设备连接时要重置为空，否则会往上一台设备的句柄上写，报错还很怪异。
4.4 接收设备主动上报：开启 notify 通道
写入指令只是单向的，设备主动上报的数据需要另一条通道，这条通道就是 notify。开启 notify 后，设备才能向手机推送数据，心率、电量、测量结果都走这里：
function enableNotify(serviceId, charUuid) { plus.bluetooth.notifyBLECharacteristicValueChange({ deviceId: currentDeviceId, serviceId: serviceId, characteristicId: charUuid, state: true, success: function() { console.log('通知开启成功'); }, fail: function(e) { console.log('开启通知失败：' + JSON.stringify(e)); } }); } // 开启后在全局监听，之后设备每次上报都会走到这里 plus.bluetooth.onBLECharacteristicValueChange(function(e) { var hex = ab2hex(e.value); console.log('收到数据：' + hex); parseProtocol(hex); }); function ab2hex(buffer) { var u8 = new Uint8Array(buffer); return Array.from(u8).map(function(b) { return b.toString(16).padStart(2, '0'); }).join(' '); }收到的e.value同样是 ArrayBuffer，直接toString拿到的是乱码，必须转成 hex 才能和协议对比。parseProtocol是业务解析函数，不同设备协议不同，但格式差不多，通常是固定帧头、长度、命令字、数据和校验位。开发阶段把收到的原始 hex 完整打印出来是最重要的排障手段，别急着做解析，先确认数据能上来，再谈协议对不对。
5. 蓝牙通讯避坑指南：权限、系统差异与回调时序
5.1 Android 扫描不到设备：定位权限与蓝牙开关的先后顺序
现象：权限都申请了，蓝牙也开着，扫描就是不回调，等一分钟都看不到设备。
原因：Android 6.0+ 要求定位权限才能扫描 BLE，但部分国产 ROM 对权限的生效时机很抠——必须先授权定位，后打开蓝牙，或者反过来，顺序颠倒后系统蓝牙服务没有重新初始化，扫描接口就一直处于哑火状态。另一个隐蔽原因是部分 ROM 的“精确定位”开关被系统策略关闭，仅定位权限还不够。
解决：把权限申请、蓝牙开启、再扫描的流程做成串行。权限申请成功后先openBluetoothAdapter，成功后再启动扫描；扫描前手动开关一次手机蓝牙，给系统蓝牙服务一个重新初始化的机会。如果还是不行，检查系统的定位服务总开关是不是被关了，这一步在定制 ROM 上最容易被忽略。
5.2 iOS 连上却读不到服务：蓝牙缓存与特征值发现时机
现象：连接成功回调正常，但getBLEDeviceServices一直返回空数组，或者返回的服务里找不到目标服务。
原因：iOS 对蓝牙有系统级缓存，设备固件更新或 App 之前连接过，缓存里的服务列表就可能失真。更常见的是时机问题——连接成功回调后立刻去查服务，此时 GATT 发现流程还没完成，接口抢跑得到空结果。
解决：连接成功后加一个 300 到 500 毫秒的延迟再调用服务发现接口，给协议栈留出完成时间；如果延迟后还是空，让用户去系统设置里忽略该设备、关闭蓝牙再重连，必要时重启手机。这个坑我调过一整个下午，最后是重启手机解决的，属于血泪经验。
5.3 写入失败或收不到通知：UUID 大小写、写类型与 MTU
现象：写入接口回调 fail，错误码提示找不到特征值；或者指令写进去了，设备没反应；又或者一次写长数据，数据被截断。
原因：第一个原因是 UUID 大小写不匹配，设备端定义的特征值 UUID 是 AB 开头，前端传的是 ab 开头，两边对不上，系统直接报找不到。第二个原因是写类型，部分设备特征值只支持writeNoResponse，不支持带响应的 write，前端接口默认走 write，硬件端没回应就失败。第三个是 MTU 问题，默认 MTU 只有 23 字节，扣掉协议头，应用层一包只能带 20 字节，写多了会被系统直接截断。
解决：UUID 全部转小写后再比较，两端统一。写类型的问题优先在特征值列表里找带write属性的特征值，如果设备只暴露writeNoResponse，前端接口没有直接暴露写类型的参数，需要在原生层做扩展或换用带响应写的主机端。长数据自己分包，每包 20 字节以内，包间加 10 到 20 毫秒延时。
5.4 回调不执行：plusready 与错误对象里的玄学
现象：接口调用看起来成功了，success 没走，fail 也没走，console 空空的，整个蓝牙功能像黑匣子一样。
原因：最常见的是页面 JS 在plusready事件触发前就调用蓝牙接口，界面 DOM 渲染完不等于 plus 环境准备好；其次是部分接口的 fail 回调在某些异常分支不会被调用，比如扫描中重复调用扫描，或者连接状态下再次连接同一设备；再者是写代码时只写了 success 没写 fail，错误被静默吞掉。
解决：所有蓝牙相关操作统一包在document.addEventListener('plusready', ...)里执行，入口页做个环境守卫。每个接口都写全 success 和 fail，fail 里完整打印错误对象。调试阶段用一个全局数组缓存日志，页面崩溃时还能通过注释临时把日志打印到页面上，避免只能对着远程日志瞎猜。
6. 从能通讯到能上线：MTU 分包、断线重连与日志验证
能连上、能收能发只是第一步，真上线还有几个问题绕不开：长数据发送会截断、连接断了用户要手动重连、设备上报的数据不知道对不对。这三个问题各有各的常规解法。
长数据用分包发送。默认 MTU 23 字节，应用层单包别超过 20 字节。封装一个发送函数，把长 hex 串按每 20 字节切块，块间延时 20 毫秒：
function sendLongHex(hexStr) { var clean = hexStr.replace(/\s/g, ''); var total = clean.length / 2; var offset = 0; var chunk = 20; var sendNext = function() { if (offset >= total) { console.log('发送完成'); return; } var part = clean.substr(offset * 2, chunk * 2); sendCmd(part); offset += chunk; setTimeout(sendNext, 20); }; sendNext(); }分包后的每一条指令仍然走writeBLECharacteristicValue，设备端会把连续收到的数据拼回完整帧，所以每包的格式要固定，最好带上序号。延时不能去掉，很多低功耗设备收包后需要时间处理，连续发送太快会丢包。
断线重连用onBLEConnectionStateChange监听。连接意外断开后，这个回调会带着connected: false触发，此时保存上次连接成功的 deviceId，提示用户一键重连，而不是让用户重新走一遍扫描流程：
plus.bluetooth.onBLEConnectionStateChange(function(e) { if (!e.connected) { console.log('连接已断开，等待重连'); reconnectToLastDevice(); } });日志验证是最后一道保险。设备上报的数据统一用ab2hex转成 hex 字符串打印，与硬件同事给的协议逐字节比对。帧头、长度、数据区、校验和每一项都要对得上，对不上先别怀疑手机，先把原始数据拍下来找硬件方确认。
我做这个方向时最大的教训是：硬件没给齐协议表之前，别急着写解析代码，先把收发链路的 hex 日志打满。服务 UUID、特征值 UUID、数据协议这三张表齐了，整个联调时间至少省一半。踩过一遍这些坑之后，再遇到类似项目你会很清楚该先问硬件什么、先测哪一步，而不是拿着手机干等回调。希望帮到你。
本文还有配套的精品资源，点击获取
