⚡ UniApp 小程序开发与避险实战手册
国内市场最大的物联网 C 端入口不是 Native Apps，而是即走即用的微信小程序！ 本项目在 apps/uniapp/ 目录下提供了基于 Vue 3 的极其完善的小程序 BLE 标杆实践。
一、 启动您的免安装基建
在您使用代码前，请确保您：
- 下载安装了 DCloud 官方的 HBuilderX 编辑器（这是 UniApp 的官方指定神兵）。
- 在微信官方注册了小程序 AppID（测试的话允许使用测试号，但无法真机预览全部能力）。
- 使用 HBuilderX 顶部菜单：
运行 (Run) -> 运行到小程序模拟器 (Run to MiniProgram) -> 微信开发者工具。
二、 微信小程序的顶级底层坑位
许多人拿到咱们的代码就盲干，结果在实际扫描和连接蓝牙的时候叫苦连天。为此，我们在 UniApp 版本里做了极其深刻的处理，您二开时必须了解：
【深渊暗坑 1】苹果手机的 “MAC 地址抹除术”
这是全网 UniApp 新手最容易摔死的坑！ 在 Android 端，微信 API uni.getBluetoothDevices 能完美拿到外围设备的物理真实 MAC 地址（例如 A1:B2:C3:D4:E5:F6）。可是，在 iOS 系统下，返回的 MAC 地址会被系统抹除变成一片空白！应对之策：由于我们的工具已经为您填好了这个坑（见源码的设备解析逻辑），iOS 会拿到一个被系统打乱的 UUID 作为连接句柄。所以请记住：绝对不要把业务强绑定在字符串形式的 "真实MAC地址"上，要采用我们封装的设备唯一防重令牌做业务判定。
【深渊暗坑 2】并发 MTU 的割裂
微信对蓝牙的底层封装存在发送长度瓶颈（很多机型被死死卡在仅能发 20 byte 的上古时代）。 我们的底层 JS 库专门针对 UniApp 分支保留了大块数据的智能切片机制(Chunking)。当您需要在小程序里向单片机推送体积庞大的 OTA 固件时，切勿通过纯手写循环疯狂发数据，请务必调用框架提供的带缓冲列队的发送 API，否则会导致您的微信直接内存溢出闪退！
三、 主题色自动换装
得益于我们的双向绑定架构，您不必到 Vue 项目繁杂的 .scss 文件中改色。 去修改根目录 core/assets-generator/meta/ 下的情报配置并运行脚本！ 脚本不仅会生成全套标准的 css 文件注入 UniApp，甚至连小程序的图标、占位缺省图 (SVG) 也会完成物理替换！