蓝牙微信小程序开发，从入门到上线的完整指南

去年夏天，有个做智能硬件的朋友找我诉苦。他花了三个月做出来的蓝牙温湿度计，硬件调得稳稳当当，却在配网环节被用户骂成了筛子——App里那个蓝牙搜索列表，安卓手机上死活刷不出设备，苹果手机上倒是能刷出来，但连上之后数据又不刷新。他问我有没有办法，我说你试试微信小程序吧，他当时就愣了：小程序也能玩蓝牙？

能，而且比你想象中成熟得多。微信小程序从2017年就开始开放蓝牙API，到现在已经迭代出了完整的蓝牙低功耗（BLE）能力矩阵。你不需要去开发原生App，不用上架应用商店，用户扫个码就能用你的硬件。对做智能硬件的小团队来说，这几乎是成本最低的落地路径。今天这篇东西，就是把我自己踩过的坑、趟过的河，整理成一份从零到上线的实操指南。

先从最基础的说起。蓝牙小程序开发，本质上就是通过微信提供的wx.openBluetoothAdapter、wx.startBluetoothDevicesDiscovery、wx.createBLEConnection这一整套API，去和你的硬件设备打交道。这里有个关键概念你得先搞明白：微信小程序里说的蓝牙，默认都是指BLE（低功耗蓝牙），也就是蓝牙4.0及以上版本。如果你的硬件还是老的蓝牙2.0/3.0那种经典蓝牙，那对不起，微信小程序直接不支持，你得换个思路。

初始化这块有个坑，我估计十个新手九个会踩。wx.openBluetoothAdapter这个API，在iOS和安卓上的表现完全不一样。iOS上如果你不先调用这个API，后面的搜索、连接全部白搭；但安卓上有些机型，你调用了反而会弹出权限申请框，用户一旦拒绝，整个蓝牙功能就废了。我的建议是，在调用openBluetoothAdapter之前，先做一个兼容性判断——用wx.getSystemInfoSync()拿到系统版本，iOS直接调，安卓的话先引导用户打开手机蓝牙开关，再调API，成功率能提升一大截。

说完初始化，再聊扫描。wx.startBluetoothDevicesDiscovery这个API，有个特别容易让人迷惑的参数叫allowDuplicatesKey。默认是false，意思是同一个设备只回调一次。但如果你要做实时信号强度（RSSI）显示，或者需要持续跟踪设备位置，就得把allowDuplicatesKey设为true，让设备重复上报。这里有个性能陷阱：设成true之后，回调频率会变得极其高，如果你的处理逻辑不够轻量，小程序直接卡死。我的做法是，在回调里只做一件事——把设备信息塞进一个数组，然后节流（throttle）更新UI，比如500毫秒刷新一次列表。

连接这块，。wx.createBLEConnection连接成功后，你要拿到的核心东西是deviceId和serviceId。这时候你会发现，不同厂家的蓝牙模块，serviceId长得完全不一样。有的用标准的UUID，比如0xFFE0，有的用自定义的128位UUID，比如6E4001-B5A3-F393-E0A9-E50E24DCCA9E。你在文档里看到的那些示例代码，基本都是拿标准UUID写的，但实际你连上设备后，得先调用wx.getBLEDeviceServices拿到所有serviceId，再一个个去匹配你硬件文档里写好的那个。没有捷径，就是老老实实做一层service匹配逻辑。

数据交互是重头戏，也是问题最多的地方。BLE通信有个特点，每次读写数据包最大是20字节（MTU默认23，去掉3字节头）。你的硬件如果一次要传200字节的数据，就得自己定义分包协议。我见过最惨的案例，是有人直接把整个JSON字符串塞进writeBLECharacteristicValue，结果数据被截断，硬件端解析全乱。正确的做法是，在硬件和软件之间约定一个简单的帧格式，比如前2字节是总长度，中间是数据体，1字节是校验和。小程序端按这个协议分包发送，硬件端按协议重组，才能保证数据完整。

还有写入的时序问题。BLE的write操作，每次都要等上一次的写回调返回后，才能发下一次。如果你不管三七二十一，for循环里连续调writeBLECharacteristicValue，大概率会丢包。正确姿势是用递归或队列，一次只发一包，收到wx.onBLECharacteristicValueChange回调后再发下一包。这个细节，直接决定你的小程序在真实场景下稳不稳。

再来说说通知。wx.notifyBLECharacteristicValueChange这个API，是让硬件主动往小程序推数据的关键。但很多新手不知道，这个API必须在连接成功后才能调，而且要在获取到正确的serviceId和characteristicId之后。你从getBLEDeviceCharacteristics拿到的characteristic列表里，要找到那个properties里包含notify标志的特征值，然后调用notifyAPI，之后每次硬件往这个特征值写数据，小程序端的onBLECharacteristicValueChange回调就会触发。整个过程，就是一次“订阅”操作，订阅成功后，数据才会源源不断地流过来。

测试的时候你会发现，真机调试和模拟器完全是两个世界。微信开发者工具里的模拟器，蓝牙功能基本是废的——它没有真实的蓝牙硬件。所以你必须用真机调试，而且最好准备两台手机，一台安卓一台iPhone，因为两端的API行为差异太大了。我自己的习惯是，先拿iPhone调通完整流程，再用安卓测一遍，重点看权限弹窗、连接稳定性、以及断线重连这几个环节。

断线重连这个话题，99%的教程都不会讲，但实际使用中几乎必然遇到。用户手机锁屏、走出蓝牙范围、或者系统内存紧张杀掉小程序，都会导致连接断开。你得监听wx.onBLEConnectionStateChange，一旦状态变成disconnected，就自动重新扫描、重新连接。这里有个细节：重新连接之前，一定要先调用wx.closeBLEConnection清理掉旧连接，否则新连接经常失败。而且重连次数要有限制，比如最多重试3次，每次间隔2秒，避免无限重试把用户手机耗干。

还有蓝牙适配器状态变化。用户可能在小程序使用过程中，去系统设置里把蓝牙关了，或者开了飞行模式。这时候wx.onBluetoothAdapterStateChange会触发，你得在回调里更新UI，提示用户打开蓝牙。如果用户蓝牙一直关着，你的扫描API会反复报错，所以最好在扫描之前就检查一下adapterState，避免无效调用。

开发完成之后，上线前还有几件事必须做。第一，蓝牙权限的说明文案一定要写清楚。微信审核的时候，如果你用到蓝牙API，必须在后台配置隐私保护指引，说明你收集哪些数据、用在哪里。很多开发者在审核被拒，都是因为文案写得含糊。我的建议是直接写“用于连接您附近的智能硬件设备，实现数据同步和远程控制”，别整虚的。第二，做好兼容性标注。微信官方有个蓝牙兼容性列表，不同机型、不同微信版本对蓝牙API的支持程度不一样，你得在页面上做个检测，如果系统版本太低，直接给出引导升级提示。

聊点实在的。蓝牙小程序的坑，远比文档里写的多。比如安卓上有些定制ROM，会限制后台蓝牙扫描频率，你得在onHide的时候主动停止扫描，否则会被系统杀掉；再比如iOS上如果你没有在plist里声明NSBluetoothAlwaysUsageDescription，小程序API会直接fail，但这个小程序端的manifest.json里也能配，别漏了。

我那个做温湿度计的朋友，后来用这套流程重构了小程序，用户反馈从“连不上”变成了“秒连”。他说最感慨的是，不用上架App Store，不用发版审核，改完代码直接提审小程序，当天就能过。这种灵活性，对硬件创业团队来说，比什么都重要。

从入门到上线，其实没有那么多玄学，就是一个个API、一个个回调函数、一个个机型适配堆出来的。你只要记住：先搞懂BLE的基本概念，再动手写代码；先用真机测通主流程，再优化细节；先保证稳定连接，再谈花哨交互。蓝牙小程序开发这条路，走通一次，后面就顺了。