微信小程序蓝牙连接读写实战：从扫描到数据分包完整指南

微信小程序蓝牙连接读写数据，这个需求这两年越来越多。智能硬件厂商想把控制页面做进小程序，节省一个独立 App 的成本；做运动健康的团队想让手表、心率带直接连接手机；连一些工业巡检设备都开始用小程序做临场调试。但真做起来你就会发现，网上大部分教程只写到“能扫到设备”就结束了，一旦涉及连接稳定、数据分包、异常重连，资料立刻变得稀碎。这篇文章是我踩过不少坑之后整理出来的一套实战流程，核心讲清楚小程序端 BLE 的扫描、连接、读写这几个环节，以及每个环节最容易翻车的地方，适合刚接手小程序外设开发、或者已经被蓝牙问题磨到心态崩掉的同学。

先说一个很多新手搞混的点：微信小程序并不支持操作所有蓝牙设备，它只开放了低功耗蓝牙（BLE）的能力。这意味着你的外设必须支持 BLE，否则小程序这边再怎么写代码都没有用。下面我按实操顺序，从设备协议、工程配置、扫描连接、数据读写到排障技巧，完整过一遍。

1. 实战前的整体认知：小程序蓝牙到底怎么工作

1.1 小程序蓝牙能做什么，不能做什么

微信小程序的蓝牙 API 本质上是把手机系统蓝牙栈封装成了 JS 接口，你调用wx.openBluetoothAdapter时，底层操作的其实是手机系统蓝牙模块。但微信只开放了部分能力，不是把整个蓝牙协议栈都给你。

当前小程序能做的事包括：初始化蓝牙适配器、开始/停止扫描、监听发现设备、建立连接、获取服务和特征值、读取特征值、写入特征值、开启通知。不能做的事包括：让手机作为蓝牙外设被其他设备扫描、直接操作经典蓝牙 SPP 通道、修改系统蓝牙底层参数等。所以小程序的角色永远是“中心设备”，负责主动扫描和连接，而你要控制的硬件通常是“外围设备”，负责广播和响应。

这个模型很像一个社交场景：外设是“贴着二维码的商家”，小程序是“路过扫码的顾客”。商家不能反过来加顾客微信，顾客必须主动扫码。小程序端所有流程都围绕“主动发现、主动连接、主动读写”展开。

1.2 为什么你的设备必须是 BLE，而不是普通蓝牙

很多硬件项目早期用的是经典蓝牙，比如一个单片机通过蓝牙模块和手机 App 做串口透传。这种模块成本低、资料多，但微信小程序不支持，因为小程序 API 里没有 SPP 通道。你只能在支持 BLE 的从机模式下通过 GATT 服务来通信。

BLE 和经典蓝牙最大的区别在于通信模型：经典蓝牙建立的是持续连接，像打电话，一直占用信道；BLE 则是“广播-连接-数据交互-休眠”的短连接模型，像发微信消息，需要时才传输。BLE 功耗更低、连接更快，但单次传输数据量也小，MTU 默认只有 20 字节左右，所以不能像串口透传那样一大段一大段地发。

我后来总结了一个类比：BLE 外设就像一面公告板，板上贴了几张表格（服务），每张表格里又有几个抽屉（特征值）。你要读数据，就得先找到公告板，找到对应表格，再打开抽屉看内容。小程序蓝牙开发的全过程，就是“找到公告板、找到表格、开抽屉、交换字条”的过程。

1.3 典型场景：这些项目最适合小程序蓝牙

从实际项目看，小程序蓝牙最常见的是这几类：一是智能家居控制，比如灯、锁、窗帘，小程序扫码后直接连蓝牙控制，省去 App 下载成本；二是健康设备，比如心率带、体脂秤、血糖仪，连接后读取测量数据；三是防丢器和标签类设备，读广播数据或者触发警报；四是工业/巡检类的数据采集终端，用小程序做临时配置和离线调试。

这些场景有一个共同点：数据量不大，交互频率不高，协议相对固定。如果你的业务需要高频率、大数据量持续传输，比如音频流、文件传输，那小程序 BLE 就不是最优选择，可以考虑其他传输方式。做好这个判断能避免后面白写一大堆代码。

2. 准备工作：从硬件选型到工程配置，漏一步就白折腾

2.1 动手写代码前，先读懂外设的协议文档

这是我吃过大亏的地方。有一次我拿到一款温湿度计模块，没看协议文档就开始写扫描代码，结果扫到了设备，连接也成功，但读特征值一直是空数据。后来才发现这个模块的数据根本不是主动读回来的，而是要开启 Notify 后由设备主动上报，我对着 read 接口折腾了大半天。

所以第一步永远是先找外设的协议文档，确认这几个信息：

• 设备的广播名称叫什么，扫描后怎么过滤；
• 设备在广播包里有没有暴露 Service UUID，有的话可以用这个 UUID 做精确过滤；
• 需要操作的目标 Service UUID 和 Characteristic UUID 是哪几个；
• 每个特征值的属性是什么：只读、可写、支持通知还是支持指示；
• 数据格式：大端还是小端，字段怎么排列，有没有校验位，命令要不要分包。

如果你手头没有任何文档，最靠谱的办法是先用手机上的通用蓝牙调试工具手动连一次。这类工具可以直接看到服务列表、特征值属性，还能手动读写数据。我把这个过程叫做“协议摸查”，相当于学游泳前先在浅水区走一圈，后面代码写起来会踏实很多。

2.2 工程配置和权限声明：Android 和 iOS 有不同的隐形门槛

微信小程序调用蓝牙接口本身不需要额外引入 npm 包，但工程配置直接影响你能否正常调起蓝牙，尤其是 Android。Android 6.0 以上扫描蓝牙设备需要定位权限，如果你在 app.json 里没有配置 location 相关的 permission 说明，直接调用wx.startBluetoothDevicesDiscovery经常会没有任何回调。

我通常会在 app.json 里加上类似这样的配置：

"permission": { "scope.userLocation": { "desc": "用于扫描附近蓝牙设备" } }

同时在微信公众平台后台的“用户隐私保护指引”里，把“位置信息”和“蓝牙”的使用目的都填写清楚。这一步看起来只是后台配置，但漏掉之后真机调试时很可能报权限错误，而且提示还不明确。

iOS 端则需要特别注意：系统不会给小程序返回蓝牙设备的 MAC 地址，设备列表里只有 deviceId 和 localName。所以如果你的过滤逻辑依赖 MAC 地址，在 iOS 上一定拿不到。更合理的做法是用 Service UUID 过滤，或者让用户在界面上手动选择要连接的设备。

2.3 初始化蓝牙适配器，不是简单调一次 open 就完事

所有蓝牙操作之前，必须先调wx.openBluetoothAdapter。很多教程只写了这一句，实际上完整流程应该更稳妥：先 open，再获取适配器状态，然后再注册设备监听，最后才开始扫描。

我的初始化习惯是封装一个initBle()方法，内部按顺序执行：

function initBle() { return new Promise((resolve, reject) => { wx.openBluetoothAdapter({ success(res) { // open 成功后再查一下蓝牙是否打开 wx.getBluetoothAdapterState({ success(state) { if (state.available) { resolve(state); } else { reject(new Error('蓝牙未开启')); } }, fail: reject }); }, fail(err) { reject(err); } }); }); }

这里有几个容易踩的坑：一是wx.openBluetoothAdapter如果蓝牙本身没打开，会在 fail 里抛错误；二是页面 onLoad 时不适合立刻初始化蓝牙，因为 iOS 上有些接口必须在用户点按触发的事件里调用才稳定，我习惯用一个“搜索设备”按钮去触发；三是 open 成功不代表适配器可用，还要看available字段，所以一定要做状态判断。

还有一点很重要：在开始扫描前，先用wx.onBluetoothDeviceFound注册监听。如果先startDiscovery再注册监听，很可能会漏掉前几次回调，导致设备列表少设备。别问我是怎么知道的，问就是被坑过。

3. 扫描与连接：从发现设备到拿到特征值，每一步都不简单

3.1 扫描：过滤条件写得越精确，后面越省心

调用wx.startBluetoothDevicesDiscovery时，如果不传services参数，小程序会把周围所有 BLE 设备都扫出来，包括耳机、手环、电子秤，列表会很乱，而且回调非常频繁，容易影响主线程性能。

我一般会在确认目标设备的 Service UUID 后，把 UUID 放到services数组里做精确过滤：

wx.startBluetoothDevicesDiscovery({ services: [primaryServiceUUID], // 用目标服务的 UUID 过滤 allowDuplicatesKey: false, success(res) { console.log('开始扫描', res); }, fail(err) { console.error('扫描失败', err); } });

如果没有拿到 Service UUID，那就先空扫描，然后在wx.onBluetoothDeviceFound回调里自己过滤。注意这个回调返回的是一个设备数组，而且同一个设备可能被重复上报多次，不能直接setData覆盖，需要按deviceId去重，把 RSSI 信号强度存下来，再按信号从强到弱排序。

扫描完成后，连接设备前一定要调用wx.stopBluetoothDevicesDiscovery停止扫描。我以前以为连上设备后系统会自动停止，结果发现连接质量很不稳定，后来查资料才知道，持续扫描和 BLE 连接会互相干扰。所以正确的流程是：扫到目标设备 -> 停止扫描 -> 发起连接。

3.2 连接：createBLEConnection 的正确打开方式

连接用wx.createBLEConnection，传设备deviceId就行。但这个接口有几个特别容易翻车的点。

第一个点是连接超时。如果你的外设离得太远、或者已经被另一个手机占用，连接回调会一直不触发，用户体验就是“转圈转半天”。我一般会包一层 Promise，同时挂一个 10 秒的 setTimeout，超时后主动调wx.closeBLEConnection，并提示用户重试。

function connectDevice(deviceId, timeout = 10000) { return new Promise((resolve, reject) => { const timer = setTimeout(() => { wx.closeBLEConnection({ deviceId }); reject(new Error('连接超时')); }, timeout); wx.createBLEConnection({ deviceId, success(res) { clearTimeout(timer); resolve(res); }, fail(err) { clearTimeout(timer); reject(err); } }); }); }

第二个点是连接成功后不要立刻去获取服务。有些蓝牙外设刚连上的瞬间，服务列表还没有准备好，立刻调getBLEDeviceServices会拿到空数组。我习惯了在连接成功的回调里加一个 100～200ms 的短延时，然后再去发现服务。这个延时不是标准文档要求，但实测对很多低成本 BLE 模块非常有效。

第三个点是批量设备的并发连接。如果不做控制，用户快速点击多个设备时，会同时发起多个createBLEConnection，很多外设只支持单连接，结果就是互相打断。我之前在页面上加了一个isConnecting标志位，连接完成前禁止再次点击。

3.3 服务与特征值：这一步决定了你到底能不能读写

连接成功后，需要依次调用wx.getBLEDeviceServices拿到 Service 列表，再根据目标 Service 调wx.getBLEDeviceCharacteristics拿到特征值列表。这里面的核心坑是 UUID 的大小写。

微信小程序文档明确说：UUID 对大小写敏感。Android 端返回的 UUID 常常是小写，iOS 端可能是大写，而你的外设文档里写的一般是大写。如果你直接用字符串比较，很容易因为大小写不一致而找不到目标服务。我的做法是：拿到所有 UUID 后，统一转成小写再比较，比较逻辑也用小写：

function findService(services, targetUUID) { const target = targetUUID.toLowerCase(); return services.find(item => item.uuid.toLowerCase() === target); }

特征值列表里的properties字段会告诉你这个特征值支持哪些操作：

• read：支持主动读取；
• write：支持写入，且对方会回复；
• writeNoResponse：支持无回复写入；
• notify：支持通知；
• indicate：支持指示。

很多新手会拿一个只支持 notify 的特征值去调 read，结果一直失败。正确做法是先判断 properties，再决定走哪条路。比如要收实时数据，就得找notify为 true 的特征值；要发命令，就得找write或writeNoResponse为 true 的特征值。

获取这些信息时，注意要先拿到 Service 再拿 Characteristic，因为getBLEDeviceCharacteristics需要传serviceId。很多人会直接跳过服务列表去调特征值，这是常见的顺序错误。

4. 数据读写：从“连上”到“能通信”的最后一公里

4.1 先搞定 ArrayBuffer 和字符串的互相转换

BLE 通信传输的是二进制数据，小程序 API 里 value 的类型是 ArrayBuffer，很多新手直接把字符串传进去会报错。我一般会准备几个工具函数，放在公共模块里：

// ArrayBuffer 转十六进制字符串 function ab2hex(buffer) { const bytes = new Uint8Array(buffer); return Array.from(bytes).map(b => b.toString(16).padStart(2, '0')).join(''); } // 十六进制字符串转 ArrayBuffer function hex2ab(hex) { const clean = hex.replace(/\s/g, ''); const buffer = new ArrayBuffer(clean.length / 2); const view = new DataView(buffer); for (let i = 0; i < clean.length; i += 2) { view.setUint8(i / 2, parseInt(clean.substr(i, 2), 16)); } return buffer; } // ArrayBuffer 转字符串（兼容 UTF-8 简单场景） function ab2str(buffer) { return new TextDecoder().decode(new Uint8Array(buffer)); } // 字符串转 ArrayBuffer function str2ab(str) { const bytes = new TextEncoder().encode(str); return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength); }

这些函数看着不起眼，但实际调试时没有它们，你根本不知道设备返回了什么，也没法把命令一键拼成代码里能用的格式。建议所有蓝牙页面都复用同一套工具函数，避免到处复制粘贴。

调试时还有一个习惯很推荐：写一个通用日志函数，把十六进制数据、ASCII 可显示内容一起打出来。有些设备返回的是 ASCII 码文本，有些是纯二进制，只打一种格式很难判断问题。

4.2 收数据：主动读 vs 被动通知，两者差别很大

接收数据有两个方式：主动调wx.readBLECharacteristicValue，或者开启 Notify 后被设备推送。

主动读适合“问一句答一句”的场景，比如点一下界面上的“读取电量”，然后去读电量特征值。主动读的结果会在wx.onBLECharacteristicValueChange回调里返回，注意不是 read 接口的 success 里返回，这个很多人会看懵。实际代码是这样的：

function readValue(deviceId, serviceId, characteristicId) { return new Promise((resolve, reject) => { wx.readBLECharacteristicValue({ deviceId, serviceId, characteristicId, success() { // 真正数据要等 onBLECharacteristicValueChange }, fail: reject }); }); }

被动通知适合持续上传的场景，比如心率带每秒上报一次心跳，或者体脂秤测量完成后主动推结果。开启通知的代码是：

wx.notifyBLECharacteristicValueChange({ deviceId, serviceId, characteristicId, state: true, // true 开启通知 success(res) { console.log('notify 开启成功'); }, fail(err) { console.error('notify 开启失败', err); } });

开启 Notify 前，一定要确认特征值的properties.notify为 true。如果外设只支持 read，你开 notify 会失败。另外，开启成功之后也要在wx.onBLECharacteristicValueChange里做分发处理，因为所有特征值的数据通知都会走同一个回调。

wx.onBLECharacteristicValueChange是全局唯一的，所以页面有多个特征值时，要在回调里根据characteristicId做分支，把数据投递到对应的处理函数。我见过有开发者在这个回调里直接 setData，导致多个数据源互相覆盖，后来改成 Map 按特征值存数据才解决。

4.3 发数据：一个 20 字节分包的经典问题

写入数据用wx.writeBLECharacteristicValue，value 必须是 ArrayBuffer，参数需要 deviceId、serviceId、characteristicId。这是整条链路里大家报错最多的地方，主要集中在这几类。

第一类是不判断特征值是否可写。写之前先看 properties 里的write或writeNoResponse，如果是 false，调了也白调。第二类是数据超过 20 字节。微信小程序没有暴露设置 MTU 的接口，所以稳妥做法是默认按 20 字节分包，所有超过 20 字节的命令都切成多包发送。第三类是不等上一包返回就发下一包，有些外设的接收缓冲区很小，发太快会丢包。

分包发送的核心思路很简单：把原始命令按 20 字节切块，每块加一个包序号，接收方按序号拼回去。比如要发送一个 60 字节的加密固件升级包，没法一次发完，我会定义一个发送队列：

let sendQueue = []; let isSending = false; function enqueueWrite(deviceId, serviceId, characteristicId, chunks) { chunks.forEach((chunk, index) => { sendQueue.push({ chunk, index, total: chunks.length }); }); processSendQueue(deviceId, serviceId, characteristicId); } function processSendQueue(deviceId, serviceId, characteristicId) { if (isSending || sendQueue.length === 0) return; const item = sendQueue.shift(); isSending = true; wx.writeBLECharacteristicValue({ deviceId, serviceId, characteristicId, value: item.chunk, success() { isSending = false; // 可以在这里记录发送进度 processSendQueue(deviceId, serviceId, characteristicId); }, fail(err) { isSending = false; console.error('发送失败', err, item); // 简单策略：把当前包放回队首重试，最多重试3次 if (item.retryCount === undefined) item.retryCount = 0; item.retryCount++; if (item.retryCount < 3) { sendQueue.unshift(item); } processSendQueue(deviceId, serviceId, characteristicId); } }); }

这里的核心是串行发送，不能并发。因为很多外设不具备接收乱序包的能力，必须等上一包 write 成功回调后再发下一包。发送前我会先跟外设协议核对广播和命令是否有应答机制，如果没有，我会在业务层加一个超时重传逻辑，否则在真实环境中丢包后很难定位。

4.4 一个极简的 BLE 管理器封装思路

随着项目复杂度上升，直接把 API 散在页面里会非常难维护。我最后都会封装一个BleManager类，把扫描、连接、发现、读写、关闭统一起来，页面只处理业务数据。

大概结构如下：

class BleManager { constructor() { this.deviceId = null; this.isReady = false; } async init() { await this.openAdapter(); this.registerDiscoveryHandler(); } startScan(filterUUID) { return new Promise((resolve, reject) => { wx.startBluetoothDevicesDiscovery({ services: filterUUID ? [filterUUID] : [], allowDuplicatesKey: false, success: resolve, fail: reject }); }); } async connect(deviceId) { this.deviceId = deviceId; await this.stopScan(); await this.createConnection(deviceId); await this.discoverServices(deviceId); } stopScan() { return new Promise(resolve => { wx.stopBluetoothDevicesDiscovery({ complete: resolve }); }); } createConnection(deviceId) { // 包含超时逻辑 } discoverServices(deviceId) { // 获取服务列表和特征值，缓存到 Map } async write(data) { // 分包写入，需要指定 serviceId/characteristicId } async read() { // 读取值，返回 Promise } async enableNotify(handler) { // 开启指定特征值通知，并注册统一回调 } close() { if (this.deviceId) { wx.closeBLEConnection({ deviceId: this.deviceId }); } } } module.exports = new BleManager();

封装完成后，页面里的业务代码就干净很多。比如一个温度计页面，只需要在 onLoad 里初始化管理器，在按钮点击后扫描连接，在 Notify 回调里刷新 UI 即可。后面如果换外设协议，只需要改管理器和协议解析层，页面几乎不用动。

5. 真机调试与问题排查：把我踩过的坑整理给你

5.1 调试流程：先用通用工具摸清协议，再写代码

小程序蓝牙最大的痛点是开发者工具基本不能用于真机蓝牙调试，必须真机跑。而且你没法像 PC 端那样抓完整的蓝牙日志，所以在写业务代码前，用通用蓝牙调试工具把读写流程跑通，是很值得的投资。

我的标准流程是这样：先把设备用某种调试软件连接上，手动扫描服务、查看特征值，然后手动执行 read、write、notify 三组操作，确认哪个特征值能读、哪个能写、哪个能通知。同时把收到的原始数据截图保存，字段含义逐条标注。

这一步做完，我对协议的理解才真正完整。否则我对着文档猜测 writed 的格式，很可能写错了都不知道。调试工具里能看到成功写入的字节数、返回的错误码，这些信息比在小程序里猜要直观得多。

小程序真机调试时，我会打开 vConsole 看 console 日志。其实 vConsole 不是专门给蓝牙用的，但能帮我在手机上直接看到 Promise 是否 reject、错误码是什么，省去一遍遍蓝牙传日志给电脑的麻烦。当然，更严谨的做法是在代码里把关键日志上传到远程日志服务，不过大部分项目前期用 vConsole 就够了。

5.2 高频问题速查表

我把实际项目中遇到最多的问题整理成了一张表，方便你们对照排查。

这张表覆盖了我遇到过的大部分问题。如果你看到的现象不在表里，最有效的排查方法是把三层日志全部拉出来：小程序 API 回调的错误码、调试工具里的协议交互记录、以及外设端的日志。三层一对比，问题基本能定位到某一层。

5.3 断线重连与日志策略：关键时刻能救命

蓝牙连接在真实环境中非常容易断，尤其是用户走远、外设休眠、或者系统资源紧张时。小程序提供的wx.onBLEConnectionStateChange可以监听连接状态变化，一旦状态变为 disconnected，要主动清理资源并提示用户重连。

我的重连策略不复杂：收到断开回调后，先把当前连接的 deviceId 保存起来，关闭所有通知监听，调用wx.closeBLEConnection确保连接资源释放，然后走重新初始化流程。重连不是无限循环，最多重试 3 次，每次间隔 1 秒、2 秒、4 秒递增，超过次数就通知用户手动操作。

日志方面，我会给每个蓝牙操作加一个带时间戳的日志前缀，比如[BLE][startScan] 12:00:01。排查问题时，这些日志能帮你还原操作顺序。蓝牙问题有个特点：很多故障是时序问题，而不是逻辑问题。比如“先扫描再连接”和“先连接再扫描”对结果影响很大，只有完整的日志才能帮你看出时序。

最后再分享一个我后来一直坚持的小习惯：每接到一个新外设，第一时间用调试工具跑通用读写，然后把原始报文截图存到项目文档里。这个动作花不了十分钟，但能让你在隔了几个月后重新接这块板子的时候，不需要再翻旧聊天记录找协议。蓝牙开发大多数时候不是难在智商，而是难在细节，把这些顺序、大小写、分包、超时的功课做扎实了，你就能少熬好几个夜。如果你现在正卡在某个蓝牙问题上，不妨按这个顺序重新捋一遍链路，大部分问题都在这个链路里。