Android BLE权限：附近设备、定位与扫描失败排查
同一蓝牙外设在一台Android手机可见，在另一台手机消失，不能直接认定固件或射频有问题。先确认应用是否获准扫描、扫描是否真正启动、收到的广播是否满足过滤条件。这三个边界需要分别记录。本指南面向原生Android中心设备应用，帮助团队建立最小权限与扫描诊断流程。
适用范围：示例配置为minSdk 29、targetSdk 35，将Android 10至11与Android 12及以上的权限模型分开处理。重点是前台扫描和GATT连接，不涵盖旧目标版本兼容模式、伴生设备关联或完整后台执行方案。资料核查日期为2026年10月11日；下述步骤是建议验证方案，并非已经完成的手机实测。
先记录系统版本与目标版本
复现记录应包含应用版本、目标SDK、手机系统与API级别，以及打包后的合并清单。手机没有升级，不代表权限行为不会变：应用提高targetSdk后，同一段调用也可能走不同分支。不要只检查源码目录中的清单，还要确认依赖库和构建变体有没有改变最终声明。
- Android 10至11，即API 29至30：核查旧BLUETOOTH、BLUETOOTH_ADMIN声明，以及扫描需要的运行时ACCESS_FINE_LOCATION。
- Android 12及以上且采用现代目标版本：扫描核查BLUETOOTH_SCAN，连接接口核查BLUETOOTH_CONNECT；是否利用扫描推断位置会影响定位声明。
现代应用兼容旧设备时，可将旧蓝牙声明的maxSdkVersion设为30。若扫描不用于推断位置且没有其他定位用途，旧版精确定位声明也可截止到30。旧系统的后台发现另有定位要求，不能照搬前台方案。依据见Android蓝牙权限指南。
按真实操作选择权限
发现设备与连接设备是两个操作。BLUETOOTH_CONNECT也保护GATT连接接口，并非只有已绑定设备才需要；应核对实际使用的BluetoothDevice接口。获得权限不等于完成配对，也不等于已经验证设备身份。先扫描再连接的配网页面，现代分支通常需要SCAN与CONNECT。
手机仅扮演中心设备时，不应因为产品用了BLE就顺手加入ADVERTISE。只有手机自身广播或变为可发现设备等相应行为才涉及该权限。还要检查SDK在扫描回调中读取哪些设备属性，避免扫描本身获准，后续属性读取却越过另一个权限边界。
认真对待neverForLocation声明
neverForLocation表达的是应用不会利用蓝牙扫描推断物理位置，而不是减少弹窗的通用技巧。Android明确提示它会过滤部分BLE信标，扫描接口说明也提醒设备交互范围可能受限。即使没有读取GPS，房间识别、基于接近程度的位置推断和分析SDK仍应纳入用途审查。
对于确实不定位的产品，用最终广播格式验证所选声明。如果目标信标因此不可见，应同时复核产品用途与清单设计，不能为了恢复结果而悄悄作出不真实的声明。测试结论应写清具体手机、系统和广播内容，避免推广为所有信标的共同表现。
把拒绝设计成稳定状态
在受保护操作前检查当前授权，等待异步权限结果后再扫描。遵循运行时权限请求流程，不要从“附近设备”弹窗文字推断每项权限都已授予。拒绝后应停止相关动作，解释受影响功能，并让用户继续使用无关功能。
不要自动重复弹窗。shouldShowRequestPermissionRationale返回false也可能出现在首次申请之前，不能单独据此认定永久拒绝。可以保留申请历史辅助界面判断，但实际能力仍以当前检查为准。用户从设置返回后重新检查，不能沿用上次成功标志。
将扫描失败与空列表分开
每次扫描记录会话编号、开始时间、结束原因，并设置上限；找到目标后及时停止。官方扫描指南建议避免无限循环扫描。蓝牙关闭时扫描器可能不可用，界面应明确显示蓝牙状态，而不是写成权限不足。
保留onScanFailed错误码及系统版本。回调文档区分重复启动、注册失败、功能不支持和内部错误；扫描过频及硬件资源不足常量在API 33加入。快速重启扫描会覆盖线索，不能作为默认恢复办法。
扫描启动且没有失败回调，却没有目标结果时，再检查广播是否开启、过滤条件是否正确、扫描设置是否匹配。旧系统测试行应单独记录系统定位开关并做受控对比，不应推导成所有现代BLE功能都必须定位。扫描接口还规定未过滤扫描的熄屏行为，因此首次复现宜保持前台亮屏，之后再单独验证生命周期变化。
用受控矩阵验收
- 各手机使用相同外设固件和广播配置，记录服务UUID及脱敏载荷摘要。
- 干净安装目标发布变体，核对最终清单，分别走允许、拒绝、取消流程。
- 授权后仅启动一个有截止条件的扫描会话，确认错误回调被保存。
- 在获准测试的手机上比较生产过滤器与临时宽范围扫描。只有后者可见时，先检查实际广播字段。
- 发现目标后独立验证连接授权及连接回调，不能把广播可见当作GATT可用。
- 撤销权限并从设置返回，确认页面正确恢复，不依赖重启应用或连续催促授权。
验收标准是每种失败都能导向明确下一步：处理权限选择、开启蓝牙、修正扫描配置，或检查外设。日志保留时间线和状态转换即可，避免无必要保存完整设备地址及与用户关联的载荷。可复现的失败边界，才是跨手机排障的可靠交付。
