1. 項(xiàng)目背景與問(wèn)題現(xiàn)象最近在適配Android 12API 31及以上版本的藍(lán)牙功能時(shí)一個(gè)非常典型且高頻的“坑”出現(xiàn)了你的應(yīng)用明明在Android 11上運(yùn)行得好好的藍(lán)牙掃描能發(fā)現(xiàn)一堆設(shè)備但一到Android 12的設(shè)備上掃描結(jié)果就空空如也日志里除了你自己的應(yīng)用日志系統(tǒng)關(guān)于藍(lán)牙發(fā)現(xiàn)的日志也少得可憐。這絕不是你的代碼邏輯突然失效了而是Google在Android 12中引入了一套更嚴(yán)格的運(yùn)行時(shí)權(quán)限模型特別是針對(duì)藍(lán)牙掃描這一涉及位置信息的行為。這個(gè)問(wèn)題困擾了相當(dāng)多的開(kāi)發(fā)者尤其是那些需要與藍(lán)牙低功耗BLE設(shè)備或經(jīng)典藍(lán)牙設(shè)備交互的應(yīng)用比如智能家居控制、健康設(shè)備數(shù)據(jù)同步、文件傳輸工具等。從用戶(hù)和測(cè)試的角度看應(yīng)用“失靈”了但從開(kāi)發(fā)角度看這是一個(gè)必須跨越的權(quán)限門(mén)檻。我花了些時(shí)間把Android 12及更高版本上藍(lán)牙掃描所需的權(quán)限梳理了一遍并記錄了完整的排查和解決方案。如果你也遇到了“掃描不到設(shè)備”的靈異事件這篇筆記應(yīng)該能幫你快速定位問(wèn)題。2. Android 12藍(lán)牙權(quán)限模型的核心變化要解決問(wèn)題首先得理解Google為什么這么做以及具體改了哪里。在Android 12之前進(jìn)行藍(lán)牙掃描特別是BLE掃描主要需要兩個(gè)權(quán)限ACCESS_FINE_LOCATION精確定位和BLUETOOTH_SCAN在Android 11引入。當(dāng)時(shí)的邏輯是因?yàn)樗{(lán)牙掃描結(jié)果特別是BLE設(shè)備的信號(hào)強(qiáng)度RSSI可以被用來(lái)進(jìn)行粗略的室內(nèi)定位所以它被歸類(lèi)為一種“位置信息”訪問(wèn)需要位置權(quán)限。到了Android 12權(quán)限管理變得更加精細(xì)和嚴(yán)格。核心變化在于將“藍(lán)牙掃描”這個(gè)行為本身從“位置信息”的范疇中部分剝離出來(lái)并強(qiáng)調(diào)了其“鄰近設(shè)備”訪問(wèn)的特性。這帶來(lái)了幾個(gè)關(guān)鍵點(diǎn)2.1 新增的BLUETOOTH_SCAN權(quán)限成為絕對(duì)主角在Android 12API 31及以上版本BLUETOOTH_SCAN權(quán)限從之前的“普通”權(quán)限升級(jí)為“運(yùn)行時(shí)”權(quán)限。這意味著必須聲明在AndroidManifest.xml中必須聲明此權(quán)限。必須動(dòng)態(tài)申請(qǐng)?jiān)诖a中必須在運(yùn)行時(shí)向用戶(hù)彈窗請(qǐng)求授權(quán)就像請(qǐng)求相機(jī)、位置權(quán)限一樣。獨(dú)立控制用戶(hù)可以在系統(tǒng)設(shè)置中單獨(dú)控制某個(gè)應(yīng)用是否擁有“藍(lán)牙掃描”的權(quán)限而不再完全與位置權(quán)限綁定。2.2 與位置權(quán)限的“脫鉤”與“有條件關(guān)聯(lián)”這是最容易讓人困惑的地方。Android 12允許你的應(yīng)用在不訪問(wèn)設(shè)備位置信息的前提下進(jìn)行藍(lán)牙掃描。這是通過(guò)BLUETOOTH_SCAN權(quán)限的android:usesPermissionFlags屬性實(shí)現(xiàn)的。你可以在聲明權(quán)限時(shí)添加neverForLocation標(biāo)志。這樣系統(tǒng)就會(huì)明白“這個(gè)應(yīng)用掃描藍(lán)牙只是為了連接設(shè)備不是為了獲取位置。” 用戶(hù)授予BLUETOOTH_SCAN權(quán)限時(shí)系統(tǒng)可能就不會(huì)再?gòu)?qiáng)制要求位置權(quán)限。但是“脫鉤”是有條件的如果你的應(yīng)用需要從掃描結(jié)果中獲取位置信息例如你需要使用ScanResult中的Rssi信號(hào)強(qiáng)度或TimestampNanos等信息來(lái)進(jìn)行三角定位或位置推斷那么你仍然需要ACCESS_FINE_LOCATION權(quán)限。如果你的應(yīng)用僅為了發(fā)現(xiàn)和連接設(shè)備例如連接一個(gè)藍(lán)牙音箱、智能燈泡你只需要知道附近有這些設(shè)備并獲取其地址MAC地址用于連接那么你可以聲明neverForLocation標(biāo)志從而可能避免申請(qǐng)位置權(quán)限。2.3 其他必要權(quán)限的鞏固除了掃描連接和管理藍(lán)牙設(shè)備還需要其他權(quán)限BLUETOOTH_CONNECT用于連接藍(lán)牙設(shè)備、與已配對(duì)設(shè)備通信、訪問(wèn)設(shè)備信息等。這在Android 12也成為了運(yùn)行時(shí)權(quán)限。BLUETOOTH_ADVERTISE如果你的應(yīng)用自身要作為藍(lán)牙外圍設(shè)備廣播例如讓手機(jī)模擬一個(gè)Beacon則需要此權(quán)限。ACCESS_BACKGROUND_LOCATION如果你的應(yīng)用需要在后臺(tái)應(yīng)用不可見(jiàn)時(shí)持續(xù)進(jìn)行藍(lán)牙掃描那么即使你聲明了neverForLocation在Android 10及以上版本后臺(tái)掃描行為本身就可能觸發(fā)系統(tǒng)對(duì)后臺(tái)位置訪問(wèn)的限制可能需要此權(quán)限。但情況較為復(fù)雜通常前臺(tái)掃描足夠。下表總結(jié)了不同場(chǎng)景下的權(quán)限需求操作場(chǎng)景Android 11及以前Android 12及以后 (聲明neverForLocation)Android 12及以后 (需要位置信息)前臺(tái)掃描發(fā)現(xiàn)BLE設(shè)備BLUETOOTH_SCAN(普通) ACCESS_FINE_LOCATION(運(yùn)行時(shí))BLUETOOTH_SCAN(運(yùn)行時(shí))BLUETOOTH_SCAN(運(yùn)行時(shí)) ACCESS_FINE_LOCATION(運(yùn)行時(shí))連接已發(fā)現(xiàn)/已配對(duì)設(shè)備BLUETOOTH(普通) BLUETOOTH_ADMIN(普通)BLUETOOTH_CONNECT(運(yùn)行時(shí))BLUETOOTH_CONNECT(運(yùn)行時(shí))應(yīng)用作為外圍設(shè)備廣播BLUETOOTH_ADVERTISE(普通)BLUETOOTH_ADVERTISE(運(yùn)行時(shí))BLUETOOTH_ADVERTISE(運(yùn)行時(shí))后臺(tái)持續(xù)掃描上述權(quán)限 ACCESS_BACKGROUND_LOCATION(運(yùn)行時(shí))可能仍需ACCESS_BACKGROUND_LOCATION取決于掃描結(jié)果用途ACCESS_BACKGROUND_LOCATION(運(yùn)行時(shí))3. 完整解決方案與代碼實(shí)現(xiàn)理解了原理我們來(lái)看具體怎么做。這里以一個(gè)典型的“掃描并連接BLE設(shè)備”的應(yīng)用為例假設(shè)我們不需要位置信息僅為了設(shè)備連接。3.1 AndroidManifest.xml 權(quán)限聲明這是第一步也是最容易出錯(cuò)的一步。聲明必須準(zhǔn)確無(wú)誤。manifest xmlns:androidhttp://schemas.android.com/apk/res/android packagecom.example.mybluetoothapp !-- 對(duì)于 Android 12 (API 31) 藍(lán)牙掃描聲明不用于定位 -- uses-permission android:nameandroid.permission.BLUETOOTH_SCAN android:usesPermissionFlagsneverForLocation / !-- 對(duì)于 Android 12 (API 31) 藍(lán)牙連接 -- uses-permission android:nameandroid.permission.BLUETOOTH_CONNECT / !-- 對(duì)于 Android 6.0 到 Android 11 (API 23-30) 藍(lán)牙掃描需要的位置權(quán)限 -- !-- 注意即使你的 targetSdkVersion 31為了兼容舊設(shè)備最好也加上 -- uses-permission android:nameandroid.permission.ACCESS_FINE_LOCATION / !-- 如果需要后臺(tái)掃描則還需要這個(gè)謹(jǐn)慎使用 -- !-- uses-permission android:nameandroid.permission.ACCESS_BACKGROUND_LOCATION / -- !-- 傳統(tǒng)藍(lán)牙權(quán)限用于 Android 11 及以下 -- uses-permission android:nameandroid.permission.BLUETOOTH / uses-permission android:nameandroid.permission.BLUETOOTH_ADMIN / !-- 如果只針對(duì) BLE 設(shè)備可以聲明此 feature -- uses-feature android:nameandroid.hardware.bluetooth_le android:requiredtrue/ application ... ... /application /manifest關(guān)鍵點(diǎn)解析android:usesPermissionFlagsneverForLocation這是Android 12權(quán)限聲明的精髓。它明確告知系統(tǒng)你申請(qǐng)BLUETOOTH_SCAN權(quán)限的目的不是為了獲取位置。這能帶來(lái)兩個(gè)好處1) 在Android 12設(shè)備上系統(tǒng)可能不會(huì)強(qiáng)制要求你同時(shí)擁有位置權(quán)限2) 在申請(qǐng)彈窗中向用戶(hù)說(shuō)明的理由會(huì)更清晰例如“允許應(yīng)用發(fā)現(xiàn)附近的設(shè)備”而不是“允許應(yīng)用訪問(wèn)位置”。兼容性聲明即使targetSdkVersion設(shè)為31或更高你仍然需要聲明ACCESS_FINE_LOCATION。因?yàn)楫?dāng)你的應(yīng)用安裝在Android 11API 30的設(shè)備上時(shí)系統(tǒng)會(huì)忽略BLUETOOTH_SCAN的聲明因?yàn)樵撓到y(tǒng)版本不存在此權(quán)限轉(zhuǎn)而檢查ACCESS_FINE_LOCATION。這是一種標(biāo)準(zhǔn)的向后兼容做法。BLUETOOTH和BLUETOOTH_ADMIN在舊版本系統(tǒng)上這些是必需的。即使在新系統(tǒng)上聲明它們也無(wú)害系統(tǒng)會(huì)忽略已廢棄的權(quán)限。3.2 運(yùn)行時(shí)權(quán)限動(dòng)態(tài)申請(qǐng)聲明了權(quán)限接下來(lái)就是在合適的時(shí)機(jī)例如進(jìn)入掃描界面時(shí)向用戶(hù)申請(qǐng)。我們需要處理Android 12的新權(quán)限和舊版本的位置權(quán)限。import android.Manifest import android.bluetooth.BluetoothAdapter import android.content.pm.PackageManager import android.os.Build import androidx.activity.result.contract.ActivityResultContracts import androidx.appcompat.app.AppCompatActivity import androidx.core.content.ContextCompat class BluetoothScanActivity : AppCompatActivity() { private lateinit var bluetoothAdapter: BluetoothAdapter // 使用 Activity Result API 簡(jiǎn)化權(quán)限請(qǐng)求回調(diào)處理 private val requestPermissionLauncher registerForActivityResult( ActivityResultContracts.RequestMultiplePermissions() ) { permissions - val allGranted permissions.entries.all { it.value } if (allGranted) { // 所有必要權(quán)限都已授予可以開(kāi)始掃描 startBluetoothScan() } else { // 有權(quán)限被拒絕向用戶(hù)解釋為什么需要這些權(quán)限 showPermissionDeniedDialog() } } override fun onStart() { super.onStart() checkAndRequestPermissions() } private fun checkAndRequestPermissions() { val permissionsToRequest mutableListOfString() // 檢查藍(lán)牙硬件支持 bluetoothAdapter BluetoothAdapter.getDefaultAdapter() ?: run { showToast(該設(shè)備不支持藍(lán)牙) return } // 1. 檢查并添加 Android 12 (API 31) 的權(quán)限 if (Build.VERSION.SDK_INT Build.VERSION_CODES.S) { // BLUETOOTH_SCAN 權(quán)限用于發(fā)現(xiàn)設(shè)備 if (ContextCompat.checkSelfPermission(this, Manifest.permission.BLUETOOTH_SCAN) ! PackageManager.PERMISSION_GRANTED ) { permissionsToRequest.add(Manifest.permission.BLUETOOTH_SCAN) } // BLUETOOTH_CONNECT 權(quán)限用于連接設(shè)備如果你在掃描后需要連接 if (ContextCompat.checkSelfPermission(this, Manifest.permission.BLUETOOTH_CONNECT) ! PackageManager.PERMISSION_GRANTED ) { permissionsToRequest.add(Manifest.permission.BLUETOOTH_CONNECT) } } else { // 2. 檢查并添加 Android 6.0 到 Android 11 (API 23-30) 的位置權(quán)限 // 注意在 Android 11 上即使聲明了 BLUETOOTH_SCAN普通權(quán)限掃描 BLE 仍需位置權(quán)限 if (ContextCompat.checkSelfPermission(this, Manifest.permission.ACCESS_FINE_LOCATION) ! PackageManager.PERMISSION_GRANTED ) { permissionsToRequest.add(Manifest.permission.ACCESS_FINE_LOCATION) } } // 3. 對(duì)于所有版本檢查藍(lán)牙開(kāi)關(guān)這不是權(quán)限但必須開(kāi)啟 if (!bluetoothAdapter.isEnabled) { // 可以引導(dǎo)用戶(hù)打開(kāi)藍(lán)牙這里使用一個(gè)簡(jiǎn)單的提示 showEnableBluetoothDialog() return // 先不請(qǐng)求權(quán)限等藍(lán)牙打開(kāi)再說(shuō) } // 4. 如果有需要申請(qǐng)的權(quán)限則發(fā)起請(qǐng)求 if (permissionsToRequest.isNotEmpty()) { requestPermissionLauncher.launch(permissionsToRequest.toTypedArray()) } else { // 所有權(quán)限都已具備藍(lán)牙已開(kāi)啟直接開(kāi)始掃描 startBluetoothScan() } } private fun startBluetoothScan() { // 這里實(shí)現(xiàn)你的藍(lán)牙掃描邏輯例如使用 BluetoothLeScanner // val scanner bluetoothAdapter.bluetoothLeScanner // val settings ScanSettings.Builder().build() // val filters listOfScanFilter() // 可以添加過(guò)濾條件 // scanner.startScan(filters, settings, scanCallback) showToast(權(quán)限檢查通過(guò)開(kāi)始掃描...) // ... 實(shí)際掃描代碼 } // 輔助方法顯示對(duì)話框等UI交互 private fun showEnableBluetoothDialog() { /* ... */ } private fun showPermissionDeniedDialog() { /* ... */ } private fun showToast(message: String) { /* ... */ } }代碼邏輯拆解版本判斷是核心我們首先根據(jù)Build.VERSION.SDK_INT判斷設(shè)備系統(tǒng)版本。對(duì)于Android 12S/API 31及以上我們動(dòng)態(tài)申請(qǐng)BLUETOOTH_SCAN和BLUETOOTH_CONNECT。對(duì)于Android 11及以下我們申請(qǐng)ACCESS_FINE_LOCATION。權(quán)限檢查前置在申請(qǐng)前先用ContextCompat.checkSelfPermission檢查權(quán)限是否已授予。只申請(qǐng)未被授予的權(quán)限避免不必要的彈窗打擾用戶(hù)。藍(lán)牙開(kāi)關(guān)檢查無(wú)論權(quán)限如何藍(lán)牙硬件必須開(kāi)啟。這是一個(gè)獨(dú)立于權(quán)限的系統(tǒng)狀態(tài)檢查。通常我們會(huì)先確保藍(lán)牙開(kāi)啟再處理權(quán)限問(wèn)題。使用現(xiàn)代APIregisterForActivityResult配合ActivityResultContracts.RequestMultiplePermissions是處理運(yùn)行時(shí)權(quán)限的最佳實(shí)踐它避免了重寫(xiě)onRequestPermissionsResult方法的繁瑣使代碼更清晰。優(yōu)雅降級(jí)如果用戶(hù)拒絕了權(quán)限應(yīng)該有一個(gè)友好的界面showPermissionDeniedDialog向用戶(hù)解釋這些權(quán)限對(duì)于應(yīng)用核心功能如連接智能設(shè)備的必要性并引導(dǎo)用戶(hù)去應(yīng)用設(shè)置頁(yè)面手動(dòng)開(kāi)啟。3.3 掃描邏輯的實(shí)現(xiàn)與適配權(quán)限搞定后掃描邏輯本身也需要針對(duì)Android 12進(jìn)行微調(diào)。主要是ScanSettings的配置。import android.bluetooth.le.ScanCallback import android.bluetooth.le.ScanFilter import android.bluetooth.le.ScanResult import android.bluetooth.le.ScanSettings import android.os.Build import android.os.Handler import android.os.Looper private val scanCallback object : ScanCallback() { override fun onScanResult(callbackType: Int, result: ScanResult) { // 處理掃描到的設(shè)備 val device result.device val rssi result.rssi // 注意在聲明了 neverForLocation 后此值可能為0 val scanRecord result.scanRecord // ... 更新UI將設(shè)備添加到列表 } override fun onScanFailed(errorCode: Int) { // 掃描失敗處理常見(jiàn)錯(cuò)誤碼如 SCAN_FAILED_APPLICATION_REGISTRATION_FAILED應(yīng)用注冊(cè)失敗通常權(quán)限問(wèn)題 // 或 SCAN_FAILED_FEATURE_UNSUPPORTED不支持BLE等 showToast(掃描失敗錯(cuò)誤碼: $errorCode) } } private fun buildScanSettings(): ScanSettings { val builder ScanSettings.Builder() .setScanMode(ScanSettings.SCAN_MODE_LOW_LATENCY) // 掃描模式低延遲發(fā)現(xiàn)設(shè)備最快 // Android 12 的重要適配如果你聲明了 neverForLocation且不需要RSSI可以設(shè)置此標(biāo)志 if (Build.VERSION.SDK_INT Build.VERSION_CODES.S) { // 這個(gè)標(biāo)志告訴硬件可以為了省電而降低掃描報(bào)告頻率因?yàn)槲覀儾魂P(guān)心精確的RSSI // 注意設(shè)置此標(biāo)志后onScanResult回調(diào)的頻率可能會(huì)降低且RSSI可能不準(zhǔn)確或?yàn)? builder.setLegacy(false) // 對(duì)于只關(guān)心新BLE設(shè)備的情況可以設(shè)為false // 如果你確實(shí)需要RSSI做信號(hào)篩選就不要加下面這行 // builder.setPhy(ScanSettings.PHY_LE_ALL_SUPPORTED) } return builder.build() } fun startScan() { val scanner bluetoothAdapter.bluetoothLeScanner val filters listOfScanFilter() // 可以按設(shè)備名、服務(wù)UUID等過(guò)濾提高效率 val settings buildScanSettings() // 開(kāi)始掃描 scanner.startScan(filters, settings, scanCallback) showToast(掃描已啟動(dòng)) // 可選掃描10秒后自動(dòng)停止節(jié)省電量 Handler(Looper.getMainLooper()).postDelayed({ stopScan() }, 10000) } fun stopScan() { bluetoothAdapter.bluetoothLeScanner?.stopScan(scanCallback) showToast(掃描已停止) }關(guān)鍵點(diǎn)與避坑指南setLegacy(false)在Android 12上這個(gè)設(shè)置與neverForLocation標(biāo)志協(xié)同工作。它告訴底層藍(lán)牙棧你不需要為了向后兼容舊版掃描報(bào)告格式而做額外處理。對(duì)于只針對(duì)Android 5.0以上新BLE規(guī)范的應(yīng)用設(shè)置為false可能更高效。但如果你需要掃描一些舊設(shè)備或遇到掃描問(wèn)題可以嘗試設(shè)為true或移除這行。RSSI值可能為0這是聲明neverForLocation后一個(gè)非常重要的副作用。系統(tǒng)或硬件為了保護(hù)位置隱私可能會(huì)在掃描結(jié)果中屏蔽或歸零RSSI值。如果你的邏輯依賴(lài)RSSI來(lái)篩選信號(hào)強(qiáng)的設(shè)備比如只連接-70dBm以上的設(shè)備那么你就不能聲明neverForLocation必須同時(shí)申請(qǐng)位置權(quán)限。掃描過(guò)濾使用ScanFilter能極大提升掃描效率減少不必要的回調(diào)和處理。例如如果你只尋找特定服務(wù)UUID的設(shè)備務(wù)必加上過(guò)濾器。4. 問(wèn)題排查與深度調(diào)試即使按照上面的步驟做了有時(shí)候掃描依然不工作。這時(shí)候就需要系統(tǒng)化的排查。以下是我總結(jié)的排查清單按照從外到內(nèi)、從易到難的順序進(jìn)行。4.1 基礎(chǔ)環(huán)境檢查設(shè)備藍(lán)牙是否真的開(kāi)啟通過(guò)系統(tǒng)設(shè)置確認(rèn)而不僅僅是代碼檢查。有時(shí)代碼檢查返回true但硬件或驅(qū)動(dòng)層可能有問(wèn)題。目標(biāo)藍(lán)牙設(shè)備是否處于可發(fā)現(xiàn)模式BLE設(shè)備通常需要處于廣播狀態(tài)經(jīng)典藍(lán)牙設(shè)備需要處于“可被檢測(cè)”狀態(tài)。物理距離和干擾將設(shè)備靠近1米內(nèi)排除信號(hào)弱的問(wèn)題。遠(yuǎn)離Wi-Fi路由器、微波爐等2.4GHz干擾源。其他應(yīng)用能否掃描到使用“nRF Connect”、“LightBlue”等通用的藍(lán)牙調(diào)試APP測(cè)試。如果它們也掃不到很可能是目標(biāo)設(shè)備或手機(jī)藍(lán)牙硬件的問(wèn)題。如果它們能掃到而你的應(yīng)用不能問(wèn)題就在你的應(yīng)用上。4.2 應(yīng)用權(quán)限與配置檢查檢查AndroidManifest.xml確保權(quán)限聲明沒(méi)有拼寫(xiě)錯(cuò)誤uses-permission標(biāo)簽在正確的層級(jí)。特別注意android:usesPermissionFlagsneverForLocation是否只附加在BLUETOOTH_SCAN上。檢查targetSdkVersion在app/build.gradle中確保targetSdkVersion至少為31如果你要適配Android 12的新權(quán)限模型。如果targetSdkVersion低于31系統(tǒng)會(huì)使用舊版的權(quán)限規(guī)則但你又聲明了新權(quán)限可能導(dǎo)致行為不一致。動(dòng)態(tài)權(quán)限狀態(tài)復(fù)查在申請(qǐng)權(quán)限的回調(diào)中打印或記錄所有請(qǐng)求權(quán)限的授予狀態(tài)。使用ActivityResultContracts.RequestMultiplePermissions返回的MapString, Boolean來(lái)確認(rèn)。private val requestPermissionLauncher registerForActivityResult( ActivityResultContracts.RequestMultiplePermissions() ) { permissions - permissions.entries.forEach { entry - Log.d(PermissionDebug, ${entry.key} : ${entry.value}) } // ... 后續(xù)處理 }檢查是否在后臺(tái)從Android 10開(kāi)始對(duì)后臺(tái)應(yīng)用獲取位置信息包括通過(guò)藍(lán)牙掃描間接獲取有嚴(yán)格限制。確保你的掃描代碼是在應(yīng)用處于前臺(tái)Activity可見(jiàn)時(shí)執(zhí)行的。如果你需要在后臺(tái)掃描那將是一個(gè)更復(fù)雜的課題涉及前臺(tái)服務(wù)、后臺(tái)位置權(quán)限和更嚴(yán)格的審核。4.3 日志與系統(tǒng)信息分析當(dāng)基礎(chǔ)檢查都通過(guò)后就需要深入系統(tǒng)內(nèi)部看日志。查看應(yīng)用日志過(guò)濾你的應(yīng)用Tag檢查是否有SecurityException或類(lèi)似“Permission Denial”的異常拋出。查看系統(tǒng)藍(lán)牙日志這是最有效的手段。使用adb logcat命令過(guò)濾藍(lán)牙相關(guān)的系統(tǒng)日志。adb logcat | grep -E (Bluetooth|BT|BLE|ScanManager|AdapterService)或者更精確地在Android Studio的Logcat中選擇設(shè)備后添加過(guò)濾器tag:Bluetooth或tag:BluetoothAdapter。重點(diǎn)觀察以下日志當(dāng)你調(diào)用startScan()時(shí)是否有類(lèi)似App your.package.name is not allowed to use Bluetooth或Scan failed, app uid XXXX not allowed to scan的錯(cuò)誤。這直接指向權(quán)限問(wèn)題。是否有Scanning too frequent之類(lèi)的警告Android對(duì)掃描頻率有限制過(guò)于頻繁的啟停掃描會(huì)被系統(tǒng)限制。檢查系統(tǒng)權(quán)限設(shè)置頁(yè)面手動(dòng)進(jìn)入手機(jī)的設(shè)置 應(yīng)用 你的應(yīng)用 權(quán)限查看“附近設(shè)備”對(duì)應(yīng)BLUETOOTH_SCAN和“位置信息”權(quán)限是否確認(rèn)為“允許”。注意在Android 13位置權(quán)限可能細(xì)分為“僅在使用中允許”和“始終允許”確保符合你的場(chǎng)景。4.4 代碼邏輯與API使用復(fù)查掃描回調(diào)是否注冊(cè)成功確保startScan被調(diào)用并且傳入的scanCallback對(duì)象是有效的、未被垃圾回收的例如作為Activity的成員變量持有。掃描設(shè)置是否過(guò)于苛刻檢查ScanSettings比如setScanMode(ScanSettings.SCAN_MODE_LOW_POWER)在低功耗模式下發(fā)現(xiàn)設(shè)備會(huì)很慢。對(duì)于測(cè)試建議使用SCAN_MODE_LOW_LATENCY。過(guò)濾器是否過(guò)濾掉了所有設(shè)備如果你使用了ScanFilter檢查過(guò)濾條件如設(shè)備名稱(chēng)、MAC地址、服務(wù)UUID是否寫(xiě)錯(cuò)導(dǎo)致所有設(shè)備都被過(guò)濾掉。嘗試不設(shè)過(guò)濾器或設(shè)置一個(gè)寬泛的過(guò)濾器進(jìn)行測(cè)試。是否在掃描過(guò)程中停止了藍(lán)牙適配器確保在掃描生命周期內(nèi)從startScan到stopScanBluetoothAdapter對(duì)象是有效的并且藍(lán)牙沒(méi)有在中間被系統(tǒng)或用戶(hù)關(guān)閉。4.5 針對(duì)特定機(jī)型或系統(tǒng)的特殊處理有些廠商如小米、華為、OPPO、Vivo的定制系統(tǒng)MIUI、EMUI等有更激進(jìn)的權(quán)限管理或后臺(tái)限制。自啟動(dòng)管理在部分系統(tǒng)上即使授予了所有權(quán)限應(yīng)用如果被“禁止自啟動(dòng)”或“關(guān)聯(lián)啟動(dòng)”后臺(tái)掃描可能被殺死。需要引導(dǎo)用戶(hù)手動(dòng)在手機(jī)管家中設(shè)置。省電策略檢查是否將你的應(yīng)用加入了“電池優(yōu)化”的白名單。在設(shè)置中搜索“電池優(yōu)化”找到你的應(yīng)用選擇“不優(yōu)化”。懸浮窗權(quán)限等雖然與藍(lán)牙掃描無(wú)直接關(guān)系但某些系統(tǒng)會(huì)將這些非常規(guī)權(quán)限與后臺(tái)活動(dòng)關(guān)聯(lián)導(dǎo)致應(yīng)用行為異常。如果排查所有可能性后仍無(wú)效可以查閱該機(jī)型開(kāi)發(fā)者的官方論壇或社區(qū)看是否有已知的特定限制。5. 進(jìn)階考量與最佳實(shí)踐解決了基本掃描問(wèn)題后為了構(gòu)建一個(gè)健壯的藍(lán)牙應(yīng)用還需要考慮以下幾點(diǎn)。5.1 后臺(tái)掃描的復(fù)雜性如前所述在后臺(tái)進(jìn)行藍(lán)牙掃描是一個(gè)“深水區(qū)”。從Android 10開(kāi)始后臺(tái)應(yīng)用訪問(wèn)位置信息受到嚴(yán)格限制。即使你聲明了neverForLocation持續(xù)的后臺(tái)掃描行為本身也可能被系統(tǒng)視為潛在的位置訪問(wèn)行為從而觸發(fā)限制。建議盡量避免持續(xù)后臺(tái)掃描這是最省心省電的做法?？紤]使用以下替代方案前臺(tái)服務(wù)當(dāng)應(yīng)用需要長(zhǎng)時(shí)間掃描時(shí)啟動(dòng)一個(gè)帶有持續(xù)通知的前臺(tái)服務(wù)。這明確告知用戶(hù)應(yīng)用正在活動(dòng)并通常能獲得更穩(wěn)定的系統(tǒng)資源。定時(shí)掃描使用WorkManager或AlarmManager安排定期、短暫的掃描任務(wù)而不是7x24小時(shí)不間斷掃描。使用系統(tǒng)廣播有限對(duì)于已配對(duì)設(shè)備的連接狀態(tài)變化可以監(jiān)聽(tīng)BluetoothDevice.ACTION_ACL_CONNECTED和ACTION_ACL_DISCONNECTED廣播但這無(wú)法發(fā)現(xiàn)新設(shè)備。如果必須后臺(tái)掃描確保申請(qǐng)了ACCESS_BACKGROUND_LOCATION權(quán)限這是一個(gè)敏感權(quán)限上架Google Play需要額外聲明和審核。在應(yīng)用商店的描述中清晰說(shuō)明為什么需要此權(quán)限。準(zhǔn)備處理用戶(hù)拒絕該權(quán)限的情況并提供優(yōu)雅降級(jí)方案例如僅支持前臺(tái)掃描功能。5.2 權(quán)限申請(qǐng)的時(shí)機(jī)與用戶(hù)體驗(yàn)不要一進(jìn)入應(yīng)用就彈出一堆權(quán)限請(qǐng)求這會(huì)讓用戶(hù)反感。適時(shí)請(qǐng)求在用戶(hù)即將使用需要該權(quán)限的功能時(shí)再請(qǐng)求。例如在用戶(hù)點(diǎn)擊“掃描設(shè)備”按鈕后再執(zhí)行權(quán)限檢查和申請(qǐng)流程。解釋必要性在請(qǐng)求權(quán)限前尤其是BLUETOOTH_SCAN和位置權(quán)限用一個(gè)簡(jiǎn)單的對(duì)話框或界面文字向用戶(hù)解釋“我們需要掃描附近藍(lán)牙設(shè)備的權(quán)限以便為您連接智能音箱/手環(huán)?！?這能顯著提高授權(quán)率。處理“不再詢(xún)問(wèn)”如果用戶(hù)拒絕了權(quán)限并勾選了“不再詢(xún)問(wèn)”下次shouldShowRequestPermissionRationale()會(huì)返回false。此時(shí)你應(yīng)該引導(dǎo)用戶(hù)前往系統(tǒng)設(shè)置頁(yè)面手動(dòng)開(kāi)啟權(quán)限。提供一個(gè)清晰的指引按鈕和說(shuō)明文字。5.3 兼容舊版本Android的優(yōu)雅處理你的應(yīng)用可能需要支持Android 11甚至更早的版本。權(quán)限代碼需要做良好的分支處理。private fun checkPermissions(): ListString { val neededPermissions mutableListOfString() if (Build.VERSION.SDK_INT Build.VERSION_CODES.S) { // Android 12 if (!hasPermission(Manifest.permission.BLUETOOTH_SCAN)) { neededPermissions.add(Manifest.permission.BLUETOOTH_SCAN) } if (!hasPermission(Manifest.permission.BLUETOOTH_CONNECT)) { neededPermissions.add(Manifest.permission.BLUETOOTH_CONNECT) } // 注意在聲明了 neverForLocation 后可以不主動(dòng)請(qǐng)求位置權(quán)限 // 但如果功能需要RSSI則仍需檢查并請(qǐng)求 // if (needLocationForScan !hasPermission(Manifest.permission.ACCESS_FINE_LOCATION)) { // neededPermissions.add(Manifest.permission.ACCESS_FINE_LOCATION) // } } else { // Android 6.0 - 11 if (!hasPermission(Manifest.permission.ACCESS_FINE_LOCATION)) { neededPermissions.add(Manifest.permission.ACCESS_FINE_LOCATION) } // Android 12以下BLUETOOTH 和 BLUETOOTH_ADMIN 是普通權(quán)限無(wú)需運(yùn)行時(shí)申請(qǐng) // 但需要在 Manifest 中聲明 } return neededPermissions } private fun hasPermission(permission: String): Boolean { return ContextCompat.checkSelfPermission(this, permission) PackageManager.PERMISSION_GRANTED }這種結(jié)構(gòu)清晰的版本判斷使得權(quán)限邏輯一目了然便于維護(hù)。5.4 測(cè)試策略藍(lán)牙開(kāi)發(fā)測(cè)試至關(guān)重要。準(zhǔn)備多版本測(cè)試機(jī)至少準(zhǔn)備一臺(tái)Android 12和一臺(tái)Android 11的設(shè)備進(jìn)行測(cè)試。模擬權(quán)限拒絕場(chǎng)景在開(kāi)發(fā)者選項(xiàng)中可以手動(dòng)撤銷(xiāo)應(yīng)用的具體權(quán)限測(cè)試應(yīng)用在權(quán)限缺失時(shí)的表現(xiàn)是否崩潰以及引導(dǎo)用戶(hù)開(kāi)啟權(quán)限的流程是否順暢。使用模擬器謹(jǐn)慎Android模擬器對(duì)藍(lán)牙的支持有限尤其是低功耗藍(lán)牙。大部分模擬器無(wú)法模擬真實(shí)的藍(lán)牙掃描。真機(jī)測(cè)試是唯一可靠的方式。日志是朋友養(yǎng)成在關(guān)鍵節(jié)點(diǎn)如權(quán)限檢查前后、掃描開(kāi)始/停止、回調(diào)觸發(fā)時(shí)打Log的習(xí)慣并熟練使用adb logcat查看系統(tǒng)藍(lán)牙日志。這是定位疑難雜癥的最強(qiáng)武器。我在實(shí)際項(xiàng)目中正是通過(guò)系統(tǒng)日志發(fā)現(xiàn)了一條關(guān)鍵的Permission denial for startLeScan日志才最終鎖定是Android 12上新權(quán)限模型導(dǎo)致的問(wèn)題。從那時(shí)起我就把權(quán)限檢查和適配作為藍(lán)牙功能開(kāi)發(fā)的第一步再也沒(méi)在這個(gè)坑里摔倒過(guò)。藍(lán)牙開(kāi)發(fā)本身就有很多坑從協(xié)議到硬件兼容性權(quán)限問(wèn)題只是第一道關(guān)卡但跨過(guò)它你的應(yīng)用才算是拿到了入場(chǎng)券。希望這篇詳細(xì)的筆記能幫你節(jié)省大量排查時(shí)間。