簡(jiǎn)介面向 Android 開(kāi)發(fā)者的「掃描 WiFi 二維碼自動(dòng)連接」實(shí)戰(zhàn)項(xiàng)目聚焦掃碼解析網(wǎng)絡(luò)信息并完成配網(wǎng)的需求適合具備基礎(chǔ)組件與權(quán)限知識(shí)、希望理解 WifiManager 連接流程的開(kāi)發(fā)者參考。壓縮包共 141 個(gè)文件約 2.16MB以 41 個(gè) class、20 個(gè) java 源碼和 13 個(gè) xml 配置為主另含 png 界面素材、jar 依賴(lài)及可運(yùn)行 apk 等兼顧源碼、資源與演示產(chǎn)物。已有 2015 人學(xué)習(xí)下載。內(nèi)容圍繞二維碼掃描、SSID 與密碼及加密類(lèi)型解析、WifiConfiguration 構(gòu)建、addNetwork 與 connect 調(diào)用以及 WiFi 狀態(tài)與修改權(quán)限處理展開(kāi)并涉及連接結(jié)果提示和失敗場(chǎng)景反饋。借助現(xiàn)成工程可對(duì)照理解相機(jī)掃碼、配置保存和自動(dòng)連接鏈路定位權(quán)限申請(qǐng)、網(wǎng)絡(luò)添加與兼容性排錯(cuò)思路。1. 掃一掃就連上二維碼里裝的是什么誰(shuí)在替你完成連接門(mén)店換了路由器墻上那張二維碼得重打客人問(wèn)“掃這個(gè)能連嗎”你說(shuō)能結(jié)果他掃出來(lái)只看到一段WIFI:S:Shop-5G;T:WPA;P:abc12345;;的純文本復(fù)制粘貼到設(shè)置里還提示“密碼錯(cuò)誤”——這是最典型的一次翻車(chē)。掃碼連 WiFi 這件事真正的難點(diǎn)從來(lái)不在“掃碼”而在掃碼之后識(shí)別出的字符串怎么拆、拆出來(lái)的密碼怎么轉(zhuǎn)義還原、不同 Android 版本該走哪套連接 API。多數(shù)“掃了個(gè)寂寞”的案例都是這三步里至少斷了一環(huán)。這篇拆的是一份 Android 端的 WiFi 二維碼掃描自動(dòng)連接實(shí)現(xiàn)。它的能力邊界很清楚相機(jī)取幀識(shí)別二維碼解析出 SSID 和密碼然后按系統(tǒng)版本降級(jí)到WifiConfiguration或升級(jí)到WifiNetworkSpecifier把用戶從“打開(kāi)設(shè)置、找網(wǎng)絡(luò)、輸密碼”里解放出來(lái)。適合誰(shuí)做門(mén)店/會(huì)議室/展臺(tái)的一線開(kāi)發(fā)做設(shè)備配網(wǎng)的工具類(lèi) App 開(kāi)發(fā)以及要給客戶演示“一貼即連”卻總被吐槽連不上的那些人。新手能照著步驟跑通熟手能在這里看到 Android 10 之后那些不寫(xiě)在文檔首頁(yè)的限制。2.WIFI:串拆解六個(gè)字段、一次轉(zhuǎn)義和一段必須自己寫(xiě)的狀態(tài)機(jī)二維碼里那串東西不是隨便定出來(lái)的它有一個(gè)被各家相機(jī) App 和系統(tǒng)設(shè)置共同沿用的約定格式以WIFI:開(kāi)頭后面是一串用分號(hào)分隔的鍵:值對(duì)結(jié)尾再用一個(gè)分號(hào)收掉。看起來(lái)像 key-value實(shí)際上它比 key-value 難纏——因?yàn)橹道锟梢院戏ǖ爻霈F(xiàn)冒號(hào)、分號(hào)、逗號(hào)和雙引號(hào)靠split(;)硬切必然出事。這一章先把格式吃透再寫(xiě)解析器最后反過(guò)來(lái)講生成端最容易踩的轉(zhuǎn)義坑。2.1 六個(gè)字段與一張反斜杠轉(zhuǎn)義表字段名都是單字母最常用的只有四個(gè)鍵含義示例備注T認(rèn)證類(lèi)型WPA/WEP/nopass/SAE/WPA2-EAP省略時(shí)按nopass兜底SSSIDShop-5G中文 SSID 走 UTF-8別用 GBKP密碼abc12345nopass時(shí)不存在該字段H是否隱藏網(wǎng)絡(luò)true不寫(xiě)就是falseE/I/A/PH2企業(yè)級(jí)認(rèn)證相關(guān)PEAP/user/anon/MSCHAPV2個(gè)人場(chǎng)景基本用不到轉(zhuǎn)義規(guī)則只有一條但很多人不寫(xiě)\、;、,、:、這五個(gè)字符出現(xiàn)在值里時(shí)前面必須加一個(gè)反斜杠。比如 SSID 叫Coffee;Bar寫(xiě)成二維碼就是WIFI:S:Coffee\;Bar;T:WPA;P:12345678;;。如果生成端漏了這一步解析端就會(huì)在分號(hào)處截?cái)郤SID 變成Coffee剩下Bar被當(dāng)成一個(gè)沒(méi)有冒號(hào)的野字段丟掉——現(xiàn)象就是“掃出來(lái)連上了但連的是隔壁那個(gè)叫 Coffee 的網(wǎng)絡(luò)”。還有一個(gè)容易忽略的點(diǎn)T的值大小寫(xiě)不敏感但S和P是大小寫(xiě)敏感的密碼里的大寫(xiě)字母不能被任何環(huán)節(jié)規(guī)范化。我見(jiàn)過(guò)一個(gè)實(shí)現(xiàn)為了“容錯(cuò)”把整串轉(zhuǎn)成小寫(xiě)再解析結(jié)果所有含大寫(xiě)字母的密碼全線崩盤(pán)排查了一下午才發(fā)現(xiàn)是lowercase()寫(xiě)在了parse的第一行。2.2 解析器不要用 split寫(xiě)個(gè)四十行的狀態(tài)機(jī)先把最容易翻車(chē)的寫(xiě)法貼出來(lái)不是讓你抄是讓你認(rèn)出來(lái)自己代碼里有沒(méi)有它// 反例看起來(lái)簡(jiǎn)潔實(shí)際把轉(zhuǎn)義吃掉了 val parts raw.substring(5).split(;) val ssid parts.first { it.startsWith(S:) }.substring(2)問(wèn)題有兩個(gè)。第一S:Coffee\;Bar會(huì)被切成S:Coffee\和Bar第二P值里如果出現(xiàn):雖然少見(jiàn)但合法substring(2)之后的處理會(huì)帶上前綴判斷的歧義。正確做法是掃描一遍字符流遇到\就吞掉它并把下一個(gè)字符原樣收進(jìn)當(dāng)前字段遇到;才斷字段。斷完字段后再取第一個(gè)字符當(dāng)鍵、校驗(yàn)第二個(gè)字符是:剩下的一整段做反轉(zhuǎn)義。data class WifiQr( val ssid: String, val password: String?, val type: AuthType, val hidden: Boolean ) enum class AuthType { WPA, WEP, NOPASS, SAE, EAP } object WifiQrParser { private const val PREFIX WIFI: fun parse(raw: String): ResultWifiQr { val text raw.trim() if (!text.startsWith(PREFIX, ignoreCase true)) { return Result.failure(IllegalArgumentException(缺少 WIFI: 前綴)) } val map HashMapChar, String() for (field in splitFields(text.substring(PREFIX.length))) { // 字段形如 S:xxx第一個(gè)字符是鍵第二個(gè)必須是冒號(hào) if (field.length 2 || field[1] ! :) continue map[field[0].uppercaseChar()] unescape(field.substring(2)) } val ssid map[S] if (ssid.isNullOrEmpty()) return Result.failure(IllegalArgumentException(缺少 SSID)) val type when (map[T]?.uppercase()) { null, , NOPASS - AuthType.NOPASS WEP - AuthType.WEP SAE - AuthType.SAE WPA2-EAP, WPA-EAP - AuthType.EAP else - AuthType.WPA } val pwd map[P] if (type ! AuthType.NOPASS pwd.isNullOrEmpty()) { return Result.failure(IllegalArgumentException(加密網(wǎng)絡(luò)缺少密碼)) } return Result.success( WifiQr(ssid, pwd, type, map[H]?.equals(true, true) true) ) } /** 只按未轉(zhuǎn)義的 ; 切分轉(zhuǎn)義序列原樣保留交給 unescape 處理 */ private fun splitFields(body: String): ListString { val out ArrayListString() val sb StringBuilder() var i 0 while (i body.length) { val c body[i] when { c \\ i 1 body.length - { sb.append(c).append(body[i 1]); i 2 } c ; - { out.add(sb.toString()); sb.clear(); i } else - { sb.append(c); i } } } if (sb.isNotEmpty()) out.add(sb.toString()) return out } private fun unescape(s: String): String { val sb StringBuilder(s.length) var i 0 while (i s.length) { if (s[i] \\ i 1 s.length) { sb.append(s[i 1]); i 2 } else { sb.append(s[i]); i } } return sb.toString() } }邏輯上的關(guān)鍵決策是“切分階段不反轉(zhuǎn)義”。如果先 unescape 再 split\;會(huì)退化成;后面的切分就再也分不清哪些分號(hào)是結(jié)構(gòu)分隔、哪些是內(nèi)容。同理取鍵值也不能用indexOf(:)因?yàn)橹道锏?雖然被轉(zhuǎn)義了但已經(jīng)混在字符串里按位置取前兩個(gè)字符才是唯一穩(wěn)的做法。splitFields里遇到\時(shí)同時(shí)把反斜杠和下一個(gè)字符一起塞進(jìn)緩沖區(qū)就是為了讓轉(zhuǎn)義信息多活一會(huì)兒。參數(shù)上只有兩處可調(diào)PREFIX的大小寫(xiě)判斷我用了ignoreCase true因?yàn)榇_實(shí)有生成工具寫(xiě)成wifi:T的映射表里把不認(rèn)識(shí)的值一律兜底為WPA這比報(bào)錯(cuò)友好——很多老路由出的碼T是空的但實(shí)際就是 WPA2。真正該報(bào)錯(cuò)的只有 SSID 缺失和加密網(wǎng)絡(luò)密碼缺失這兩種其余都該容錯(cuò)。2.3 反向生成密碼少一位多半是轉(zhuǎn)義順序?qū)懛戳松啥说目颖冉馕龆烁[蔽因?yàn)樗恰皩?xiě)錯(cuò)了也能出圖只是掃出來(lái)不對(duì)”。最典型的錯(cuò)誤是轉(zhuǎn)義順序必須先把\換成\\再處理其他四個(gè)字符。反過(guò)來(lái)的話你把;變成\;緊接著又把那個(gè)剛加進(jìn)去的\再轉(zhuǎn)義一次變成\\;解析端還原出來(lái)就是\;而不是;。密碼里帶反斜杠的人不多但 SSID 里帶分號(hào)的咖啡店、帶逗號(hào)的餐廳太多了。# 生成端轉(zhuǎn)義順序不能反反斜杠必須第一個(gè)處理 SPECIAL [\\, ;, ,, :, ] def escape(value: str) - str: out value for ch in SPECIAL: out out.replace(ch, \\ ch) return out def build_wifi_qr(ssid: str, password: str , auth: str WPA, hidden: bool False) - str: parts [fT:{auth}, fS:{escape(ssid)}] if auth.upper() ! NOPASS: parts.append(fP:{escape(password)}) if hidden: parts.append(H:true) return WIFI: ;.join(parts) ;;注意SPECIAL里\\排第一這不是隨便排的——str.replace是順序執(zhí)行的先處理反斜杠能保證后續(xù)插入的轉(zhuǎn)義符不會(huì)被二次轉(zhuǎn)義。最后的;;是格式約定每個(gè)字段自帶一個(gè)分號(hào)末尾再補(bǔ)一個(gè)收尾缺了它有些老設(shè)備的解析器會(huì)認(rèn)為串沒(méi)結(jié)束。auth傳nopass時(shí)直接不寫(xiě)P字段而不是寫(xiě)P:空值這兩種在部分系統(tǒng)實(shí)現(xiàn)里行為不同空值可能被當(dāng)成空密碼去嘗試關(guān)聯(lián)結(jié)果是反復(fù)失敗。生成完別急著打印先自己解析一遍做閉環(huán)校驗(yàn)把build_wifi_qr的輸出喂給你 Android 側(cè)那個(gè)parse斷言parse(build(...)).ssid 原 SSID。這條斷言能擋掉八成以上的轉(zhuǎn)義問(wèn)題成本只有五行代碼。3. 掃碼鏈路CameraX 抓幀 ML Kit 出串把識(shí)別率從 60% 拉到 95%二維碼解析再漂亮識(shí)別不出來(lái)等于零。這一段的常見(jiàn)失敗不是“完全掃不到”而是“要舉著手機(jī)對(duì)準(zhǔn)三秒才出結(jié)果”用戶體驗(yàn)上跟壞了沒(méi)區(qū)別。原因是很多人用PreviewView截圖再去解碼或者把ImageAnalysis的分辨率設(shè)成默認(rèn)的 640×480二維碼在畫(huà)面里只占幾十個(gè)像素解碼器自然吃力。3.1 依賴(lài)、權(quán)限與一個(gè)容易漏的 manifest 標(biāo)記依賴(lài)就三塊相機(jī)、分析器、條碼識(shí)別。// build.gradle.kts版本號(hào)以你倉(cāng)庫(kù)里能拉到的最新穩(wěn)定版為準(zhǔn) implementation(androidx.camera:camera-camera2:1.3.4) implementation(androidx.camera:camera-lifecycle:1.3.4) implementation(androidx.camera:camera-view:1.3.4) implementation(com.google.mlkit:barcode-scanning:17.2.0)權(quán)限這塊是 Android 版本差異最集中的地方建議一次性寫(xiě)全靠maxSdkVersion讓系統(tǒng)自己裁剪uses-permission android:nameandroid.permission.CAMERA / uses-permission android:nameandroid.permission.ACCESS_WIFI_STATE / uses-permission android:nameandroid.permission.CHANGE_WIFI_STATE / uses-permission android:nameandroid.permission.ACCESS_NETWORK_STATE / !-- Android 12 及以下WiFi 相關(guān)操作被視為可推斷位置必須給精確定位 -- uses-permission android:nameandroid.permission.ACCESS_FINE_LOCATION android:maxSdkVersion32 / !-- Android 13 起用獨(dú)立權(quán)限聲明 neverForLocation 可免掉定位授權(quán)彈窗 -- uses-permission android:nameandroid.permission.NEARBY_WIFI_DEVICES android:usesPermissionFlagsneverForLocation tools:targetApi33 /neverForLocation這個(gè)標(biāo)記值得單獨(dú)說(shuō)一句。它的語(yǔ)義是“我承諾不用 WiFi 掃描結(jié)果去推斷地理位置”加上之后 Android 13 不會(huì)再要求用戶額外授予定位權(quán)限彈窗從兩次變一次。但代價(jià)是一旦你聲明了它就不能再調(diào)用任何會(huì)被判定為位置推斷的 API比如主動(dòng)掃描周?chē)?AP 列表并上報(bào)。只做“按 SSID 直連”的話完全夠用所以門(mén)店場(chǎng)景我一般都會(huì)加上。反之如果你的 App 還要展示附近可用網(wǎng)絡(luò)列表這個(gè)標(biāo)記就得去掉老老實(shí)實(shí)申請(qǐng)定位。ACCESS_FINE_LOCATION的maxSdkVersion32也不是可選項(xiàng)。Android 12 及以下只要涉及 WiFi 連接系統(tǒng)就要求精確定位權(quán)限給ACCESS_COARSE_LOCATION不夠Android 13 起這個(gè)要求被NEARBY_WIFI_DEVICES接管舊的定位權(quán)限反而變成冗余。兩條并存、靠版本裁剪是唯一不用寫(xiě)版本分支的寫(xiě)法。3.2 用 ImageAnalysis 抓幀別用 Preview 截圖PreviewView的bitmap是給用戶看的經(jīng)過(guò)了縮放和裁切拿去解碼等于自己給自己降分辨率。正確路徑是ImageAnalysis拿到ImageProxy轉(zhuǎn)InputImage直接喂給識(shí)別器。分辨率選擇器我一般顯式設(shè)成 1280×720再高解碼耗時(shí)上去了再低小碼識(shí)別不了。private val cameraExecutor Executors.newSingleThreadExecutor() private var lastRaw: String? null private var lastTime 0L private fun startScanner(lifecycleOwner: LifecycleOwner, previewView: PreviewView) { val analyzer ImageAnalysis.Builder() .setBackpressureStrategy(ImageAnalysis.STRATEGY_KEEP_ONLY_LATEST) .setResolutionSelector( ResolutionSelector.Builder() .setResolutionStrategy( ResolutionStrategy( Size(1280, 720), ResolutionStrategy.FALLBACK_RULE_CLOSEST_HIGHER_THEN_LOWER ) ).build() ) .build() val scanner BarcodeScanning.getClient( BarcodeScannerOptions.Builder() .setBarcodeFormats(Barcode.FORMAT_QR_CODE) .build() ) analyzer.setAnalyzer(cameraExecutor) { proxy - val media proxy.image if (media null) { proxy.close(); returnsetAnalyzer } val input InputImage.fromMediaImage(media, proxy.imageInfo.rotationDegrees) scanner.process(input) .addOnSuccessListener { codes - val raw codes.firstOrNull()?.rawValue ?: returnaddOnSuccessListener val now SystemClock.elapsedRealtime() // 同一張碼 2 秒內(nèi)只處理一次避免連續(xù)回調(diào)把連接請(qǐng)求打爆 if (raw lastRaw now - lastTime 2000) returnaddOnSuccessListener lastRaw raw lastTime now onQrDecoded(raw) } .addOnCompleteListener { proxy.close() } } val provider ProcessCameraProvider.getInstance(previewView.context) provider.addListener({ val cameraProvider provider.get() val preview Preview.Builder().build() preview.setSurfaceProvider(previewView.surfaceProvider) cameraProvider.unbindAll() cameraProvider.bindToLifecycle( lifecycleOwner, CameraSelector.DEFAULT_BACK_CAMERA, preview, analyzer ) }, ContextCompat.getMainExecutor(previewView.context)) }幾個(gè)參數(shù)值得掰開(kāi)說(shuō)。STRATEGY_KEEP_ONLY_LATEST是必須的默認(rèn)的KEEP_ONLY_LATEST在識(shí)別器處理不過(guò)來(lái)時(shí)會(huì)積壓幀表現(xiàn)為“畫(huà)面在動(dòng)但結(jié)果延遲兩秒”設(shè)成只保留最新幀后識(shí)別永遠(yuǎn)跟著當(dāng)前畫(huà)面走。FALLBACK_RULE_CLOSEST_HIGHER_THEN_LOWER表示優(yōu)先挑不低于 720p 的檔位挑不到再往下降比精確匹配穩(wěn)因?yàn)椴煌瑱C(jī)型支持的預(yù)覽尺寸差異很大。proxy.close()的位置是另一個(gè)血淚點(diǎn)。ImageProxy是有數(shù)量上限的緩沖區(qū)你不關(guān)它幾幀之后分析器就再也不回調(diào)了現(xiàn)象是“第一次能掃之后就死了”。上面代碼把它放在addOnCompleteListener里保證成功失敗都會(huì)釋放。lastRaw那個(gè)去重也必要識(shí)別器一秒能回調(diào)十幾次不去重的話連接請(qǐng)求會(huì)被連續(xù)觸發(fā)WifiNetworkSpecifier那邊會(huì)直接拋“已有請(qǐng)求在進(jìn)行中”。3.3 從 Barcode 到 WifiQr中間加一層容錯(cuò)拿到rawValue之后不要直接扔給parse中間隔一層處理更穩(wěn)。真實(shí)場(chǎng)景里二維碼可能是從別的工具導(dǎo)出的前綴寫(xiě)成WIFI:也可能寫(xiě)成wifi:末尾可能少分號(hào)SSID 前后可能帶空格。我一般做三件事trim()去掉首尾空白、大小寫(xiě)不敏感地校驗(yàn)前綴、解析失敗時(shí)用寬松模式再試一次比如把沒(méi)有T字段的直接當(dāng) WPA 處理。private fun onQrDecoded(raw: String) { val result WifiQrParser.parse(raw) if (result.isSuccess) { val qr result.getOrThrow() // 交給下一章的連接分派邏輯 connect(qr) } else { // 明確告訴用戶是哪一步失敗而不是籠統(tǒng)的“二維碼無(wú)效” showError(result.exceptionOrNull()?.message ?: 無(wú)法識(shí)別的二維碼) } }這層的價(jià)值體現(xiàn)在錯(cuò)誤提示上。解析失敗的原因就那么幾種前綴不對(duì)、沒(méi)有 SSID、加密網(wǎng)絡(luò)沒(méi)密碼。把它們分別提示出來(lái)用戶才知道是“掃錯(cuò)碼了”還是“這張碼印壞了”?；\統(tǒng)地報(bào)“二維碼無(wú)效”用戶唯一能做的就是再掃一次然后你收到第二條同樣的日志。4. 連接鏈路Android 10 這道分水嶺兩套 API 與三條權(quán)限鏈到這一步SSID 和密碼都在手上了剩下的看起來(lái)只是“調(diào)個(gè) API”。但 Android 10API 29把舊的WifiManager.addNetwork標(biāo)記為廢棄并收緊了權(quán)限同一個(gè)功能從此分裂成兩條完全不同的實(shí)現(xiàn)路徑。更麻煩的是新路徑還分叉成兩個(gè)語(yǔ)義不同的 APIWifiNetworkSpecifier是臨時(shí)的、應(yīng)用級(jí)的、退到后臺(tái)可能斷WifiNetworkSuggestion是持久的、系統(tǒng)級(jí)的、需要用戶點(diǎn)一次通知同意。選錯(cuò)了不是連不上是“連上了但過(guò)一會(huì)兒自己斷了”這種問(wèn)題最難解釋。4.1 API 29 以下WifiConfiguration 直連注意引號(hào)老路徑繞不開(kāi)WifiConfiguration它的字段賦值有幾個(gè)格式要求寫(xiě)錯(cuò)了addNetwork直接返回 -1。Suppress(DEPRECATION) fun connectLegacy(wifiManager: WifiManager, qr: WifiQr): Boolean { val config WifiConfiguration().apply { // SSID 與密碼必須帶雙引號(hào)包裹這是 WifiConfiguration 的格式要求 SSID \${qr.ssid}\ hiddenSSID qr.hidden when (qr.type) { AuthType.NOPASS - { allowedKeyManagement.set(WifiConfiguration.KeyMgmt.NONE) } AuthType.WEP - { allowedKeyManagement.set(WifiConfiguration.KeyMgmt.NONE) allowedAuthAlgorithms.set(WifiConfiguration.AuthAlgorithm.OPEN) allowedAuthAlgorithms.set(WifiConfiguration.AuthAlgorithm.SHARED) wepKeys[0] \${qr.password}\ wepTxKeyIndex 0 } else - { allowedKeyManagement.set(WifiConfiguration.KeyMgmt.WPA_PSK) preSharedKey \${qr.password}\ } } } val netId wifiManager.addNetwork(config) if (netId -1) return false wifiManager.disconnect() val enabled wifiManager.enableNetwork(netId, true) return enabled wifiManager.reconnect() }三個(gè)參數(shù)細(xì)節(jié)。第一SSID和preSharedKey的雙引號(hào)是硬性要求少了的話系統(tǒng)會(huì)把它當(dāng)成十六進(jìn)制原始的寫(xiě)法去解析返回 -1 且沒(méi)有任何錯(cuò)誤信息這是最容易卡住新手的地方。第二enableNetwork(netId, true)第二個(gè)參數(shù)是attemptConnect必須傳true傳false只是把網(wǎng)絡(luò)標(biāo)記為可用但不主動(dòng)連。第三先disconnect()再enableNetwork再reconnect()這個(gè)順序不是玄學(xué)某些定制 ROM 上如果不先斷開(kāi)新網(wǎng)絡(luò)會(huì)一直處于“已保存但未連接”的狀態(tài)。還需要注意addNetwork的返回值語(yǔ)義它返回的是系統(tǒng)分配的netId同一個(gè) SSID 且密碼相同的情況下重復(fù)調(diào)用會(huì)返回同一個(gè) ID冪等但密碼變了會(huì)新建一條配置舊的那條還留著。做門(mén)店應(yīng)用的話連上之后我一般會(huì)順手把除當(dāng)前netId之外的舊配置removeNetwork掉否則配置文件越積越多用戶下次手動(dòng)進(jìn)設(shè)置會(huì)看到一堆重名網(wǎng)絡(luò)體驗(yàn)很糟。4.2 API 29 及以上Specifier 管當(dāng)下Suggestion 管長(zhǎng)期新路徑的兩個(gè) API 語(yǔ)義完全不同選錯(cuò)就是線上事故。WifiNetworkSpecifier配合ConnectivityManager.requestNetwork使用特點(diǎn)是會(huì)彈出系統(tǒng)選擇框讓用戶確認(rèn)、連接是應(yīng)用級(jí)的、App 進(jìn)程退到后臺(tái)或銷(xiāo)毀時(shí)網(wǎng)絡(luò)會(huì)被回收、不需要用戶去系統(tǒng)設(shè)置里操作。它適合“掃完碼馬上要用一下”的場(chǎng)景比如掃碼后立刻打開(kāi)一個(gè)局域網(wǎng)配置頁(yè)面。RequiresApi(Build.VERSION_CODES.Q) fun connectWithSpecifier(context: Context, qr: WifiQr) { val specifier WifiNetworkSpecifier.Builder() .setSsid(qr.ssid) .apply { when (qr.type) { AuthType.NOPASS - Unit AuthType.WEP - setWepKey(qr.password!!) AuthType.SAE - setWpa3Passphrase(qr.password!!) else - setWpa2Passphrase(qr.password!!) } } .build() val request NetworkRequest.Builder() .addTransportType(NetworkCapabilities.TRANSPORT_WIFI) // 關(guān)鍵移除 INTERNET 能力避免系統(tǒng)對(duì)這個(gè)網(wǎng)絡(luò)做連通性校驗(yàn) .removeCapability(NetworkCapabilities.NET_CAPABILITY_INTERNET) .setNetworkSpecifier(specifier) .build() val cm context.getSystemService(ConnectivityManager::class.java) cm.requestNetwork(request, object : ConnectivityManager.NetworkCallback() { override fun onAvailable(network: Network) { // 需要把業(yè)務(wù)流量綁到這個(gè)網(wǎng)絡(luò)上否則仍走默認(rèn)網(wǎng)絡(luò) cm.bindProcessToNetwork(network) } override fun onUnavailable() { // 用戶點(diǎn)了取消或密碼錯(cuò)誤 } override fun onLost(network: Network) { cm.bindProcessToNetwork(null) } }) }removeCapability(NET_CAPABILITY_INTERNET)這行是整個(gè)方法里最值得抄的一行。加上它系統(tǒng)不會(huì)對(duì)這個(gè) WiFi 做“是否能訪問(wèn)公網(wǎng)”的探測(cè)也就不會(huì)彈出那個(gè)“此網(wǎng)絡(luò)無(wú)法訪問(wèn)互聯(lián)網(wǎng)是否保持連接”的二次確認(rèn)。門(mén)店的 WiFi 很多是內(nèi)網(wǎng)、沒(méi)有外網(wǎng)出口不加這行的話用戶會(huì)被多問(wèn)一次很多人就在這里點(diǎn)了“否”然后反饋“你們這個(gè)掃碼連不上”。bindProcessToNetwork也不能省。requestNetwork只是“建立”了連接你的 App 默認(rèn)流量還是走原來(lái)的網(wǎng)絡(luò)可能是移動(dòng)數(shù)據(jù)。不綁的話你以為連上了 WiFi實(shí)際請(qǐng)求還是從 4G 出去的訪問(wèn)局域網(wǎng) IP 自然全超時(shí)。WifiNetworkSuggestion則是另一套邏輯RequiresApi(Build.VERSION_CODES.Q) fun suggestNetwork(context: Context, qr: WifiQr): Int { val suggestion WifiNetworkSuggestion.Builder() .setSsid(qr.ssid) .apply { when (qr.type) { AuthType.NOPASS - Unit AuthType.SAE - setWpa3Passphrase(qr.password!!) else - setWpa2Passphrase(qr.password!!) } } .setIsHiddenSsid(qr.hidden) .build() return context.getSystemService(WifiManager::class.java) .addNetworkSuggestions(listOf(suggestion)) }它不會(huì)立刻建立連接而是把這張網(wǎng)絡(luò)“推薦”給系統(tǒng)用戶會(huì)在通知欄收到一條“某應(yīng)用想要連接到 xxx”的提示同意之后系統(tǒng)就會(huì)像對(duì)待自己保存的網(wǎng)絡(luò)一樣自動(dòng)連接。返回值是STATUS_NETWORK_SUGGESTIONS_SUCCESS之類(lèi)的狀態(tài)碼注意它只代表“建議已提交”不代表“用戶已同意”真正的連接結(jié)果要靠監(jiān)聽(tīng)ACTION_WIFI_NETWORK_SUGGESTION_POST_CONNECTION廣播。所以選型結(jié)論很清楚掃碼后馬上就要用網(wǎng)絡(luò)配網(wǎng)、局域網(wǎng)控制——用WifiNetworkSpecifier希望用戶下次來(lái)門(mén)店自動(dòng)連上——用WifiNetworkSuggestion。兩個(gè)都要的話就都調(diào)先 specifier 保當(dāng)下再 suggestion 保下次。4.3 權(quán)限與版本分派一張表把分支寫(xiě)清楚運(yùn)行時(shí)權(quán)限的申請(qǐng)順序也有講究。相機(jī)權(quán)限和 WiFi 權(quán)限不要一次性全申請(qǐng)用戶看到連著彈三個(gè)框會(huì)直接拒絕。我的做法是進(jìn)頁(yè)面先要相機(jī)掃到碼之后再要 WiFi 相關(guān)權(quán)限這樣用戶的理解鏈路是連貫的——“我要掃碼” → “掃到了現(xiàn)在要連網(wǎng)”。版本分派寫(xiě)成表更清楚系統(tǒng)版本連接 API必須權(quán)限用戶交互≤ API 28WifiConfigurationenableNetworkCHANGE_WIFI_STATE、ACCESS_FINE_LOCATION無(wú)彈窗直接連API 29–32WifiNetworkSpecifierACCESS_FINE_LOCATION、ACCESS_NETWORK_STATE系統(tǒng)選擇框 可能的“無(wú)互聯(lián)網(wǎng)”確認(rèn)API 29–32WifiNetworkSuggestionACCESS_FINE_LOCATION、CHANGE_WIFI_STATE通知欄同意API 33同上兩者NEARBY_WIFI_DEVICES帶neverForLocation同上分派代碼本身很短但要用Build.VERSION.SDK_INT卡在 29而不是 30 或 31——WifiNetworkSpecifier是 29 引入的卡錯(cuò)版本會(huì)在 Android 10 設(shè)備上走到廢棄分支然后靜默失敗。fun connect(qr: WifiQr) { if (Build.VERSION.SDK_INT Build.VERSION_CODES.Q) { connectWithSpecifier(appContext, qr) // 順手提交一條持久化建議下次進(jìn)店免掃碼 if (qr.password ! null) suggestNetwork(appContext, qr) } else { val wm appContext.getSystemService(WifiManager::class.java) connectLegacy(wm, qr) } }一個(gè)額外提醒WifiNetworkSpecifier在同一時(shí)刻只能有一個(gè)活躍請(qǐng)求。用戶連掃兩張不同的碼第二個(gè)requestNetwork會(huì)拋IllegalStateException。所以調(diào)用前必須先unregisterNetworkCallback掉上一個(gè)或者用一個(gè)布爾量擋住重復(fù)點(diǎn)擊。這個(gè)異常在文檔里寫(xiě)得很輕線上卻是高頻崩潰點(diǎn)。5. 避坑排查五類(lèi)掃描后連不上的現(xiàn)場(chǎng)復(fù)盤(pán)前面四章講的是“應(yīng)該怎么寫(xiě)”這一章講“寫(xiě)完為什么還是不通”。下面五條都是我在真機(jī)上反復(fù)遇到過(guò)的按“現(xiàn)象 → 原因 → 解決”記每條都對(duì)應(yīng)一個(gè)具體的日志特征方便你對(duì)照自己的現(xiàn)場(chǎng)。5.1 現(xiàn)象掃出來(lái)了提示密碼錯(cuò)誤但密碼肉眼看著沒(méi)錯(cuò)原因基本鎖定在轉(zhuǎn)義還原。生成端把;、,、:、轉(zhuǎn)義了解析端卻沒(méi)還原導(dǎo)致傳給系統(tǒng)的密碼里還帶著反斜杠abc\;123被當(dāng)成密碼去認(rèn)證當(dāng)然失敗。還有一種變體解析端做了一次unescape連接層又做了一次\\被還原成\之后又被當(dāng)成轉(zhuǎn)義符吃掉一個(gè)字符密碼少一位。解決在parse返回之前打一條日志把最終password的長(zhǎng)度和hashCode打出來(lái)跟生成端對(duì)比。長(zhǎng)度對(duì)不上就是轉(zhuǎn)義問(wèn)題長(zhǎng)度對(duì)得上但連不上就是加密類(lèi)型判斷錯(cuò)了。我現(xiàn)在的習(xí)慣是parse方法里常駐一行Log.d(WifiQr, ssid${ssid.length} pwdLen${password?.length})不為別的就為了這種時(shí)候不用改代碼重打包。5.2 現(xiàn)象addNetwork一直返回 -1沒(méi)有任何報(bào)錯(cuò)在 API 28 及以下的機(jī)型上addNetwork返回 -1 最常見(jiàn)的原因是 SSID 或密碼沒(méi)加雙引號(hào)。WifiConfiguration.SSID期望的是帶引號(hào)的字面量你直接塞Shop-5G系統(tǒng)會(huì)嘗試按十六進(jìn)制解析解析失敗就返回 -1日志里連個(gè) warning 都沒(méi)有堪稱(chēng)黑匣子。解決SSID \${qr.ssid}\preSharedKey \${qr.password}\兩個(gè)都要。另外檢查allowedKeyManagement有沒(méi)有設(shè)置只填preSharedKey不設(shè)WPA_PSK同樣返回 -1。這兩條占了我早期踩坑記錄的絕大部分。5.3 現(xiàn)象Android 10 上彈窗點(diǎn)了“連接”然后什么也沒(méi)發(fā)生requestNetwork的回調(diào)有三個(gè)onAvailable、onUnavailable、onLost。很多人只處理了onAvailable用戶點(diǎn)取消走onUnavailable代碼里靜默無(wú)聲界面就卡在那里。更隱蔽的一種是onAvailable觸發(fā)了但業(yè)務(wù)請(qǐng)求還是超時(shí)——因?yàn)闆](méi)調(diào)bindProcessToNetwork流量仍然走默認(rèn)網(wǎng)絡(luò)。解決三個(gè)回調(diào)全實(shí)現(xiàn)onUnavailable里給明確提示“已取消或密碼錯(cuò)誤”onAvailable里立刻bindProcessToNetwork(network)onLost里置回null。驗(yàn)證方法是連上之后訪問(wèn)一個(gè)局域網(wǎng)內(nèi)的固定 IP能通才說(shuō)明綁定生效。用公網(wǎng)地址驗(yàn)證是無(wú)效的因?yàn)楣W(wǎng)走哪條路都能通。5.4 現(xiàn)象連著連著網(wǎng)斷了尤其是切到后臺(tái)再回來(lái)WifiNetworkSpecifier建立的連接生命周期綁在發(fā)起請(qǐng)求的進(jìn)程上。App 退到后臺(tái)被系統(tǒng)回收、或者用戶手動(dòng)劃掉網(wǎng)絡(luò)就會(huì)被移除。這不是 bug是設(shè)計(jì)如此。把它當(dāng)“臨時(shí)連接”用沒(méi)問(wèn)題當(dāng)“連上就一直在”用必然翻車(chē)。解決需要長(zhǎng)期保持的場(chǎng)景改用WifiNetworkSuggestion讓系統(tǒng)接管這條網(wǎng)絡(luò)的生命周期。如果兩個(gè)都要就在 specifier 連上之后再提交一次 suggestion用戶同意之后下次就由系統(tǒng)自動(dòng)連不再依賴(lài)你的進(jìn)程。這里有個(gè)細(xì)節(jié)suggestion 提交后用戶沒(méi)點(diǎn)同意的話那條通知會(huì)一直掛著所以提交時(shí)機(jī)最好放在“用戶已經(jīng)成功連上一次”之后轉(zhuǎn)化率會(huì)高很多。5.5 現(xiàn)象部分機(jī)型掃得飛快部分機(jī)型死活掃不出來(lái)同一張碼某廠商 Android 13 的機(jī)器一秒出結(jié)果另一臺(tái) Android 11 的機(jī)器舉十秒都沒(méi)反應(yīng)。原因通常是相機(jī)分辨率協(xié)商失敗——ResolutionSelector請(qǐng)求 1280×720但該機(jī)型不支持這個(gè)預(yù)覽尺寸組合回退到了 640×480二維碼在畫(huà)面里像素太少。另一種可能是該機(jī)型的ImageAnalysis默認(rèn)走了 YUV_420_888 之外的格式InputImage.fromMediaImage轉(zhuǎn)換失敗process一直不回調(diào)。解決ImageAnalysis.Builder().setOutputImageFormat(ImageAnalysis.OUTPUT_IMAGE_FORMAT_YUV_420_888)顯式指定格式兼容性最好。分辨率那邊把回退規(guī)則設(shè)成FALLBACK_RULE_CLOSEST_HIGHER_THEN_LOWER之外再加一層兜底連續(xù) 5 秒沒(méi)有識(shí)別結(jié)果就主動(dòng)unbindAll后用 1920×1080 重試一次。這個(gè)“重試一次”的邏輯聽(tīng)著土但在中低端機(jī)型上救回過(guò)好幾個(gè)現(xiàn)場(chǎng)。6. 生成端與自檢自己造碼、批量回連把兼容性驗(yàn)證做成流水線真機(jī)兼容性這件事靠手動(dòng)一臺(tái)臺(tái)試是撐不住的。我的做法是把驗(yàn)證拆成兩段先在生成端造一批“故意刁難”的碼再在連接端跑一遍自動(dòng)化回連把兼容性問(wèn)題在發(fā)版前逼出來(lái)。6.1 造一批邊界碼把轉(zhuǎn)義和長(zhǎng)度全覆蓋正常碼誰(shuí)都能過(guò)邊界碼才是照妖鏡。我一般固定造這么一組SSID 含分號(hào)、SSID 含中文、SSID 正好 32 字節(jié)、密碼含反斜杠和雙引號(hào)、密碼 8 位與 63 位各一、無(wú)密碼開(kāi)放網(wǎng)絡(luò)、隱藏網(wǎng)絡(luò)。用第 2 章那個(gè)build_wifi_qr生成再配qrcode庫(kù)出圖。import qrcode from qr_builder import build_wifi_qr # 第 2 章的生成函數(shù) CASES [ (Normal-2G, 12345678, WPA, False), (Coffee;Bar, pa\\ss\word, WPA, False), # 分號(hào)、反斜杠、雙引號(hào)全覆蓋 (中文網(wǎng)絡(luò)-5G, 12345678, WPA, False), (Open-Guest, , nopass, False), (Hidden-Lab, 12345678, WPA, True), (A * 32, 1 * 63, WPA, False), # SSID 與密碼長(zhǎng)度上限 ] for ssid, pwd, auth, hidden in CASES: payload build_wifi_qr(ssid, pwd, auth, hidden) img qrcode.make(payload) img.save(fqr_{abs(hash(ssid)) % 10000}.png) print(payload)跑完先別急著掃碼做一次閉環(huán)校驗(yàn)把每一條payload喂給你 Kotlin 側(cè)的parse可以把解析邏輯抽成一個(gè)純 JVM 模塊跑單元測(cè)試斷言還原出的ssid和password跟輸入完全一致。這一步能擋掉絕大部分轉(zhuǎn)義錯(cuò)誤而且跑一次只要幾百毫秒比真機(jī)試快兩個(gè)數(shù)量級(jí)。6.2 用 adb 把連接結(jié)果撈出來(lái)別靠肉眼看真機(jī)回連的時(shí)候界面提示“連接成功”并不可信因?yàn)閛nAvailable只代表鏈路建立不代表能通信。我會(huì)用幾條命令做交叉驗(yàn)證# 看當(dāng)前連的是哪個(gè) SSID部分機(jī)型需要 root 或調(diào)試版本 adb shell dumpsys wifi | grep -i mWifiInfo | head -n 3 # 看系統(tǒng)里保存的網(wǎng)絡(luò)建議與其狀態(tài) adb shell dumpsys wifi | grep -i -A2 NetworkSuggestion # 確認(rèn)進(jìn)程綁定的網(wǎng)絡(luò)配合 App 內(nèi)日志一起看 adb shell dumpsys connectivity | grep -i Bound to第一條命令的輸出里能找到當(dāng)前SSID:字段跟你要連的那個(gè)比對(duì)。如果顯示的還是舊網(wǎng)絡(luò)說(shuō)明bindProcessToNetwork沒(méi)生效或者連接壓根沒(méi)建立。第二條用來(lái)確認(rèn) suggestion 是否真的被系統(tǒng)接受——addNetworkSuggestions返回成功只代表提交成功系統(tǒng)側(cè)可能因?yàn)橹貜?fù)提交或策略限制而丟棄。6.3 一個(gè)收尾習(xí)慣把“連不上”的日志字段固定下來(lái)排查這類(lèi)問(wèn)題最耗時(shí)間的不是修復(fù)是復(fù)現(xiàn)。所以我現(xiàn)在每接一個(gè) WiFi 相關(guān)需求都會(huì)在連接失敗的分支里固定打這幾個(gè)字段sdkInt、ssid 長(zhǎng)度、password 長(zhǎng)度、authType、走的分支legacy/specifier/suggestion、回調(diào)名onUnavailable/onLost。這幾項(xiàng)加起來(lái)不到一百字節(jié)但基本能把問(wèn)題定位到具體某一步不用再問(wèn)用戶“你手機(jī)什么系統(tǒng)”。吃過(guò)一次虧某批門(mén)店的 Android 11 設(shè)備反饋“掃碼后彈窗閃一下就沒(méi)了”日志里只有一句籠統(tǒng)的失敗。后來(lái)補(bǔ)上分支標(biāo)記才發(fā)現(xiàn)是WifiNetworkSpecifier拋了IllegalStateException——上一個(gè)請(qǐng)求沒(méi)注銷(xiāo)。加了“先unregisterNetworkCallback再發(fā)新請(qǐng)求”之后同類(lèi)問(wèn)題再?zèng)]出現(xiàn)過(guò)。從那以后我每次發(fā)版前都會(huì)強(qiáng)制走一遍這套邊界碼加 adb 交叉驗(yàn)證的流程寧可多花半小時(shí)也不想再在群里被追著問(wèn)“為什么我這臺(tái)連不上”。希望幫到你。本文還有配套的精品資源點(diǎn)擊獲取