蓝牙权限适配概述
蓝牙权限适配是 Android 平台应用开发中最为复杂的权限治理场景之一。自 Android 6.0 引入运行时权限机制以来，蓝牙相关权限经历了多次拆分与重构；从 Android 10 开始强制执行位置权限关联，到 Android 12 引入细粒度蓝牙权限，再到 Android 13+ 对扫描、连接、广播权限的彻底解耦，开发者在不同系统版本上面临着差异极大的授权逻辑与适配要求。
权限分类
蓝牙权限按功能与系统版本可划分为以下几类：
| 分类 | 权限名称 | 引入版本 | 作用域 |
|---|---|---|---|
| 传统蓝牙 | BLUETOOTH | API 1 | 基础通信（连接、收发数据） |
| 管理权限 | BLUETOOTH_ADMIN | API 1 | 扫描设备、修改蓝牙设置 |
| 位置关联 | ACCESS_FINE_LOCATION | API 23 | Android 10–11 扫描 BLE 设备时必须持有 |
| 位置关联 | ACCESS_COARSE_LOCATION | API 23 | 可替代细粒度位置（作用域缩小） |
| 细粒度扫描 | BLUETOOTH_SCAN | API 31 | Android 12+ 专用扫描权限，不依赖位置 |
| 细粒度连接 | BLUETOOTH_CONNECT | API 31 | Android 12+ 建立/断开连接所需 |
| 细粒度广播 | BLUETOOTH_ADVERTISE | API 31 | Android 12+ 发起 BLE 广播必须 |
适配目标
- 功能完整：确保应用在不同 Android 版本上均能执行蓝牙扫描、连接、数据传输等核心操作。
- 最小敏感权限：优先使用细粒度蓝牙权限（如
BLUETOOTH_SCAN）替代位置权限，避免过度索取。 - 优雅降级：当用户拒绝某一权限时，应用能提供替代方案或清晰提示，而非崩溃。
- 合规审计：遵循 Google Play 政策要求，如 Android 12+ 不允许仅因蓝牙扫描而声明位置权限。
兼容性要点
以下是在不同 API 级别上配置和请求蓝牙权限的核心原则：
- Android 6.0 (API 23) – 11 (API 30)：必须同时声明
BLUETOOTH、BLUETOOTH_ADMIN和ACCESS_FINE_LOCATION（或ACCESS_COARSE_LOCATION），并在运行时请求位置权限。 - Android 12 (API 31) – 12L (API 32)：新增三个细粒度权限，无需位置权限即可完成 BLE 扫描；但若兼容旧版本，仍需要在
AndroidManifest.xml中声明位置权限并使用maxSdkVersion="30"限制。 - Android 13 (API 33)+：系统自动将旧蓝牙权限映射至新细粒度权限，但开发者应主动迁移至
BLUETOOTH_SCAN/BLUETOOTH_CONNECT/BLUETOOTH_ADVERTISE。 - 清单声明示例：
<!-- AndroidManifest.xml 兼容多版本声明 -->
<uses-permission android:name="android.permission.BLUETOOTH" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
<!-- 仅 Android 10–11 需要位置权限 -->
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"
android:maxSdkVersion="30" />
<!-- Android 12+ 细粒度权限 -->
<uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
<uses-permission android:name="android.permission.BLUETOOTH_ADVERTISE" />
常见错误： 在 Android 12+ 设备上仅声明
ACCESS_FINE_LOCATION 而未声明 BLUETOOTH_SCAN，会导致扫描回调无法触发；或错误地将 BLUETOOTH_CONNECT 放在运行时请求列表之外，造成连接时安全异常 SecurityException。
蓝牙权限适配全景图
下图展示了从 Android 6 到 Android 13+ 的权限演进路径、核心权限节点以及适配策略：
调试建议： 在
adb shell dumpsys package com.your.app 中检查已授予的权限列表，确认细粒度权限是否生效。对于 Android 12+ 设备，若扫描回调始终不返回结果，优先核查是否已请求 BLUETOOTH_SCAN 且用户未拒绝。