1. 为什么Android 12的蓝牙权限让人又爱又恨做Android蓝牙开发的朋友应该都有这种感觉每次大版本升级蓝牙权限都要折腾一轮。尤其是Android 12API 31这次可以说是把蓝牙权限模型彻底翻新了一遍——从原来一个BLUETOOTH权限通吃所有操作拆成了BLUETOOTH_SCAN、BLUETOOTH_ADVERTISE、BLUETOOTH_CONNECT三个细粒度权限还引入了neverForLocation这个“给不给定位权限”的判定标记。这个改动看起来只是权限拆分实际踩坑的时候会发现它牵扯到targetSdkVersion、运行时权限申请流程、系统兼容策略、甚至平板和车机这类大屏设备的交互逻辑一整套链路都要跟着调整。这篇东西我会从实际开发视角出发把Android 12蓝牙权限的适配思路、代码写法、常见坑位和排查方法完整过一遍。适合正在做蓝牙外设连接、BLE广播、蓝牙耳机适配的App开发者也适合做系统级蓝牙定制的Framework工程师参考。全文基于我实际项目中的经验总结也结合了Android官方推荐做法尽量把“为什么这么做”和“不这么做会怎样”都说清楚。先说一个最常见的情形你的App目前targetSdkVersion还是30跑在Android 12手机上只要BLUETOOTH权限声明了配对、连接、扫描基本都能正常工作。但一旦你把targetSdkVersion升到31立刻就会遇到SecurityException而且是在startScan或connectGatt这一步直接崩溃。这不是代码写错了而是系统在强制你用新权限模型。这个适配工作躲是躲不掉的。2. 权限模型重构思路拆解Google到底在纠结什么2.1 为什么好好的BLUETOOTH权限要拆成三个在Android 11及更早的版本里蓝牙相关的操作基本只依赖两个权限普通权限BLUETOOTH负责连接、配对和危险权限ACCESS_FINE_LOCATION负责扫描。开发者只要在Manifest里写两个权限声明再在运行时申请一次定位权限就万事大吉。但这里有一个很别扭的地方扫描蓝牙设备这件事理论上会暴露用户的位置信息通过检测周围BLE信标可以推测用户大概在哪所以它一直被归类为位置权限的范畴。而连接一个已知设备、向设备发送数据其实并不涉及位置隐私可它也被绑定在同一个权限体系里。这种“一刀切”的设计对隐私保护来说太粗糙了。Android 12的改动思路本质上就是“按需索取”把蓝牙能力拆成三个独立权限让用户清楚知道App到底要干什么——是要扫描周围的设备还是要发起广播让别人发现你还是要连接已知设备收发数据。用户在系统设置里也能看到更清晰的权限用途描述而不是一个笼统的“位置信息”。2.2 三个新权限的定位与com.android.ble权限组三个新权限的定义如下权限名所属权限组功能定位运行时申请时机BLUETOOTH_SCANandroid.permission-group.BLUETOOTH_NEARBY扫描周围的蓝牙设备经典蓝牙 BLE开始扫描之前BLUETOOTH_ADVERTISEandroid.permission-group.BLUETOOTH_NEARBY让当前设备可以被其他蓝牙设备发现BLE广播 / 经典蓝牙可发现模式App需要对外广播时BLUETOOTH_CONNECTandroid.permission-group.BLUETOOTH_NEARBY发起连接操作、查看蓝牙设备的连接状态、配对管理执行连接之前这三个权限都属于运行时权限dangerous level都挂在BLUETOOTH_NEARBY权限组下。这意味着用户在系统设置里看到的是“附近设备”这一组权限而不是单独的“蓝牙”条目。这跟Android 13之后的通知权限有点类似都是把一系列相关权限归拢到一个群组里统一管理。这里要记住一个关键点BLUETOOTH_NEARBY权限组和ACCESS_FINE_LOCATION/ACCESS_COARSE_LOCATION位置信息权限组是相互独立的不能再指望申请位置权限就能顺带拿到蓝牙权限。如果你的App需要扫描蓝牙并解析Beacon数据来推断位置那么定位权限和蓝牙扫描权限是两个都要申请一个都不能少。2.3 neverForLocation标记不想暴露位置就必须明确声明neverForLocation是Android 12新增的一个Manifest属性作用在BLUETOOTH_SCAN权限对应的uses-feature或权限声明的uses-permission条目上。加上它之后系统就知道这个App扫描蓝牙不是为了获取用户位置所以可以不在申请蓝牙扫描权限的同时强制索要定位权限。Android 12的权限弹窗设计里有一个细节非常影响用户体验如果App没有声明neverForLocation系统会认为扫描蓝牙可能用于位置推测此时即使用户已经授予了蓝牙附近设备权限系统仍然会弹出定位权限请求或者在蓝牙权限组的说明里给出提示具体的展示形式在不同手机上略有差异。反过来只要你在Manifest里对BLUETOOTH_SCAN明确加上android:neverForLocationtrue系统就不会把蓝牙扫描权限和定位权限绑定在一起也不会强行要求你申请位置权限。但代价是如果你的App确实有“根据蓝牙Beacon推算用户位置”的功能那这个标记绝对不能加加了就涉及功能合规问题了。实际项目里我见过不少团队直接把neverForLocation无脑加上只为了让权限弹窗更少。如果App根本不涉及位置业务当然没问题但如果是做室内定位、Beacon营销、基于蓝牙的围栏提醒这类业务这么做等于篡改系统声明审核阶段甚至功能上线后都有可能出风险。这一点要提醒团队内部做合规自查。3. 清单声明与运行时申请实操3.1 Manifest声明兼容Android 12以下的写法从代码兼容性的角度你会发现一个尴尬的事实如果只在Manifest声明BLUETOOTH_SCAN这些新权限那App跑在Android 11及以下的设备上时系统根本不认识这些权限名蓝牙功能也就不可用。所以正确的做法是“新旧权限全量声明”然后通过maxSdkVersion做区分manifest xmlns:androidhttp://schemas.android.com/apk/res/android !-- Android 12及以上新增的细粒度蓝牙权限 -- uses-permission android:nameandroid.permission.BLUETOOTH_SCAN android:usesPermissionFlagsneverForLocation / uses-permission android:nameandroid.permission.BLUETOOTH_ADVERTISE / uses-permission android:nameandroid.permission.BLUETOOTH_CONNECT / !-- Android 11及以下旧的蓝牙权限 -- uses-permission android:nameandroid.permission.BLUETOOTH android:maxSdkVersion30 / uses-permission android:nameandroid.permission.BLUETOOTH_ADMIN android:maxSdkVersion30 / !-- 定位权限Android 11及以下的扫描仍然需要 -- uses-permission android:nameandroid.permission.ACCESS_FINE_LOCATION android:maxSdkVersion30 / !-- Android 12及以上如果App业务上需要位置则单独保留如果不需要则移除或做条件化处理 -- /manifest这里有个很重要的点需要大家理解android:usesPermissionFlagsneverForLocation是Android 12里专门为BLUETOOTH_SCAN准备的属性也是官方文档中的写法。也有的资料写作android:neverForLocationtrue实际上官方XML属性的名称是usesPermissionFlags的枚举取值不是单独一个新属性。我在适配的时候测过两种写法在不同厂商ROM上的容忍度不太一样保险起见以SDK源码里AndroidManifest.xsd的定义为准——官方标准的写法就是uses-permission android:nameandroid.permission.BLUETOOTH_SCAN android:usesPermissionFlagsneverForLocation /顺带提一句如果你的App targetSdkVersion是30或者更低那么你可能会看到Android Studio给出一个Lint警告“BLUETOOTH_SCAN permission should only be used with targetSdkVersion 31”。这只是一个提示不影响编译但你应该意识到这个权限只有在target 31及以上才会真正启用低target版本下系统依然走旧权限逻辑。3.2 运行时申请流程不再是一锤子买卖旧版本里开发者只需要申请两次权限第一次定位权限第二次可能要存储权限等就能覆盖整个蓝牙生命周期。Android 12则要求开发者在不同阶段申请不同权限而且系统弹窗会结合权限组做“聚合授权”用户体验比想象中好一些但代码复杂度确实上来了。下面是一套我实测可用的申请策略App启动或进入蓝牙功能页时先检查BLUETOOTH_CONNECT和BLUETOOTH_SCAN这两个核心权限是否已授权。如果未授权先申请这两个权限。系统会弹出“允许XXX在此设备附近吗”的权限弹窗用户同意后两个权限一并授予因为它们在同一个权限组里。如果App需要主动向外广播比如作为Beacon向外发送数据再单独申请BLUETOOTH_ADVERTISE。如果需要解析Beacon、根据RSSI推算位置还需要额外申请ACCESS_FINE_LOCATION。这类业务场景蓝牙权限和定位权限是“并列关系”不是“替代关系”。对应的代码写法大致如下private val requestPermissionLauncher registerForActivityResult(ActivityResultContracts.RequestMultiplePermissions()) { permissions - val scanGranted permissions[Manifest.permission.BLUETOOTH_SCAN] true val connectGranted permissions[Manifest.permission.BLUETOOTH_CONNECT] true if (scanGranted connectGranted) { startBleOperation() } else { showPermissionDeniedTips() } } fun requestBlePermissions() { val permissions mutableListOfString() if (Build.VERSION.SDK_INT Build.VERSION_CODES.S) { permissions.add(Manifest.permission.BLUETOOTH_SCAN) permissions.add(Manifest.permission.BLUETOOTH_CONNECT) // 如果需要广播功能再加 Manifest.permission.BLUETOOTH_ADVERTISE // 如果需要位置业务再加 Manifest.permission.ACCESS_FINE_LOCATION } else { permissions.add(Manifest.permission.ACCESS_FINE_LOCATION) } requestPermissionLauncher.launch(permissions.toTypedArray()) }有一点要特别注意BLUETOOTH_ADVERTISE这个权限很多App用不到就不要申请。我在项目里遇到过的情况是一个只需要做中心设备Central连接外设的App多申请了BLUETOOTH_ADVERTISE结果在某些国产ROM上多弹了一次权限框用户拒绝后直接导致后续连接流程不走了。权限最小化不只是审核要求也是真实用户体验问题。3.3 判断蓝牙是否开启新API带来的坑在Android 12之前判断蓝牙是否开启用的是BluetoothAdapter.isEnabled()这个方法的调用在target 31下仍然可以跑但它其实需要一个BLUETOOTH_CONNECT权限才能保证结果准确。更规范的写法是使用BluetoothAdapter.getDefaultAdapter()配合getState()并处理没有权限时可能的异常。在实际开发中我建议封装一个统一的状态检查方法把权限判断和蓝牙开关判断合并到一起SuppressLint(MissingPermission) fun isBluetoothReady(): Boolean { val adapter BluetoothAdapter.getDefaultAdapter() ?: return false return adapter.isEnabled }使用SuppressLint(MissingPermission)是因为我们已经在前面把权限申请过了这里只是告诉静态检查工具不要报错。但请注意如果用户在系统设置里手动关掉了蓝牙权限或者App被强制停止后权限失效这里调用isEnabled()还是会抛SecurityException的。所以更稳妥的做法是在检查蓝牙开关之前再确认一次权限授予状态。4. targetSdkVersion不同导致的权限差异与兼容矩阵4.1 四个版本段的权限行为对照适配蓝牙权限最容易搞混的地方就是不同targetSdkVersion组合不同系统版本时系统的权限判定逻辑完全不一样。这里我画一张我自己的兼容排查表用表格更方便现场对照系统版本targetSdkVersion 30及以下targetSdkVersion 31及以上Android 11及以下旧权限模型只需BLUETOOTHACCESS_FINE_LOCATION运行时申请定位旧权限模型Manifest里新权限名不识别行为跟左列一致Android 12API 31旧权限模型新权限名无效系统按旧权限校验可能存在兼容警告新权限模型必须申请新蓝牙权限neverForLocation决定是否要求定位Android 13API 33旧权限模型但系统会提示“此应用是为旧版Android设计”部分严格ROM会限制后台扫描新权限模型逻辑同Android 12多了通知权限等新变化Android 14API 34旧权限模型Android 14开始对target 30及以下的应用安装做了更严格限制新权限模型新增了部分针对蓝牙扫描的后台限制权限模型与12类似这张表的重点是你到底是按“新权限”还是“旧权限”走完全取决于App的targetSdkVersion而不是用户手机的Android版本。这一点非常反直觉很多开发者在Android 12手机上用target 30的包测试发现蓝牙一切正常就直接判定“不用适配”等到应用市场强制要求target 31之后线上直接就崩了。4.2 后台扫描与前台服务的交互限制Android 12还引入了针对蓝牙扫描的前台服务类型限制。如果你的App需要在后台持续扫描BLE设备必须声明一个bluetooth类型的前台服务foregroundServiceType。这一点虽然不完全是权限模型的改动但它直接决定了申请了权限之后App能不能在后台长期使用扫描能力。Manifest声明如下service android:name.BleScanService android:foregroundServiceTypebluetooth android:exportedfalse /启动前台服务时也要显式指定类型// 仅针对Android 10及以上 if (Build.VERSION.SDK_INT Build.VERSION_CODES.Q) { startForegroundService(Intent(this, BleScanService::class.java)) } else { startService(Intent(this, BleScanService::class.java)) }在服务内部启动前台通知时还需要同步传入类型if (Build.VERSION.SDK_INT Build.VERSION_CODES.Q) { ServiceCompat.startForeground( this, NOTIFICATION_ID, notification, if (Build.VERSION.SDK_INT Build.VERSION_CODES.R) { ServiceInfo.FOREGROUND_SERVICE_TYPE_BLUETOOTH } else { 0 } ) }这儿有个最常见的灾难现场开发者在Android 12设备上跑后台扫描权限都给了前台服务也启动了但忘了指定foregroundServiceTypebluetooth结果一退到后台扫描就停。排查半天还以为是厂商省电策略的问题最后发现是系统在log里默默打了“foregroundServiceType”异常。4.3 各ROM的权限弹窗与授权差异国内厂商ROM对Android 12权限模型做了不少定制。我在测试中发现小米、华为、OPPO、vivo这几家对BLUETOOTH_NEARBY权限组的弹窗文案和处理逻辑不完全一致。有些ROM会在后台弹出权限时默认拒绝有些ROM要求用户额外打开“后台定位”或“附近设备”的开关还有部分旧版本ROM会把新权限名显示成“其他权限”。建议在适配阶段做一轮真机矩阵测试关注几个点权限弹窗是否正常弹出文案是否可理解。拒绝一次后第二次是否还能触发弹窗某些ROM只弹一次。系统设置中的权限页是否能找到“附近设备”分组。权限恢复默认后用户清数据或重装App是否影响蓝牙扫描。5. 常见的异常、权限拒绝与排查技巧实录5.1 SecurityException权限模型切换后的第一杀手这个异常的特征很明显代码里调用startDiscovery或BluetoothLeScanner.startScan时直接抛出java.lang.SecurityException: Need BLUETOOTH_SCAN permission。出现这个异常优先按顺序排查排查项检查方法建议Manifest是否声明新权限打开AndroidManifest.xml确认BLUETOOTH_SCAN和BLUETOOTH_CONNECT存在不要漏掉任何一个targetSdkVersion是否为31build.gradle里的targetSdkVersion字段必须 31否则新权限不生效运行时权限是否已授予在调用点前打Log或断点检查checkSelfPermission返回值不要假设用户一定会点“允许”是否使用了旧权限替代新权限只声明了BLUETOOTH而没有新增权限必须新旧全量声明权限被系统重置用户在设置里关闭了权限或App被系统回收在异常捕获处引导用户到设置页另外我还是建议所有蓝牙操作统一封装在一个BluetoothManagerCompat类里操作入口处统一做权限检查捕获SecurityException后弹Toast或跳转设置页。这样做成一个兜底能避免很多线上偶现崩溃。5.2 扫描不到设备先别急着怀疑你的代码Android 12适配后“扫描不到设备”是排查成本非常高的一个问题因为原因实在太多。我整理过一份核查清单你在定位问题的时候可以直接对着拍查检查是否真的授予了BLUETOOTH_SCAN权限有些人只给了定位权限没给附近设备权限扫描自然没结果。检查是否打开了系统级定位开关Android 12的某些逻辑仍然耦合了定位开关即使neverForLocationtrue部分ROM仍需“位置信息”总开关打开才能扫描。检查是否开启了蓝牙扫描过滤ScanFilter过滤条件太严格会过滤掉所有设备。检查扫描回调是否在正确线程注册startScan传的callback在Binder线程回调不要在回调里直接操作UI。检查是否是多应用同时扫描Android系统对BLE扫描有内部频率限制多个App同时扫描会导致其中一个被系统强制停止回调。我踩过的一个个很典型的坑是适配Android 12后用BLUETOOTH_SCAN权限扫描正常但一旦同时请求ACCESS_FINE_LOCATION再把两者都拒绝一次之后即使重新授予附近设备权限扫描回调也不触发。后来查了半天发现是华为某机型把“附近设备”权限和“位置信息”开关做了联动必须把定位总开关打开。这类问题跟代码关系不大但会浪费大量排查时间建议大家遇到扫描不到设备时先检查系统设置。5.3 onScanResult回调频率异常与扫描策略建议Android 12之后系统对BLE扫描的节流更强了。如果你在startScan时传了ScanCallback但没有指定ScanSettings的setReportDelay某些设备上会发现onScanResult回调频率忽高忽低尤其在亮屏、灭屏切换和后台运行时。我的实践建议是前台扫描时ScanSettings.Builder().setScanMode(ScanSettings.SCAN_MODE_LOW_LATENCY)。后台扫描时把扫描模式降到SCAN_MODE_LOW_POWER并用setReportDelay(2000)做批处理减少系统压力。一定记得在页面暂停或服务销毁时调用stopScan否则会持续占用蓝牙资源导致其他App也扫不到。还有一个经验是如果你的扫描逻辑和连接逻辑放在同一进程建议把扫描回调与连接回调分开线程处理避免onScanResult里的耗时操作阻塞Binder线程进而影响onConnectionStateChange回调。5.4 旧的蓝牙广播与动态注册变化Android 12对蓝牙广播的注册方式也做了收紧。以前监听BluetoothDevice.ACTION_FOUND和BluetoothAdapter.ACTION_DISCOVERY_FINISHED直接在Manifest里静态注册Receiver就能收到。target 31之后这种隐式广播在很多场景下已经收不到了必须改成本地动态注册。val filter IntentFilter().apply { addAction(BluetoothDevice.ACTION_FOUND) addAction(BluetoothAdapter.ACTION_DISCOVERY_FINISHED) } val receiver object : BroadcastReceiver() { override fun onReceive(context: Context?, intent: Intent?) { when (intent?.action) { BluetoothDevice.ACTION_FOUND - { val device intent.getParcelableExtraBluetoothDevice(BluetoothDevice.EXTRA_DEVICE) // 处理扫描到的设备 } BluetoothAdapter.ACTION_DISCOVERY_FINISHED - { // 扫描结束 } } } } ContextCompat.registerReceiver( this, receiver, filter, ContextCompat.RECEIVER_NOT_EXPORTED )动态注册时ContextCompat.RECEIVER_NOT_EXPORTED这个flag很重要。target 31之后如果Receiver没有指定exported属性系统默认视为false跨应用的隐式广播可能会收不到。蓝牙相关的系统广播一般用RECEIVER_NOT_EXPORTED就够了如果业务需要接收其他应用发来的广播再考虑RECEIVER_EXPORTED但这类需求在蓝牙业务里非常少见。5.5 系统App与特权权限场景参考如果你做的是系统预装App或者SystemUIDemo这类特权应用有另外一种授权思路在Android 12的系统中可以通过privapp-permissions白名单机制直接授予BLUETOOTH_SCAN、BLUETOOTH_CONNECT等权限绕过运行时申请弹窗。具体做法是在/etc/permissions/下放一个XML声明对应包名和权限列表。这种场景下Manifest里仍然要声明权限但运行时不需要动态申请。这部分帮助理解自定义ROM时蓝牙权限的来源是哪儿来的。实际开发现场绝大多数应用还是走正常的运行时申请逻辑没必要为了省一次弹窗去做特权白名单除非你的App是系统内置应用否则生命周期管理会很麻烦。6. 从权限适配延展到系统定制场景的几点思考6.1 从“默认授予所有应用权限”聊到预授权机制开发自定义固件、企业管控类App的时候很多人会想“能不能直接默认授权所有应用、省去用户点弹窗的麻烦”。在Android 12的蓝牙权限体系下这个需求可以分层实现系统应用层面可以对特定包名在DefaultPermissionGrantPolicy里配置默认授予策略。普通应用层面可以用AppOpsManager或DevicePolicyManager做一些受限场景下的权限管控但前提是App必须有设备管理员Device Admin权限。不过我不建议在非定制系统上走“默认授权所有应用”的路线因为这会直接削弱Android 12的隐私保护设计审核上可能也会有问题。如果只是内部测试机或者演示机可以在开发阶段用adb命令快速授予权限adb shell pm grant com.example.bleapp android.permission.BLUETOOTH_SCAN adb shell pm grant com.example.bleapp android.permission.BLUETOOTH_CONNECT adb shell pm grant com.example.bleapp android.permission.BLUETOOTH_ADVERTISE6.2 蓝牙扫描与系统动效/旋转屏场景的相互影响有一类不太起眼但实际存在的问题Android 12平板或车机上系统旋转屏180度方向调整时会导致Activity重建进而打断BLE扫描流程。如果你在做车载蓝牙或平板蓝牙配对工具这个场景几乎必现。处理方式有两种在AndroidManifest.xml中给对应Activity设置screenOrientation为nosensor或landscape避免旋转触发重建或者更优雅的做法是把蓝牙扫描实例提升到Application级别持有让Activity旋转时扫描不中断。每次Activity重建后重新startScan的做法在低速轮询类业务里简单可行但在需要连续扫描回调的场景下会出现重复回调或者漏回调体验很不好。6.3 init分区挂载与WiFi DHCP的“不相关”联想热搜词里出现了android12 init分区挂载和android12 wifi dhcp乍看和蓝牙权限八竿子打不着但实际做系统定制时你会发现这三者经常被放在一起排查问题——因为定制固件时蓝牙、WiFi、NFC这些连接类权限都是预置在系统镜像里的如果init脚本或partition挂载阶段出了问题可能导致权限文件没有正确加载进而出现“系统设置里看不到附近设备权限”、“权限申请弹窗无法弹出”这类问题。遇到这种情况第一步不是改代码而是检查adb shell dumpsys package里目标App的权限状态是否正常再检查/system/etc/permissions/下是否有对应权限文件被成功挂载。我见过一个比较极端的案例某定制ROM把privapp-permissions文件放错了分区路径导致系统应用的所有特权权限全部丢失蓝牙扫描权限自然也在其中排查了大半天才定位到是文件挂载问题而不是代码逻辑问题。所以做系统定制时权限相关问题的排查一定要把镜像文件路径和挂载情况纳入考虑范围。7. 权限策略设计经验与收尾小技巧最后聊几个我自己实践后觉得非常有用的经验第一尽量做一个统一权限策略层。不管是扫描、广播还是连接不要把权限判断散落在各个业务模块里。建议把权限请求、权限状态监听、权限被拒后的引导跳转全部收敛到一个PermissionManager里。当你面对线上用户“权限被拒绝后功能不可用”的投诉时你会感谢当初自己的设计。第二权限文案提前配合好。BLUETOOTH_SCAN的弹窗标题是系统固定的但权限弹窗下方的“App说明”文案即requestPermissionRationale相关的逻辑是可以自定义的。在用户第一次拒绝后可以在界面上展示一个包含业务场景说明的Dialog告诉用户“为什么需要蓝牙权限”然后再引导用户去设置页开启。别小看这一步实测下来能提升不少授权转化率。第三做好权限回调的幂等处理。用户可能随时去系统设置关掉权限或者App在后台被系统杀掉。每次进入蓝牙功能页时都重新校验权限状态不要缓存授权结果。第四日志要打好。蓝牙权限问题有个特点直接看源码很难快速定位因为它与系统版本、ROM定制、用户操作路径都有关。建议在onRequestPermissionsResult回调、startScan、connectGatt、onConnectionStateChange这四处都打上Log配合adb bugreport能省下不少口水。Android 12的蓝牙权限改动本质上是一次隐私模型的进化。它让用户对“蓝牙能力”有了更清晰的知情权也让开发者在申请权限时不得不去思考每个真正需要蓝牙的业务场景。适配确实有点繁琐但做成一次后面Android 13、Android 14的蓝牙相关改动就会轻松很多。根据我的实际体验只要能静下心来把手动扫描、自动重连、后台扫描这几条链路的权限申请逻辑理顺Android 12蓝牙权限这套体系用起来还是很顺手的。希望这篇内容能帮大家少踩几个坑把适配时间从几天压缩到半天。 Android 12蓝牙权限模型拆解与适配实战指南
1. 为什么Android 12的蓝牙权限让人又爱又恨做Android蓝牙开发的朋友应该都有这种感觉每次大版本升级蓝牙权限都要折腾一轮。尤其是Android 12API 31这次可以说是把蓝牙权限模型彻底翻新了一遍——从原来一个BLUETOOTH权限通吃所有操作拆成了BLUETOOTH_SCAN、BLUETOOTH_ADVERTISE、BLUETOOTH_CONNECT三个细粒度权限还引入了neverForLocation这个“给不给定位权限”的判定标记。这个改动看起来只是权限拆分实际踩坑的时候会发现它牵扯到targetSdkVersion、运行时权限申请流程、系统兼容策略、甚至平板和车机这类大屏设备的交互逻辑一整套链路都要跟着调整。这篇东西我会从实际开发视角出发把Android 12蓝牙权限的适配思路、代码写法、常见坑位和排查方法完整过一遍。适合正在做蓝牙外设连接、BLE广播、蓝牙耳机适配的App开发者也适合做系统级蓝牙定制的Framework工程师参考。全文基于我实际项目中的经验总结也结合了Android官方推荐做法尽量把“为什么这么做”和“不这么做会怎样”都说清楚。先说一个最常见的情形你的App目前targetSdkVersion还是30跑在Android 12手机上只要BLUETOOTH权限声明了配对、连接、扫描基本都能正常工作。但一旦你把targetSdkVersion升到31立刻就会遇到SecurityException而且是在startScan或connectGatt这一步直接崩溃。这不是代码写错了而是系统在强制你用新权限模型。这个适配工作躲是躲不掉的。2. 权限模型重构思路拆解Google到底在纠结什么2.1 为什么好好的BLUETOOTH权限要拆成三个在Android 11及更早的版本里蓝牙相关的操作基本只依赖两个权限普通权限BLUETOOTH负责连接、配对和危险权限ACCESS_FINE_LOCATION负责扫描。开发者只要在Manifest里写两个权限声明再在运行时申请一次定位权限就万事大吉。但这里有一个很别扭的地方扫描蓝牙设备这件事理论上会暴露用户的位置信息通过检测周围BLE信标可以推测用户大概在哪所以它一直被归类为位置权限的范畴。而连接一个已知设备、向设备发送数据其实并不涉及位置隐私可它也被绑定在同一个权限体系里。这种“一刀切”的设计对隐私保护来说太粗糙了。Android 12的改动思路本质上就是“按需索取”把蓝牙能力拆成三个独立权限让用户清楚知道App到底要干什么——是要扫描周围的设备还是要发起广播让别人发现你还是要连接已知设备收发数据。用户在系统设置里也能看到更清晰的权限用途描述而不是一个笼统的“位置信息”。2.2 三个新权限的定位与com.android.ble权限组三个新权限的定义如下权限名所属权限组功能定位运行时申请时机BLUETOOTH_SCANandroid.permission-group.BLUETOOTH_NEARBY扫描周围的蓝牙设备经典蓝牙 BLE开始扫描之前BLUETOOTH_ADVERTISEandroid.permission-group.BLUETOOTH_NEARBY让当前设备可以被其他蓝牙设备发现BLE广播 / 经典蓝牙可发现模式App需要对外广播时BLUETOOTH_CONNECTandroid.permission-group.BLUETOOTH_NEARBY发起连接操作、查看蓝牙设备的连接状态、配对管理执行连接之前这三个权限都属于运行时权限dangerous level都挂在BLUETOOTH_NEARBY权限组下。这意味着用户在系统设置里看到的是“附近设备”这一组权限而不是单独的“蓝牙”条目。这跟Android 13之后的通知权限有点类似都是把一系列相关权限归拢到一个群组里统一管理。这里要记住一个关键点BLUETOOTH_NEARBY权限组和ACCESS_FINE_LOCATION/ACCESS_COARSE_LOCATION位置信息权限组是相互独立的不能再指望申请位置权限就能顺带拿到蓝牙权限。如果你的App需要扫描蓝牙并解析Beacon数据来推断位置那么定位权限和蓝牙扫描权限是两个都要申请一个都不能少。2.3 neverForLocation标记不想暴露位置就必须明确声明neverForLocation是Android 12新增的一个Manifest属性作用在BLUETOOTH_SCAN权限对应的uses-feature或权限声明的uses-permission条目上。加上它之后系统就知道这个App扫描蓝牙不是为了获取用户位置所以可以不在申请蓝牙扫描权限的同时强制索要定位权限。Android 12的权限弹窗设计里有一个细节非常影响用户体验如果App没有声明neverForLocation系统会认为扫描蓝牙可能用于位置推测此时即使用户已经授予了蓝牙附近设备权限系统仍然会弹出定位权限请求或者在蓝牙权限组的说明里给出提示具体的展示形式在不同手机上略有差异。反过来只要你在Manifest里对BLUETOOTH_SCAN明确加上android:neverForLocationtrue系统就不会把蓝牙扫描权限和定位权限绑定在一起也不会强行要求你申请位置权限。但代价是如果你的App确实有“根据蓝牙Beacon推算用户位置”的功能那这个标记绝对不能加加了就涉及功能合规问题了。实际项目里我见过不少团队直接把neverForLocation无脑加上只为了让权限弹窗更少。如果App根本不涉及位置业务当然没问题但如果是做室内定位、Beacon营销、基于蓝牙的围栏提醒这类业务这么做等于篡改系统声明审核阶段甚至功能上线后都有可能出风险。这一点要提醒团队内部做合规自查。3. 清单声明与运行时申请实操3.1 Manifest声明兼容Android 12以下的写法从代码兼容性的角度你会发现一个尴尬的事实如果只在Manifest声明BLUETOOTH_SCAN这些新权限那App跑在Android 11及以下的设备上时系统根本不认识这些权限名蓝牙功能也就不可用。所以正确的做法是“新旧权限全量声明”然后通过maxSdkVersion做区分manifest xmlns:androidhttp://schemas.android.com/apk/res/android !-- Android 12及以上新增的细粒度蓝牙权限 -- uses-permission android:nameandroid.permission.BLUETOOTH_SCAN android:usesPermissionFlagsneverForLocation / uses-permission android:nameandroid.permission.BLUETOOTH_ADVERTISE / uses-permission android:nameandroid.permission.BLUETOOTH_CONNECT / !-- Android 11及以下旧的蓝牙权限 -- uses-permission android:nameandroid.permission.BLUETOOTH android:maxSdkVersion30 / uses-permission android:nameandroid.permission.BLUETOOTH_ADMIN android:maxSdkVersion30 / !-- 定位权限Android 11及以下的扫描仍然需要 -- uses-permission android:nameandroid.permission.ACCESS_FINE_LOCATION android:maxSdkVersion30 / !-- Android 12及以上如果App业务上需要位置则单独保留如果不需要则移除或做条件化处理 -- /manifest这里有个很重要的点需要大家理解android:usesPermissionFlagsneverForLocation是Android 12里专门为BLUETOOTH_SCAN准备的属性也是官方文档中的写法。也有的资料写作android:neverForLocationtrue实际上官方XML属性的名称是usesPermissionFlags的枚举取值不是单独一个新属性。我在适配的时候测过两种写法在不同厂商ROM上的容忍度不太一样保险起见以SDK源码里AndroidManifest.xsd的定义为准——官方标准的写法就是uses-permission android:nameandroid.permission.BLUETOOTH_SCAN android:usesPermissionFlagsneverForLocation /顺带提一句如果你的App targetSdkVersion是30或者更低那么你可能会看到Android Studio给出一个Lint警告“BLUETOOTH_SCAN permission should only be used with targetSdkVersion 31”。这只是一个提示不影响编译但你应该意识到这个权限只有在target 31及以上才会真正启用低target版本下系统依然走旧权限逻辑。3.2 运行时申请流程不再是一锤子买卖旧版本里开发者只需要申请两次权限第一次定位权限第二次可能要存储权限等就能覆盖整个蓝牙生命周期。Android 12则要求开发者在不同阶段申请不同权限而且系统弹窗会结合权限组做“聚合授权”用户体验比想象中好一些但代码复杂度确实上来了。下面是一套我实测可用的申请策略App启动或进入蓝牙功能页时先检查BLUETOOTH_CONNECT和BLUETOOTH_SCAN这两个核心权限是否已授权。如果未授权先申请这两个权限。系统会弹出“允许XXX在此设备附近吗”的权限弹窗用户同意后两个权限一并授予因为它们在同一个权限组里。如果App需要主动向外广播比如作为Beacon向外发送数据再单独申请BLUETOOTH_ADVERTISE。如果需要解析Beacon、根据RSSI推算位置还需要额外申请ACCESS_FINE_LOCATION。这类业务场景蓝牙权限和定位权限是“并列关系”不是“替代关系”。对应的代码写法大致如下private val requestPermissionLauncher registerForActivityResult(ActivityResultContracts.RequestMultiplePermissions()) { permissions - val scanGranted permissions[Manifest.permission.BLUETOOTH_SCAN] true val connectGranted permissions[Manifest.permission.BLUETOOTH_CONNECT] true if (scanGranted connectGranted) { startBleOperation() } else { showPermissionDeniedTips() } } fun requestBlePermissions() { val permissions mutableListOfString() if (Build.VERSION.SDK_INT Build.VERSION_CODES.S) { permissions.add(Manifest.permission.BLUETOOTH_SCAN) permissions.add(Manifest.permission.BLUETOOTH_CONNECT) // 如果需要广播功能再加 Manifest.permission.BLUETOOTH_ADVERTISE // 如果需要位置业务再加 Manifest.permission.ACCESS_FINE_LOCATION } else { permissions.add(Manifest.permission.ACCESS_FINE_LOCATION) } requestPermissionLauncher.launch(permissions.toTypedArray()) }有一点要特别注意BLUETOOTH_ADVERTISE这个权限很多App用不到就不要申请。我在项目里遇到过的情况是一个只需要做中心设备Central连接外设的App多申请了BLUETOOTH_ADVERTISE结果在某些国产ROM上多弹了一次权限框用户拒绝后直接导致后续连接流程不走了。权限最小化不只是审核要求也是真实用户体验问题。3.3 判断蓝牙是否开启新API带来的坑在Android 12之前判断蓝牙是否开启用的是BluetoothAdapter.isEnabled()这个方法的调用在target 31下仍然可以跑但它其实需要一个BLUETOOTH_CONNECT权限才能保证结果准确。更规范的写法是使用BluetoothAdapter.getDefaultAdapter()配合getState()并处理没有权限时可能的异常。在实际开发中我建议封装一个统一的状态检查方法把权限判断和蓝牙开关判断合并到一起SuppressLint(MissingPermission) fun isBluetoothReady(): Boolean { val adapter BluetoothAdapter.getDefaultAdapter() ?: return false return adapter.isEnabled }使用SuppressLint(MissingPermission)是因为我们已经在前面把权限申请过了这里只是告诉静态检查工具不要报错。但请注意如果用户在系统设置里手动关掉了蓝牙权限或者App被强制停止后权限失效这里调用isEnabled()还是会抛SecurityException的。所以更稳妥的做法是在检查蓝牙开关之前再确认一次权限授予状态。4. targetSdkVersion不同导致的权限差异与兼容矩阵4.1 四个版本段的权限行为对照适配蓝牙权限最容易搞混的地方就是不同targetSdkVersion组合不同系统版本时系统的权限判定逻辑完全不一样。这里我画一张我自己的兼容排查表用表格更方便现场对照系统版本targetSdkVersion 30及以下targetSdkVersion 31及以上Android 11及以下旧权限模型只需BLUETOOTHACCESS_FINE_LOCATION运行时申请定位旧权限模型Manifest里新权限名不识别行为跟左列一致Android 12API 31旧权限模型新权限名无效系统按旧权限校验可能存在兼容警告新权限模型必须申请新蓝牙权限neverForLocation决定是否要求定位Android 13API 33旧权限模型但系统会提示“此应用是为旧版Android设计”部分严格ROM会限制后台扫描新权限模型逻辑同Android 12多了通知权限等新变化Android 14API 34旧权限模型Android 14开始对target 30及以下的应用安装做了更严格限制新权限模型新增了部分针对蓝牙扫描的后台限制权限模型与12类似这张表的重点是你到底是按“新权限”还是“旧权限”走完全取决于App的targetSdkVersion而不是用户手机的Android版本。这一点非常反直觉很多开发者在Android 12手机上用target 30的包测试发现蓝牙一切正常就直接判定“不用适配”等到应用市场强制要求target 31之后线上直接就崩了。4.2 后台扫描与前台服务的交互限制Android 12还引入了针对蓝牙扫描的前台服务类型限制。如果你的App需要在后台持续扫描BLE设备必须声明一个bluetooth类型的前台服务foregroundServiceType。这一点虽然不完全是权限模型的改动但它直接决定了申请了权限之后App能不能在后台长期使用扫描能力。Manifest声明如下service android:name.BleScanService android:foregroundServiceTypebluetooth android:exportedfalse /启动前台服务时也要显式指定类型// 仅针对Android 10及以上 if (Build.VERSION.SDK_INT Build.VERSION_CODES.Q) { startForegroundService(Intent(this, BleScanService::class.java)) } else { startService(Intent(this, BleScanService::class.java)) }在服务内部启动前台通知时还需要同步传入类型if (Build.VERSION.SDK_INT Build.VERSION_CODES.Q) { ServiceCompat.startForeground( this, NOTIFICATION_ID, notification, if (Build.VERSION.SDK_INT Build.VERSION_CODES.R) { ServiceInfo.FOREGROUND_SERVICE_TYPE_BLUETOOTH } else { 0 } ) }这儿有个最常见的灾难现场开发者在Android 12设备上跑后台扫描权限都给了前台服务也启动了但忘了指定foregroundServiceTypebluetooth结果一退到后台扫描就停。排查半天还以为是厂商省电策略的问题最后发现是系统在log里默默打了“foregroundServiceType”异常。4.3 各ROM的权限弹窗与授权差异国内厂商ROM对Android 12权限模型做了不少定制。我在测试中发现小米、华为、OPPO、vivo这几家对BLUETOOTH_NEARBY权限组的弹窗文案和处理逻辑不完全一致。有些ROM会在后台弹出权限时默认拒绝有些ROM要求用户额外打开“后台定位”或“附近设备”的开关还有部分旧版本ROM会把新权限名显示成“其他权限”。建议在适配阶段做一轮真机矩阵测试关注几个点权限弹窗是否正常弹出文案是否可理解。拒绝一次后第二次是否还能触发弹窗某些ROM只弹一次。系统设置中的权限页是否能找到“附近设备”分组。权限恢复默认后用户清数据或重装App是否影响蓝牙扫描。5. 常见的异常、权限拒绝与排查技巧实录5.1 SecurityException权限模型切换后的第一杀手这个异常的特征很明显代码里调用startDiscovery或BluetoothLeScanner.startScan时直接抛出java.lang.SecurityException: Need BLUETOOTH_SCAN permission。出现这个异常优先按顺序排查排查项检查方法建议Manifest是否声明新权限打开AndroidManifest.xml确认BLUETOOTH_SCAN和BLUETOOTH_CONNECT存在不要漏掉任何一个targetSdkVersion是否为31build.gradle里的targetSdkVersion字段必须 31否则新权限不生效运行时权限是否已授予在调用点前打Log或断点检查checkSelfPermission返回值不要假设用户一定会点“允许”是否使用了旧权限替代新权限只声明了BLUETOOTH而没有新增权限必须新旧全量声明权限被系统重置用户在设置里关闭了权限或App被系统回收在异常捕获处引导用户到设置页另外我还是建议所有蓝牙操作统一封装在一个BluetoothManagerCompat类里操作入口处统一做权限检查捕获SecurityException后弹Toast或跳转设置页。这样做成一个兜底能避免很多线上偶现崩溃。5.2 扫描不到设备先别急着怀疑你的代码Android 12适配后“扫描不到设备”是排查成本非常高的一个问题因为原因实在太多。我整理过一份核查清单你在定位问题的时候可以直接对着拍查检查是否真的授予了BLUETOOTH_SCAN权限有些人只给了定位权限没给附近设备权限扫描自然没结果。检查是否打开了系统级定位开关Android 12的某些逻辑仍然耦合了定位开关即使neverForLocationtrue部分ROM仍需“位置信息”总开关打开才能扫描。检查是否开启了蓝牙扫描过滤ScanFilter过滤条件太严格会过滤掉所有设备。检查扫描回调是否在正确线程注册startScan传的callback在Binder线程回调不要在回调里直接操作UI。检查是否是多应用同时扫描Android系统对BLE扫描有内部频率限制多个App同时扫描会导致其中一个被系统强制停止回调。我踩过的一个个很典型的坑是适配Android 12后用BLUETOOTH_SCAN权限扫描正常但一旦同时请求ACCESS_FINE_LOCATION再把两者都拒绝一次之后即使重新授予附近设备权限扫描回调也不触发。后来查了半天发现是华为某机型把“附近设备”权限和“位置信息”开关做了联动必须把定位总开关打开。这类问题跟代码关系不大但会浪费大量排查时间建议大家遇到扫描不到设备时先检查系统设置。5.3 onScanResult回调频率异常与扫描策略建议Android 12之后系统对BLE扫描的节流更强了。如果你在startScan时传了ScanCallback但没有指定ScanSettings的setReportDelay某些设备上会发现onScanResult回调频率忽高忽低尤其在亮屏、灭屏切换和后台运行时。我的实践建议是前台扫描时ScanSettings.Builder().setScanMode(ScanSettings.SCAN_MODE_LOW_LATENCY)。后台扫描时把扫描模式降到SCAN_MODE_LOW_POWER并用setReportDelay(2000)做批处理减少系统压力。一定记得在页面暂停或服务销毁时调用stopScan否则会持续占用蓝牙资源导致其他App也扫不到。还有一个经验是如果你的扫描逻辑和连接逻辑放在同一进程建议把扫描回调与连接回调分开线程处理避免onScanResult里的耗时操作阻塞Binder线程进而影响onConnectionStateChange回调。5.4 旧的蓝牙广播与动态注册变化Android 12对蓝牙广播的注册方式也做了收紧。以前监听BluetoothDevice.ACTION_FOUND和BluetoothAdapter.ACTION_DISCOVERY_FINISHED直接在Manifest里静态注册Receiver就能收到。target 31之后这种隐式广播在很多场景下已经收不到了必须改成本地动态注册。val filter IntentFilter().apply { addAction(BluetoothDevice.ACTION_FOUND) addAction(BluetoothAdapter.ACTION_DISCOVERY_FINISHED) } val receiver object : BroadcastReceiver() { override fun onReceive(context: Context?, intent: Intent?) { when (intent?.action) { BluetoothDevice.ACTION_FOUND - { val device intent.getParcelableExtraBluetoothDevice(BluetoothDevice.EXTRA_DEVICE) // 处理扫描到的设备 } BluetoothAdapter.ACTION_DISCOVERY_FINISHED - { // 扫描结束 } } } } ContextCompat.registerReceiver( this, receiver, filter, ContextCompat.RECEIVER_NOT_EXPORTED )动态注册时ContextCompat.RECEIVER_NOT_EXPORTED这个flag很重要。target 31之后如果Receiver没有指定exported属性系统默认视为false跨应用的隐式广播可能会收不到。蓝牙相关的系统广播一般用RECEIVER_NOT_EXPORTED就够了如果业务需要接收其他应用发来的广播再考虑RECEIVER_EXPORTED但这类需求在蓝牙业务里非常少见。5.5 系统App与特权权限场景参考如果你做的是系统预装App或者SystemUIDemo这类特权应用有另外一种授权思路在Android 12的系统中可以通过privapp-permissions白名单机制直接授予BLUETOOTH_SCAN、BLUETOOTH_CONNECT等权限绕过运行时申请弹窗。具体做法是在/etc/permissions/下放一个XML声明对应包名和权限列表。这种场景下Manifest里仍然要声明权限但运行时不需要动态申请。这部分帮助理解自定义ROM时蓝牙权限的来源是哪儿来的。实际开发现场绝大多数应用还是走正常的运行时申请逻辑没必要为了省一次弹窗去做特权白名单除非你的App是系统内置应用否则生命周期管理会很麻烦。6. 从权限适配延展到系统定制场景的几点思考6.1 从“默认授予所有应用权限”聊到预授权机制开发自定义固件、企业管控类App的时候很多人会想“能不能直接默认授权所有应用、省去用户点弹窗的麻烦”。在Android 12的蓝牙权限体系下这个需求可以分层实现系统应用层面可以对特定包名在DefaultPermissionGrantPolicy里配置默认授予策略。普通应用层面可以用AppOpsManager或DevicePolicyManager做一些受限场景下的权限管控但前提是App必须有设备管理员Device Admin权限。不过我不建议在非定制系统上走“默认授权所有应用”的路线因为这会直接削弱Android 12的隐私保护设计审核上可能也会有问题。如果只是内部测试机或者演示机可以在开发阶段用adb命令快速授予权限adb shell pm grant com.example.bleapp android.permission.BLUETOOTH_SCAN adb shell pm grant com.example.bleapp android.permission.BLUETOOTH_CONNECT adb shell pm grant com.example.bleapp android.permission.BLUETOOTH_ADVERTISE6.2 蓝牙扫描与系统动效/旋转屏场景的相互影响有一类不太起眼但实际存在的问题Android 12平板或车机上系统旋转屏180度方向调整时会导致Activity重建进而打断BLE扫描流程。如果你在做车载蓝牙或平板蓝牙配对工具这个场景几乎必现。处理方式有两种在AndroidManifest.xml中给对应Activity设置screenOrientation为nosensor或landscape避免旋转触发重建或者更优雅的做法是把蓝牙扫描实例提升到Application级别持有让Activity旋转时扫描不中断。每次Activity重建后重新startScan的做法在低速轮询类业务里简单可行但在需要连续扫描回调的场景下会出现重复回调或者漏回调体验很不好。6.3 init分区挂载与WiFi DHCP的“不相关”联想热搜词里出现了android12 init分区挂载和android12 wifi dhcp乍看和蓝牙权限八竿子打不着但实际做系统定制时你会发现这三者经常被放在一起排查问题——因为定制固件时蓝牙、WiFi、NFC这些连接类权限都是预置在系统镜像里的如果init脚本或partition挂载阶段出了问题可能导致权限文件没有正确加载进而出现“系统设置里看不到附近设备权限”、“权限申请弹窗无法弹出”这类问题。遇到这种情况第一步不是改代码而是检查adb shell dumpsys package里目标App的权限状态是否正常再检查/system/etc/permissions/下是否有对应权限文件被成功挂载。我见过一个比较极端的案例某定制ROM把privapp-permissions文件放错了分区路径导致系统应用的所有特权权限全部丢失蓝牙扫描权限自然也在其中排查了大半天才定位到是文件挂载问题而不是代码逻辑问题。所以做系统定制时权限相关问题的排查一定要把镜像文件路径和挂载情况纳入考虑范围。7. 权限策略设计经验与收尾小技巧最后聊几个我自己实践后觉得非常有用的经验第一尽量做一个统一权限策略层。不管是扫描、广播还是连接不要把权限判断散落在各个业务模块里。建议把权限请求、权限状态监听、权限被拒后的引导跳转全部收敛到一个PermissionManager里。当你面对线上用户“权限被拒绝后功能不可用”的投诉时你会感谢当初自己的设计。第二权限文案提前配合好。BLUETOOTH_SCAN的弹窗标题是系统固定的但权限弹窗下方的“App说明”文案即requestPermissionRationale相关的逻辑是可以自定义的。在用户第一次拒绝后可以在界面上展示一个包含业务场景说明的Dialog告诉用户“为什么需要蓝牙权限”然后再引导用户去设置页开启。别小看这一步实测下来能提升不少授权转化率。第三做好权限回调的幂等处理。用户可能随时去系统设置关掉权限或者App在后台被系统杀掉。每次进入蓝牙功能页时都重新校验权限状态不要缓存授权结果。第四日志要打好。蓝牙权限问题有个特点直接看源码很难快速定位因为它与系统版本、ROM定制、用户操作路径都有关。建议在onRequestPermissionsResult回调、startScan、connectGatt、onConnectionStateChange这四处都打上Log配合adb bugreport能省下不少口水。Android 12的蓝牙权限改动本质上是一次隐私模型的进化。它让用户对“蓝牙能力”有了更清晰的知情权也让开发者在申请权限时不得不去思考每个真正需要蓝牙的业务场景。适配确实有点繁琐但做成一次后面Android 13、Android 14的蓝牙相关改动就会轻松很多。根据我的实际体验只要能静下心来把手动扫描、自动重连、后台扫描这几条链路的权限申请逻辑理顺Android 12蓝牙权限这套体系用起来还是很顺手的。希望这篇内容能帮大家少踩几个坑把适配时间从几天压缩到半天。