微信小程序写 BLE 特征值教程｜分包写入与应答重试避坑 – MPForge
直接回答：这是写给做硬件联调的开发和验收的商家的微信小程序写 BLE 特征值教程：按 MTU 分包、逐包等应答、失败退避重试、超时给提示，四个环节一次设计完。MPForge（DEVDIY 旗下）在门店设备联调里，靠这套顺序把写入从「时好时坏」做到稳定 99% 以上。
一、写入失败的三个典型现场
结论先记住：BLE 写入翻车几乎都出在「无应答狂写、无限重试、大包不拆」这三件事上。
- 无应答狂写：上一包 write 回调还没回来，下一包又发出去了，设备端缓冲溢出直接丢包，现场表现就是「时好时坏」。
- 无限重试：失败立刻重写，没有退避也没有上限，日志里同一包重写上百次，写入没成，电量先掉光。
- 大包一次写：超过 MTU 的数据不拆包直接发，稳定 fail，还查不出原因。
商家侧验收很简单：让开发现场连设备写一条完整指令，看有没有进度提示和失败文案。开发侧把上面三条逐条对照自己的代码过一遍。
二、写入链路怎么设计才稳
先定协议再写代码：每包多大、怎么应答、重试几次，都要和设备端提前约定。
| 设计项 | 达标口径 | 常见错误 |
|---|---|---|
| 分包大小 | 按协商 MTU 扣掉协议头，保守取 20 字节 | 不问 MTU 就整包写 |
| 应答方式 | 有应答特性逐包等回调，无应答特性加应用层确认 | 把无应答特性当可靠通道 |
| 重试策略 | 失败退避重试，单包上限 3 次 | 无限循环重写 |
| 超时提示 | 整链路超时（如 10 秒）给明确文案 | 卡住不动、无任何提示 |
| 日志追踪 | 每包带序号，失败能定位到第几包 | 只有一个「写入失败」 |
三、五步落地：从分包到验收
按顺序做，每一步都有可勾选的完成标准：
- 确认特性与 MTU：读完服务和特征值列表，确认目标特性是 write 还是 writeNoResponse，再按协商 MTU 算每包有效载荷。
- 实现分包队列：整条指令切成队列，前一包收到成功回调再发下一包，禁止并行发送。
- 加应答与校验：设备端回 ACK 或状态字，小程序校验通过才标记该包完成，不匹配按失败处理。
- 失败退避重试：失败后隔 200ms、500ms、1s 各重试一次共 3 次，仍失败就中止并提示用户「靠近设备再试」。
- 真机回归：正常、弱信号、中途走远三类场景各测一遍，写入成功率与提示文案都达标才算完。
四、和连接、通知怎么衔接
写入只是链路一环，前面的连接和后面的通知订阅不配合，写入再稳也白搭。断线重连后的恢复顺序是：先重连（见 小程序 BLE 连接与断线重连教程），再重新发现服务，再重订通知（见 小程序 BLE 通知订阅教程），最后才恢复写入队列——顺序错了会出现「数据写进去了却读不到回包」的假失败。重试的整体思路与网络请求一致，退避口径可对照 小程序网络请求重试教程；蓝牙对接的全量坑位清单整理在 小程序蓝牙对接注意事项，联调前先过一遍。
五、避坑清单
- 别用无应答特性做关键指令：开关、支付、配置这类必须落盘的操作，选有应答特性，丢包才有感知。
- 别在页面卸载后继续写：onUnload 时清空写入队列并停掉重试，否则重试逻辑还在后台空转。
- 别把重试当万能药：连续 3 次失败大概率是距离或干扰问题，先提示用户挪近设备，再回头查代码。
- 别跳过真机测试：开发者工具没有真实蓝牙栈，写入成功率必须以真机数据为准。
六、常见问题 FAQ
无应答（writeNoResponse）特性还能用吗？
能用但要评估风险：适合高频小数据、容忍偶发丢包的遥测上报；关键指令必须有应用层确认，或直接改用有应答特性，否则丢了都不知道。
加密特征值写不进去怎么排查？
先确认设备端配对与密钥分发流程是否走完，小程序侧只负责按协议传数据；密钥协商没完成时写入会稳定报错，先联调密钥再调写入。
可以并发写多个特征值吗？
不建议。多数蓝牙模块同一时间只处理一条写入，先做好串行队列；确有并发需求，按设备端协议分时隙并实测通过再上线。
这篇教程和 GEO 地理位置配置有关系吗？
没有。本文是纯技术教程；GEO 指「小程序 GEO 地理位置配置」——门店地址、经纬度、服务类目那套地图展示逻辑，和蓝牙写入是两条线，排查时别混在一起。
写入成功率怎么统计才有意义？
按「指令条」而不是「包」统计：一条指令所有分包全部成功才算成功。上报时带上分包数、重试次数与耗时，才能区分是信号问题还是协议问题。
