微信小程序蓝牙开发全攻略，手把手教你快速上手

打开微信小程序蓝牙开发这个坑之前，我先说句实在话：这玩意儿看着像座小山，其实爬上去也就几条固定的路。我见过太多人卡在第一步，对着文档里那些`wx.openBluetoothAdapter`、`wx.startBluetoothDevicesDiscovery`之类的API发呆，心里直犯嘀咕：这都啥玩意儿？我当初也是这么过来的，翻遍了官方文档，踩了一堆莫名其妙的坑，才把整个流程捋顺。今天这篇东西，不整那些虚头巴脑的理论，就我实际开发中摸爬滚打的经验，给你把从初始化到数据收发这条路，用大白话铺平了。

先说最基础的那个坎：初始化蓝牙适配器。很多人一上来就调用`wx.openBluetoothAdapter`，结果直接弹个`fail`，心里就慌了，以为代码写错了。其实大概率不是你代码的问题，而是手机蓝牙压根没开，或者小程序还没拿到蓝牙权限。这里有个小细节，iOS和Android的行为还不一样。iOS上，如果用户没开蓝牙，这个API会直接报错，你得监听`wx.onBluetoothAdapterStateChange`，在回调里提示用户去设置里打开。Android那边呢，有时候系统会弹个权限框，你得等用户点了允许，再重新调用初始化。所以我的习惯是，初始化之前先检查状态，用`wx.getBluetoothAdapterState`探一下底，再决定要不要调`open`。这个顺序搞反了，后面全是白费功夫。

蓝牙打开之后，第二步就是搜索设备。这步看着简单，就是调`wx.startBluetoothDevicesDiscovery`，但里面的门道多着呢。这个搜索是有功耗的，你不能一直开着，搜到目标设备就得赶紧关掉。搜索回调里返回的`deviceId`是你要存下来的关键东西，但`name`可能为空，尤其是一些杂牌蓝牙模块，广播包里根本没带名字。这时候别慌，你可以先存下`deviceId`，等连接成功后再通过`wx.getBLEDeviceCharacteristics`之类的API去拿详细服务信息。还有个坑是，搜索回调`wx.onBluetoothDeviceFound`会触发很多次，每次返回一批设备，你得自己做去重，不然列表里全是重复项。我一般会维护一个`Map`，用`deviceId`做key，新来的设备信息直接覆盖旧的。

找到设备之后，真正的硬仗才刚开始：连接和获取服务。`wx.createBLEConnection`这个API，参数就是之前存下来的`deviceId`。连接成功之后，你以为就完事了？早着呢。蓝牙设备不像WiFi，连上就能上网，它得先找到服务（Service）和特征值（Characteristic），才能读数据、写数据。这里有个经典操作：先调`wx.getBLEDeviceServices`拿到这个设备所有的服务UUID列表，然后从里面挑出你需要的那个服务，再调`wx.getBLEDeviceCharacteristics`拿到这个服务下的所有特征值。你可能会问，咋知道哪个UUID是干嘛的？这得看你的硬件厂商给不给文档了。通常他们会告诉你，哪个UUID是读数据的，哪个是写指令的，哪个是通知的。没有文档的话，你就只能一个个试，或者用一些通用的蓝牙调试工具先探一遍。

说到读写数据，这里面的坑能让新手摔得鼻青脸肿。先说写数据，调`wx.writeBLECharacteristicValue`的时候，得注意数据格式，必须转成`ArrayBuffer`。很多人拿个字符串直接往里塞，报错报得莫名其妙。正确姿势是，先把字符串转成字节数组，再包成`ArrayBuffer`。还有一个特别容易忽略的点：写操作是有`MTU`限制的，默认一般是20字节一次，你一次写太多数据，超过MTU，数据就发不出去，或者被截断了。这时候你得跟硬件商量，让他们把数据分包发送，或者你在小程序端做分包处理。读数据呢，一般用`wx.notifyBLECharacteristicValueChange`开启监听，然后通过`wx.onBLECharacteristicValueChange`这个回调接收数据。这个回调会一直触发，每次收到数据都得自己拼接，直到凑够一包完整的数据再做解析。这里我吃过一次大亏，硬件那边分包发得太快，小程序这边回调还没处理完，下一包就到了，结果数据全乱了。后来我在回调里加了个队列，一包一包地处理，才算稳定下来。

设备连上之后，还有个管理问题：生命周期。小程序切到后台，或者用户锁屏，蓝牙连接可能会断，也可能不断，这取决于手机品牌和系统版本。你没法控制这个，但你可以监听`wx.onBLEConnectionStateChange`，一旦发现连接断了，就更新UI状态，提示用户重新连接。千万别让用户傻乎乎地对着一个“已连接”的按钮干瞪眼，点半天没反应。还有，页面卸载的时候，比如用户从蓝牙页面跳走了，你得在`onUnload`里调用`wx.closeBLEConnection`主动断开连接，不然下次再进来，蓝牙状态是乱的，连不上新设备。这个细节看着小，但直接影响用户体验，做不好就会被用户骂“这什么破小程序”。

再往深了说，蓝牙开发里最磨人的不是技术本身，而是调试过程。你写好了代码，连上了设备，结果收不到数据，或者数据是乱码，这时候你怎么办？我告诉你，最快的办法不是翻文档，而是先确认硬件那边是不是真的在发数据。你可以用手机自带的蓝牙调试工具，比如iOS上的LightBlue，Android上的nRF Connect，先跟设备连一下，看看能不能收到数据。如果这些工具也收不到，那就是硬件的问题，跟你的代码没关系。如果工具能收到，你的小程序收不到，那就回头查你的UUID有没有写对，`notify`有没有开启，`ArrayBuffer`转换有没有搞错。这种排查思路，比对着代码瞎猜高效十倍。

说到实战场景，我做过一个智能水杯的小程序，那玩意儿就是通过蓝牙把水温、水量这些数据传上来。当时最头疼的就是数据格式，硬件那边发过来的是一堆十六进制字节流，我得自己解析成温度值。比如第一字节是温度整数部分，第二字节是小数部分，第三字节是电量百分比，这种协议就得跟硬件工程师反复对齐，一个字节对不上，显示的温度就是离谱的。后来我发现一个规律：凡是这种自定义协议的蓝牙设备，最好在开发初期就把协议文档敲定，用表格把每个字节的含义列清楚，两边照着实现，能省掉后面百分之八十的扯皮时间。

我还得提醒你一句：别把所有逻辑都堆在蓝牙API的原始回调里。那代码写出来，过个两周你自己都看不懂。我现在的习惯是，写一个专门的`BluetoothManager`类，把初始化、扫描、连接、断开、数据收发这些操作都封装成Promise方法，上层页面只管调用和监听事件。比如连接设备，就调`connect(deviceId)`，返回一个Promise，成功了就跳转页面，失败了就弹toast。数据接收呢，用事件订阅的方式，页面在`onShow`时订阅，`onHide`时取消订阅。这样代码结构清晰，出问题了也好排查，维护起来也不至于想骂人。

微信小程序蓝牙开发这条路，说难也难，说简单也简单。难在你得把API的每个细节都吃透，把硬件的协议摸清楚，还得应付各种安卓机型的兼容性问题。简单在于，核心流程就那么几步：初始化、扫描、连接、找服务、读写数据，把这五步走顺了，百分之八十的场景都能覆盖。剩下的那些坑，都是你亲手踩过之后才知道怎么绕开的。我写这篇东西，不是让你看完就成为蓝牙专家，而是让你少走点弯路，心里有个底。下次再有人问你小程序蓝牙开发难不难，你就可以拍着胸脯告诉他：不难，就是坑多了点，但你只要按着这条路走，一步一个脚印，准能把数据从设备里抠出来。