uni.openbluetoothadapter失败是蓝牙连接首要障碍，必须先解决：ios需manifest配置nsbluetoothalwaysusagedescription及后台模式，android 12+须分步授权bluetoothscan/connect权限，旧版还需定位权限；失败即终止后续操作，errcode:10001表明系统蓝牙未开启。
uni.openBluetoothAdapter 调用失败就别往下走了
自动配对不是“点一下就连上”，而是依赖一整套前置状态就绪：蓝牙已开、权限已授、适配器已启用。只要 uni.openBluetoothAdapter 返回 errCode: 10001，说明系统蓝牙根本没打开，此时任何后续操作（包括扫描、连接）都会静默失败或报 errCode: 10000。
实操建议：
- iOS 必须在
manifest.json的app-plus → permissions中勾选「蓝牙」，并填入NSBluetoothAlwaysUsageDescription；Xcode 打包后还需手动开启Background Modes → Bluetooth Central - Android 12+（API 31+）必须分开动态申请
scope.bluetoothScan和scope.bluetoothConnect，不能只调一次uni.authorize - Android API scope.location（系统把扫描归为定位行为），且华为/小米等厂商可能静默禁用扫描，得弹窗提醒用户手动开启
- 务必监听
uni.onBluetoothAdapterStateChange，确认available: true且discovering: false后再执行下一步
startBluetoothDevicesDiscovery 搜不到设备？大概率是 services 参数没传
很多 BLE 设备（尤其是打印机、扫码器、传感器）默认广播时不带 service UUID，uni.startBluetoothDevicesDiscovery 若不显式传 services: [] 或具体 UUID 数组，iOS 15+ 和部分 Android 厂商 ROM 会直接过滤掉这些设备——这不是 bug，是系统级过滤策略。
实操建议：
- 先查硬件文档，拿到目标设备的主 service UUID（如 ESC/POS 打印常用
'00001101-0000-1000-8000-00805f9b34fb'） - 搜索时强制传
{ services: ['xxx'] }，不要依赖空参数默认扫全量 -
allowDuplicatesKey设为false，自己按deviceId缓存去重，避免内存泄漏 - 扫描时长设为 10–15 秒，太短可能错过广播窗口（BLE 设备通常每 1–2 秒广播一次）
createBLEConnection 后立即通信？流程断在中间了
连接成功 ≠ 可读写。uni.createBLEConnection 只建立物理链路，后续必须严格走完“发现服务 → 获取特征值 → 启用 notify/write”三步，否则 uni.readBLECharacteristicValue 或 uni.writeBLECharacteristicValue 必报 errCode: 10006（未连接）、10008（未找到特征值）或 10009（不可写）。
实操建议：
- 必须监听
uni.onBLEConnectionStateChange，确认回调中connected: true再调下一步 - 用
uni.getBLEDeviceServices获取服务列表，注意筛选isPrimary: true的主服务 - 再用该服务
uuid调uni.getBLEDeviceCharacteristics，检查目标characteristic的properties.notify或properties.write是否为true（大小写敏感） - 启用通知必须调
uni.notifyBLECharacteristicValueChange({ state: true, serviceId, characteristicId })，漏掉任一参数都会失败
自动配对的核心其实是“缓存 deviceId + 重连逻辑”
uni-app 没有真正意义上的“自动配对”API（如系统级配对弹窗），所谓自动，是指跳过重复扫描，直接用已知 deviceId 尝试连接。这要求你持久化存储上次成功连接过的设备 ID，并在启动或页面显示时主动重连。
实操建议：
- 连接成功后，把
deviceId存到uni.setStorageSync；断开或失败时及时清理 - 进入页面时先调
uni.getConnectedBluetoothDevices，检查是否已连——有些设备配对后会自动维持连接 - 若未连，再用缓存的
deviceId直接调uni.createBLEConnection，无需重新扫描 - 必须监听
uni.onBLEConnectionStateChange，设备意外断开时可触发自动重连（但别无限重试，加 3 次上限+退避）
最易被忽略的一点：安卓多次调用 uni.createBLEConnection 可能导致同一设备持有多个连接句柄，uni.closeBLEConnection 无法彻底释放。每次连接前，建议先尝试用 uni.closeBLEConnection 清理旧连接（即使不确定是否连着，fail 也无害）。
