HBuilderX蓝牙通讯实战：plus.bluetooth接口从扫描到数据收发全解析

简介：基于HBuilderX实现的HTML5蓝牙通信示例工程，面向Web前端与移动端开发者，演示如何通过Web Bluetooth API与低功耗蓝牙设备建立连接、读取特征值并完成双向数据收发；同时给出常见异常和连接失败的处理思路。项目亲测可用，包含蓝牙状态监听、连接管理、数据透传的完整逻辑，还附带Android原生蓝牙实现源码和MLT-BT05、JDY-08等透传模块资料，软硬件对接时可直接参照。压缩包共258个文件，以Java、JavaScript、XML与APK为主，另有Gradle构建配置、图片和资源文件，整体约11.45MB；目录中同时包含可运行APK示例和调试辅助内容，便于直接安装验证。目前已有5166人浏览学习，适合需要快速搭建BLE通信项目、希望同时掌握Web与原生蓝牙开发路径的开发者参考，尤其适合物联网场景下健康监测与智能家居等应用开发。

1. HBuilder蓝牙通讯：这个Demo凭什么敢说是“亲测可用”

做智能硬件控制方向，最怕的不是写业务逻辑，而是蓝牙链路本身的不确定性。很多开发者习惯性复用PC浏览器里的Web Bluetooth代码，结果挪到移动端直接翻车——不是扫描不到设备，就是连接上了却收不到数据。这个Demo的定位很明确：基于HBuilderX的5+ App标准封装，直接调用plus.bluetooth原生接口，把BLE从初始化到数据收发全链路跑通。它适合正在用HBuilderX开发门锁、灯控、透传模块等项目的开发者，新人照着改改UUID就能对接硬件，熟手可以直接抽走打包逻辑当基建用。

2. 蓝牙选型逻辑：为什么必须用HBuilderX的plus.bluetooth而不是Web Bluetooth

2.1 浏览器直连BLE的“黑匣子”问题

很多初接触物联网的开发者，第一反应是去翻Web Bluetooth API的文档。这个API在Chrome桌面浏览器上确实能用，但放到实际项目里处处受制。我之前在某实验室帮人整过一个模拟项目X，用Chrome的navigator.bluetooth去连一台BLE体脂秤。代码写起来很简洁，就那么几行：

navigator.bluetooth.requestDevice({ acceptAllDevices: true, optionalServices: ['battery_service'] }).then(device => { return device.gatt.connect(); }).then(server => { return server.getPrimaryService('battery_service'); }).then(service => { return service.getCharacteristic('battery_level'); }).then(characteristic => { return characteristic.readValue(); }).then(value => { console.log('电量:', value.getUint8(0)); });

这段代码在笔记本上的Chrome里跑得很欢，但一旦挪到移动端App场景就彻底哑火。原因在于：Web Bluetooth要求页面必须在HTTPS环境下运行，且目前只有Android端的Chrome给了一部分支持，iOS全部不支持。Android后台一锁屏，蓝牙扫描进程随时可能被系统回收，连接也就跟着断了。这就是典型的“黑匣子”——浏览器层封装得太干净，开发者根本看不到底层的权限管理、蓝牙状态切换、MTU协商这些真正决定成败的参数。

所以在这个Demo里，没有去碰Web Bluetooth API，而是直接落到了HTML5+的plus.bluetooth模块。这才是HBuilderX打包成原生App后，我们真正能稳定控制的蓝牙入口。

2.2 HTML5+ Bluetooth模块的能力边界与选型

plus.bluetooth是HBuilderX的5+运行时提供的原生能力封装，它和Web Bluetooth API有个本质区别：它走的是系统级蓝牙框架，Android和iOS各走各的原生实现，再由统一JS接口暴露给前端。也就是说，你写一遍JS逻辑，系统帮你适配了两端的差异，这正是“H5+Blu”这套方案的价值所在。

选型结论很直接：只要你是要上架到Android/iOS的应用商店，或者要交付给客户装到手机里的正式产品，就绕开Web Bluetooth，直接用plus.bluetooth。它虽然看起来“不那么时髦”，但却是HBuilderX生态里唯一能扛住真机生产环境的方案。

2.3 Demo的文件结构与API映射关系

拿到这份源码后，第一件事不是急着运行，而是先看清工程目录。这个Demo延续了HBuilderX里典型的5+ App结构，主要分三层：

├── manifest.json // 应用配置：权限声明、App图标、启动图 ├── index.html // 入口页面：UI布局、事件绑定 ├── js/ │ ├── bluetooth.js // 核心：蓝牙API封装层 │ └── protocol.js // 可选：数据帧解析与组包（新版已集成）

index.html直接引用了bluetooth.js里的全局对象BluetoothManager。这个管理器把零散的plus.bluetooth接口串成了有状态的流程——从openBluetoothAdapter到startBluetoothDevicesDiscovery再到createBLEConnection，每一步都做了状态锁和错误回调。为什么要封装成管理器而不是直接在每个按钮事件里写API？因为蓝牙流程是异步且状态机驱动的，如果不在中间层统一管理，后续维护时会出现大量重复代码，而且很容易在“连接中”状态下二次点击操作导致不可预期的错误。这个Demo的价值就在于此：它把状态流转从业务层剥离出去了。

3. 核心API实战：从扫描到数据回传的完整生命周期

3.1 第一步：初始化蓝牙适配器

一切蓝牙操作的前提是适配器可用。很多刚接触的开发者容易栽在这一步：直接调用startBluetoothDevicesDiscovery，却忘了先开启蓝牙、初始化适配器，结果得到一堆莫名其妙的错误码。在Demo里，这一步被封装得很谨慎：

bluetoothManager.openAdapter = function(successCallback, failCallback) { if (plus.bluetooth && typeof plus.bluetooth.openBluetoothAdapter === 'function') { plus.bluetooth.openBluetoothAdapter({ success: function(res) { console.log('适配器开启成功', res); successCallback && successCallback(res); }, fail: function(err) { console.error('适配器开启失败', err); // 常见错误码：10001 表示蓝牙未开启 if (err.code === 10001) { failCallback && failCallback('请先打开系统蓝牙'); } else { failCallback && failCallback('蓝牙初始化失败，代码:' + err.code); } } }); } else { failCallback && failCallback('当前环境不支持蓝牙接口'); } };

逻辑说明：这里先做了能力检测，判断plus.bluetooth是否存在，而不是假定所有打包环境都一定有蓝牙模块。这可以避免在Android模拟器或某些定制ROM上运行时出现白屏。

参数说明：openBluetoothAdapter的success返回的res对象里包含isSupportBLE字段，用来判断当前设备是否支持低功耗蓝牙。fail回调里的err.code有固定含义——10001是蓝牙未开启，10002是系统不支持BLE。后续步骤的排错完全依赖这些错误码，所以我在封装时特意把它们转成了人类可读的字符串。

3.2 第二步：扫描设备与过滤规则

蓝牙扫描是异步过程，不能像调用普通函数那样指望一次性返回所有结果。Demo里的扫描封装采用了“定时累加+自动去重”的模式：

bluetoothManager.startDiscovery = function(duration) { var scanInterval = null; var deviceMap = {}; // 监听设备发现事件 plus.bluetooth.onBluetoothDeviceFound(function(res) { var devices = res.devices || []; devices.forEach(function(device) { var key = device.deviceId; // 利用RSSI信号强度过滤掉过于微弱的设备 if (device.RSSI && device.RSSI < -70) { return; } if (!deviceMap[key]) { deviceMap[key] = device; } else { // 更新已存在设备的信号强度，避免列表闪烁 deviceMap[key].RSSI = device.RSSI; } }); // 触发页面渲染回调 bluetoothManager._renderDeviceList(deviceMap); }); // 开始扫描 plus.bluetooth.startBluetoothDevicesDiscovery({ allowDuplicatesKey: false, // 默认去重，避免重复上报 interval: 100, // 上报间隔，单位毫秒，越大越省电 success: function() { console.log('扫描启动成功'); }, fail: function(err) { console.error('扫描启动失败', err); } }); // 自动停止扫描，防止持续耗电 scanInterval = setTimeout(function() { plus.bluetooth.stopBluetoothDevicesDiscovery({ success: function() { console.log('扫描已停止'); } }); }, duration || 10000); return scanInterval; };

逻辑说明：deviceMap是用来做设备去重的核心容器。BLE设备在广播时会周期性重复发送广播包，如果不做去重，列表里会出现同一个设备刷屏几十条记录的情况。这里用RSSI < -70过滤是为了避免把信号很弱、根本无法稳定通信的设备列出来干扰选择。

参数说明：allowDuplicatesKey设置为false时，系统会过滤重复广播；设为true则更耗电但能拿到更频繁的RSSI刷新。调试时建议设为true，生产环境设false。interval控制设备上报间隔，实测100毫秒比较均衡，太密集页面频繁刷新会卡顿，太稀疏体验不好。

3.3 第三步：连接设备并遍历服务与特征值

扫描到设备只是万里长征第一步。连接成功后，真正的工作是找到这个设备暴露了哪些服务、每个服务下有哪些特征值。这个过程可能让新手头晕，因为一个BLE设备通常包含多个服务，而每个服务又对应多个特征值，读写和通知往往分布在不同的特征值上。Demo里的做法是递归遍历全部服务，然后打平成一个可索引的映射：

bluetoothManager.connectAndDiscover = function(deviceId, callback) { plus.bluetooth.createBLEConnection({ deviceId: deviceId, timeout: 10000, success: function() { console.log('连接成功:', deviceId); bluetoothManager._discoverServices(deviceId, callback); }, fail: function(err) { console.error('连接失败:', err); // 错误码 10003 表示连接超时或设备不可达 callback && callback({ code: err.code || 10003, message: '连接失败' }); } }); }; // 内部方法：遍历所有服务下的特征值 bluetoothManager._discoverServices = function(deviceId, callback) { var allCharacteristics = {}; var serviceIndex = 0; var servicesList = []; plus.bluetooth.getBLEDeviceServices({ deviceId: deviceId, success: function(res) { servicesList = res.services || []; // 遍历服务，获取每个服务的特征值 var fetchNextService = function() { if (serviceIndex >= servicesList.length) { // 全部遍历完成 callback && callback({ code: 0, services: allCharacteristics }); return; } var service = servicesList[serviceIndex]; var serviceId = service.uuid; plus.bluetooth.getBLEDeviceCharacteristics({ deviceId: deviceId, serviceId: serviceId, success: function(charRes) { var chars = charRes.characteristics || []; allCharacteristics[serviceId] = chars; serviceIndex++; fetchNextService(); }, fail: function(err) { // 单个服务失败不中断，记录后继续下一个 console.warn('获取服务特征值失败:', serviceId, err); serviceIndex++; fetchNextService(); } }); }; fetchNextService(); }, fail: function(err) { callback && callback({ code: err.code, message: '获取服务列表失败' }); } }); };

逻辑说明：fetchNextService是一个递归迭代器，确保在Android设备上即使某个服务读取失败，也不会阻断整个发现流程。很多廉价BLE模组固件写得不太规范，读取某些保留服务会返回无权限错误，这里选择跳过而不是直接让整个流程崩溃。

参数说明：createBLEConnection里的timeout参数要特别注意。iOS上默认连接很快，10000毫秒足够；但Android上如果设备处于深度休眠或距离较远，连接可能持续卡顿。设太短容易误判失败，设太长又会让用户等得焦躁，10秒是折中值。

3.4 第四步：收发数据与开启Notify

BLE通信中，写数据是主动发送，读数据通常不用轮询，而是通过开启Notify让设备主动上报。这两个场景在Demo里被分开处理，因为它们的机制完全不同。

// 发送数据：将字符串转为ArrayBuffer并写入特征值 bluetoothManager.writeData = function(deviceId, serviceId, characteristicId, strData) { // 将字符串按UTF-8编码转为ArrayBuffer var buffer = new ArrayBuffer(strData.length); var dataView = new DataView(buffer); for (var i = 0; i < strData.length; i++) { dataView.setUint8(i, strData.charCodeAt(i)); } // 注意：部分设备要求写入字节长度不能超过MTU-3 plus.bluetooth.writeBLECharacteristicValue({ deviceId: deviceId, serviceId: serviceId, characteristicId: characteristicId, value: buffer, success: function() { console.log('数据写入成功'); }, fail: function(err) { console.error('数据写入失败', err); } }); }; // 接收数据：开启Notify并监听变化 bluetoothManager.startNotify = function(deviceId, serviceId, characteristicId) { plus.bluetooth.notifyBLECharacteristicValueChange({ deviceId: deviceId, serviceId: serviceId, characteristicId: characteristicId, state: true, success: function() { console.log('Notify已开启'); } }); // 全局监听设备数据变化 plus.bluetooth.onBLECharacteristicValueChange(function(res) { if (res.deviceId !== deviceId) return; var byteArray = new Uint8Array(res.value); var resultStr = ''; for (var j = 0; j < byteArray.length; j++) { resultStr += String.fromCharCode(byteArray[j]); } // 将收到的数据抛给业务层 bluetoothManager._onDataReceived && bluetoothManager._onDataReceived(resultStr); }); };

逻辑说明：写入时使用ArrayBuffer而不是直接传字符串，这是HBuilderX官方API的硬性要求。每次发送前先申请一个和字符串等长的字节缓冲区，然后逐字节填入，避免中文等Unicode字符在编码转换时出现乱码。开启Notify后，数据回调是全局的，所以回调里必须比对res.deviceId，否则多个设备连接时会串数据。

参数说明：notifyBLECharacteristicValueChange的state是个布尔值，true开启，false关闭。部分设备在重新连接后需要重新开启Notify，否则会收不到任何数据。这种情况在低功耗传感器里特别常见，后面避坑章节会详细说。

4. 避坑：四个经典踩坑案例与问题排查路径

4.1 现象：Android 10以上扫描不到任何设备

现象描述：项目在Android 8上开发调试时一切正常，升级到Android 10及以上后，扫描列表一只空着，onBluetoothDeviceFound一次都没触发。

原因分析：Android 6.0起，蓝牙扫描开始要求定位权限；Android 10起进一步收紧了规则——必须同时开启定位服务，且应用必须动态申请ACCESS_FINE_LOCATION权限。HBuilderX云打包默认只在manifest.json中声明了蓝牙权限，并没有把定位权限置为必选。更隐蔽的是，小米、华为等厂商ROM还额外加了一道“基于位置的扫描限制”，即使权限开了，如果定位服务没打开，扫描结果依然为空。

解决路径：在manifest.json的permissions节点中，同时加入ACCESS_FINE_LOCATION和ACCESS_COARSE_LOCATION，并在App启动时用plus.android.requestPermissions主动申请定位权限。同时在真机调试时检查定位服务是否处于开启状态。这个坑花了我一整天排查，最终发现是ROM自带的“精准定位”开关在作祟。

4.2 现象：连接成功但无法读写数据，错误码10003反复出现

现象描述：设备能扫描到，也能显示已连接，但一执行writeBLECharacteristicValue就回调失败，错误码10003，偶尔伴随“连接中断”。

原因分析：10003在官方文档里表示连接失败或已断开。实际上在这个场景下，往往是因为连接成功后，操作系统还没来得及完成服务发现，业务层就立刻去写数据。更常见的情况是设备端固件没有正确处理连接事件的时序——它认为连接刚建立，但系统底层还处于GATT服务就绪的过渡期。这时候写数据相当于往一扇还没完全打开的门里递东西。

解决路径：在createBLEConnection的成功回调里，不要立即发送数据，而是等getBLEDeviceServices的所有特征值遍历完成后，再执行写操作。这个Demo里的connectAndDiscover已经做了串行处理，但如果自己改过代码，千万别把连接和发现拆成并行。另一个原因是上次连接未调用closeBLEConnection释放资源，残存的连接句柄导致新连接无法正常收发。调试时，每次断开后都手动调用一次closeBluetoothAdapter，把整个蓝牙栈重置。

4.3 现象：收到数据乱码，或只有一半字节

现象描述：设备端发送一串十六进制AA 55 01 02 03，App侧收到的resultStr变成了乱码，甚至长度都对不上。

原因分析：BLE的MTU默认只有23字节，除去ATT头部的3字节开销，真正能装数据的只有20字节。这不是HBuilderX的限制，而是BLE 4.0协议栈的默认真实情况。更麻烦的是，iOS会自己把MTU协商到更大的值，而Android不同机型协商结果五花八门。当你写数据超过MTU长度时，大部分Android设备会静默丢弃超出的部分；同时，如果你把二进制数据转成字符串时用了默认的UTF-8解码，某些字节落在非ASCII区就会变成乱码。

解决路径：发送端严格分包，每包控制在20字节以内；接收端不要用String.fromCharCode，直接使用Uint8Array处理后按十六进制拼接展示。这个Demo里给出的写入函数比较基础，实际生产代码我会改成这样：

function bufferToHexString(buffer) { var bytes = new Uint8Array(buffer); var hex = []; for (var i = 0; i < bytes.length; i++) { var v = bytes[i].toString(16); if (v.length < 2) v = '0' + v; hex.push(v); } return hex.join(' '); }

这段代码把收到的ArrayBuffer转成十六进制字符串，用来排查数据内容能立刻看清协议对不对。如果要在页面上显示中文，再单独用TextDecoder解码，不要混用字符串转换。

4.4 现象：iOS上断开后无法再次连接，App只能重启

现象描述：所有操作在iOS 14以下都正常，升级到iOS 15后，第一次连接读写都成功，断开后再次扫描、连接，系统弹出了蓝牙配对框，但点了之后App直接无响应，只有杀掉App重开才能恢复。

原因分析：这是HBuilderX的5+引擎对iOS蓝牙回调处理的一个历史包袱。iOS的CoreBluetooth在系统弹配对框时，会打断当前GATT会话，而旧版引擎没有正确处理系统级的中断事件，导致JS层回调永远等不到结果。属于经典的“弹窗阻塞”问题。

解决路径：将蓝牙模块运行逻辑脱离标准内置API，改用官方最新的uni.connectSocket之类替代方案，或者升级到最新的HBuilderX云打包环境，刷新引擎版本。另一个临时规避方案是在调用createBLEConnection之前，先调用一次closeBluetoothAdapter，把之前残留的系统蓝牙会话清干净，让系统以全新状态进入连接流程。代码里加个防抖即可，代价是每次连接前要多花两秒左右的重置时间。

5. 协议组包：把Demo改造成能对接自家硬件透传模块的形态

5.1 定义一套简洁实用的私有帧协议

拿到Demo后，最大的痛点就是怎么把它从“示例”变成“能跑业务的代码”。蓝牙透传模块（比如常用的JDY-08、CC2541等）通常支持AT指令配置和透传模式。透传模式下，App写入什么数据模组就原样发出，但这不等于你可以直接把裸数据扔进去。没有帧头、长度、校验的话，一旦数据隔断或错位，接收端完全无法判断这一包数据的完整性。

我这里设计了一个简单的帧协议，适合控制类设备：

5.2 JavaScript实现封包与解包逻辑

以这个协议为基础，封装两个核心函数：

// 封包：根据命令字和负载数据生成完整帧 function packFrame(cmd, payload) { var len = payload.length; var buffer = new ArrayBuffer(len + 5); var view = new DataView(buffer); view.setUint8(0, 0xAA); // 帧头 view.setUint16(1, len, false); // 长度，大端模式 view.setUint8(3, cmd); // 命令字 for (var i = 0; i < len; i++) { view.setUint8(4 + i, payload[i]); } // 异或校验：从长度字段算到数据字段末尾 var check = 0; for (var j = 1; j < len + 4; j++) { check ^= view.getUint8(j); } view.setUint8(len + 4, check); return buffer; } // 解包：从原始字节中提取完整帧并校验 function parseFrame(bytes) { var length = bytes.length; if (length < 5) return null; // 不足帧头+长度+校验 var view = new Uint8Array(bytes); // 找帧头 var frameStart = -1; for (var i = 0; i < length - 1; i++) { if (view[i] === 0xAA && view[i + 1] === 0xAA) { // 模拟一个双帧头做数据同步（实际使用可去掉） } if (view[i] === 0xAA) { frameStart = i; break; } } if (frameStart === -1) return null; var payloadLen = (view[frameStart + 1] << 8) | view[frameStart + 2]; if (frameStart + 3 + payloadLen + 1 > length) return null; // 数据不够，等待下一包 var dataStart = frameStart + 3; var check = 0; for (var j = frameStart + 1; j < dataStart + payloadLen; j++) { check ^= view[j]; } if (check !== view[dataStart + payloadLen]) { console.warn('校验失败，帧数据损坏'); return null; } return { cmd: view[dataStart], payload: view.slice(dataStart + 1, dataStart + 1 + payloadLen) }; }

逻辑说明：packFrame里的view.setUint16(1, len, false)指定了大端序，这是绝大多数嵌入式设备的默认字节序。parseFrame里对半包数据的处理才是BLE开发的关键——蓝牙传输是流式的，每几十毫秒报一次数，一次回调里可能只有半截帧，所以要先把帧头找到，再判断数据长度是否够，不够就返回null等下一次上报的数据拼接。

参数说明：这里的异或校验比CRC16要轻量得多，适合灯光、开关这类实时性要求高的场景。如果设备端已有硬件CRC硬件单元，也可以换成CRC16/Modbus，原理相同。

5.3 断线重连的工程化处理

Demo里对断线重连的处理比较基础，但实际硬件场景下，用户拿起手机设备可能已经休眠了几分钟，断线是常态。工程化的做法是引入状态机：

bluetoothManager.handleConnectionLoss = function(deviceId) { // 重置设备状态缓存 delete bluetoothManager._deviceCache[deviceId]; // 尝试重连，最多重试3次 var retryCount = 0; var maxRetry = 3; var attemptReconnect = function() { if (retryCount >= maxRetry) { bluetoothManager._emit('disconnected', { deviceId: deviceId }); return; } retryCount++; bluetoothManager.connectAndDiscover(deviceId, function(err) { if (err && err.code === 0) { // 重连成功，恢复Notify状态 bluetoothManager.startNotify(deviceId, serviceId, charId); } else { // 延迟1秒继续尝试 setTimeout(attemptReconnect, 1000); } }); }; attemptReconnect(); };

逻辑说明：重连时的_deviceCache清理非常重要，因为旧的服务信息可能已经失效，不清理会导致读写调用拿到过期的UUID。重连成功后必须重新开启Notify，因为低功耗蓝牙设备在断开后通常不会再主动上报数据。这里的3次重试和1秒间隔是经验值，既不会让用户等太久，也不会因为频繁请求把设备端固件搞出连接风暴。

参数说明：connectAndDiscover如果返回err.code === 0代表成功，这个约定在Demo里是统一定义的。实际硬件连接中，有时候重连失败是因为设备端同时连了其他手机，这种场景下重试也没用，需要提醒用户手动关掉设备侧连接。

6. 真机验证与交付前的最后一道手艺

6.1 两个必测的极端场景

交付前别急着打正式包，先用同样的代码跑两次真机验证。第一测锁屏休眠：页面停留在蓝牙首页，锁屏等5分钟，再解锁，看连接是否还在。大多数坑都是因为这个暴露的——iOS会蹦出“蓝牙已断开”的弹窗，Android则会静默恢复。第二测连续收发压力：用脚本每秒发一包20字节数据，连续发300包，统计丢包率。

6.2 云打包的证书与权限复核

用HBuilderX的云打包功能出正式包前，建议把manifest.json里的权限列表逐条过一遍。Android端不要勾选不必要的权限，比如存储权限如果业务没用到就删掉，避免应用市场上架审核被问询。iOS端要确认NSBluetoothAlwaysUsageDescription描述文案是否写清楚了用途。证书方面用测试证书调试，正式上架再换发布证书，不要混用，否则Android应用签名对不上会导致升级安装失败。

所有的工程我都习惯放在同一个目录下管理，蓝牙模块单独抽离成bluetoothBridge.js，这样以后换项目不用删改历史逻辑，直接引用这个文件，再按硬件需求改改UUID即可。

这也是我为什么把这个Demo推荐给做HBuilderX蓝牙开发的人的一个核心理由：它是少有的没堆花活、直接给你可复用模块的源码。从那以后我每次交付蓝牙模块，都会强制走一遍“锁屏-重连-大数据流”的测试脚本。希望帮到你。

本文还有配套的精品资源，点击获取