簡(jiǎn)介面向 Android 開發(fā)者的「掃描 WiFi 二維碼自動(dòng)連接」實(shí)戰(zhàn)項(xiàng)目聚焦掃碼解析網(wǎng)絡(luò)信息并完成配網(wǎng)的需求適合具備基礎(chǔ)組件與權(quán)限知識(shí)、希望理解 WifiManager 連接流程的開發(fā)者參考。壓縮包共 141 個(gè)文件約 2.16MB以 41 個(gè) class、20 個(gè) java 源碼和 13 個(gè) xml 配置為主另含 png 界面素材、jar 依賴及可運(yùn)行 apk 等兼顧源碼、資源與演示產(chǎn)物。已有 2015 人學(xué)習(xí)下載。內(nèi)容圍繞二維碼掃描、SSID 與密碼及加密類型解析、WifiConfiguration 構(gòu)建、addNetwork 與 connect 調(diào)用以及 WiFi 狀態(tài)與修改權(quán)限處理展開并涉及連接結(jié)果提示和失敗場(chǎng)景反饋。借助現(xiàn)成工程可對(duì)照理解相機(jī)掃碼、配置保存和自動(dòng)連接鏈路定位權(quán)限申請(qǐng)、網(wǎng)絡(luò)添加與兼容性排錯(cuò)思路。1. 掃一掃就連上二維碼里裝的是什么誰在替你完成連接門店換了路由器墻上那張二維碼得重打客人問“掃這個(gè)能連嗎”你說能結(jié)果他掃出來只看到一段WIFI:S:Shop-5G;T:WPA;P:abc12345;;的純文本復(fù)制粘貼到設(shè)置里還提示“密碼錯(cuò)誤”——這是最典型的一次翻車。掃碼連 WiFi 這件事真正的難點(diǎn)從來不在“掃碼”而在掃碼之后識(shí)別出的字符串怎么拆、拆出來的密碼怎么轉(zhuǎn)義還原、不同 Android 版本該走哪套連接 API。多數(shù)“掃了個(gè)寂寞”的案例都是這三步里至少斷了一環(huán)。這篇拆的是一份 Android 端的 WiFi 二維碼掃描自動(dòng)連接實(shí)現(xiàn)。它的能力邊界很清楚相機(jī)取幀識(shí)別二維碼解析出 SSID 和密碼然后按系統(tǒng)版本降級(jí)到WifiConfiguration或升級(jí)到WifiNetworkSpecifier把用戶從“打開設(shè)置、找網(wǎng)絡(luò)、輸密碼”里解放出來。適合誰做門店/會(huì)議室/展臺(tái)的一線開發(fā)做設(shè)備配網(wǎng)的工具類 App 開發(fā)以及要給客戶演示“一貼即連”卻總被吐槽連不上的那些人。新手能照著步驟跑通熟手能在這里看到 Android 10 之后那些不寫在文檔首頁(yè)的限制。2.WIFI:串拆解六個(gè)字段、一次轉(zhuǎn)義和一段必須自己寫的狀態(tài)機(jī)二維碼里那串東西不是隨便定出來的它有一個(gè)被各家相機(jī) App 和系統(tǒng)設(shè)置共同沿用的約定格式以WIFI:開頭后面是一串用分號(hào)分隔的鍵:值對(duì)結(jié)尾再用一個(gè)分號(hào)收掉?？雌饋硐?key-value實(shí)際上它比 key-value 難纏——因?yàn)橹道锟梢院戏ǖ爻霈F(xiàn)冒號(hào)、分號(hào)、逗號(hào)和雙引號(hào)靠split(;)硬切必然出事。這一章先把格式吃透再寫解析器最后反過來講生成端最容易踩的轉(zhuǎn)義坑。2.1 六個(gè)字段與一張反斜杠轉(zhuǎn)義表字段名都是單字母最常用的只有四個(gè)鍵含義示例備注T認(rèn)證類型WPA/WEP/nopass/SAE/WPA2-EAP省略時(shí)按nopass兜底SSSIDShop-5G中文 SSID 走 UTF-8別用 GBKP密碼abc12345nopass時(shí)不存在該字段H是否隱藏網(wǎng)絡(luò)true不寫就是falseE/I/A/PH2企業(yè)級(jí)認(rèn)證相關(guān)PEAP/user/anon/MSCHAPV2個(gè)人場(chǎng)景基本用不到轉(zhuǎn)義規(guī)則只有一條但很多人不寫\、;、,、:、這五個(gè)字符出現(xiàn)在值里時(shí)前面必須加一個(gè)反斜杠。比如 SSID 叫Coffee;Bar寫成二維碼就是WIFI:S:Coffee\;Bar;T:WPA;P:12345678;;。如果生成端漏了這一步解析端就會(huì)在分號(hào)處截?cái)郤SID 變成Coffee剩下Bar被當(dāng)成一個(gè)沒有冒號(hào)的野字段丟掉——現(xiàn)象就是“掃出來連上了但連的是隔壁那個(gè)叫 Coffee 的網(wǎng)絡(luò)”。還有一個(gè)容易忽略的點(diǎn)T的值大小寫不敏感但S和P是大小寫敏感的密碼里的大寫字母不能被任何環(huán)節(jié)規(guī)范化。我見過一個(gè)實(shí)現(xiàn)為了“容錯(cuò)”把整串轉(zhuǎn)成小寫再解析結(jié)果所有含大寫字母的密碼全線崩盤排查了一下午才發(fā)現(xiàn)是lowercase()寫在了parse的第一行。2.2 解析器不要用 split寫個(gè)四十行的狀態(tài)機(jī)先把最容易翻車的寫法貼出來不是讓你抄是讓你認(rèn)出來自己代碼里有沒有它// 反例看起來簡(jiǎn)潔實(shí)際把轉(zhuǎn)義吃掉了 val parts raw.substring(5).split(;) val ssid parts.first { it.startsWith(S:) }.substring(2)問題有兩個(gè)。第一S:Coffee\;Bar會(huì)被切成S:Coffee\和Bar第二P值里如果出現(xià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的大小寫判斷我用了ignoreCase true因?yàn)榇_實(shí)有生成工具寫成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)樗恰皩戝e(cuò)了也能出圖只是掃出來不對(duì)”。最典型的錯(cuò)誤是轉(zhuǎn)義順序必須先把\換成\\再處理其他四個(gè)字符。反過來的話你把;變成\;緊接著又把那個(gè)剛加進(jìn)去的\再轉(zhuǎn)義一次變成\\;解析端還原出來就是\;而不是;。密碼里帶反斜杠的人不多但 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)為串沒結(jié)束。auth傳nopass時(shí)直接不寫P字段而不是寫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)義問題成本只有五行代碼。3. 掃碼鏈路CameraX 抓幀 ML Kit 出串把識(shí)別率從 60% 拉到 95%二維碼解析再漂亮識(shí)別不出來等于零。這一段的常見失敗不是“完全掃不到”而是“要舉著手機(jī)對(duì)準(zhǔn)三秒才出結(jié)果”用戶體驗(yàn)上跟壞了沒區(qū)別。原因是很多人用PreviewView截圖再去解碼或者把ImageAnalysis的分辨率設(shè)成默認(rèn)的 640×480二維碼在畫面里只占幾十個(gè)像素解碼器自然吃力。3.1 依賴、權(quán)限與一個(gè)容易漏的 manifest 標(biāo)記依賴就三塊相機(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 版本差異最集中的地方建議一次性寫全靠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ú)說一句。它的語義是“我承諾不用 WiFi 掃描結(jié)果去推斷地理位置”加上之后 Android 13 不會(huì)再要求用戶額外授予定位權(quán)限彈窗從兩次變一次。但代價(jià)是一旦你聲明了它就不能再調(diào)用任何會(huì)被判定為位置推斷的 API比如主動(dòng)掃描周圍 AP 列表并上報(bào)。只做“按 SSID 直連”的話完全夠用所以門店場(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)限反而變成冗余。兩條并存、靠版本裁剪是唯一不用寫版本分支的寫法。3.2 用 ImageAnalysis 抓幀別用 Preview 截圖PreviewView的bitmap是給用戶看的經(jīng)過了縮放和裁切拿去解碼等于自己給自己降分辨率。正確路徑是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ù)值得掰開說。STRATEGY_KEEP_ONLY_LATEST是必須的默認(rèn)的KEEP_ONLY_LATEST在識(shí)別器處理不過來時(shí)會(huì)積壓幀表現(xiàn)為“畫面在動(dòng)但結(jié)果延遲兩秒”設(shè)成只保留最新幀后識(shí)別永遠(yuǎn)跟著當(dāng)前畫面走。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)出的前綴寫成WIFI:也可能寫成wifi:末尾可能少分號(hào)SSID 前后可能帶空格。我一般做三件事trim()去掉首尾空白、大小寫不敏感地校驗(yàn)前綴、解析失敗時(shí)用寬松模式再試一次比如把沒有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)的“二維碼無效” showError(result.exceptionOrNull()?.message ?: 無法識(shí)別的二維碼) } }這層的價(jià)值體現(xiàn)在錯(cuò)誤提示上。解析失敗的原因就那么幾種前綴不對(duì)、沒有 SSID、加密網(wǎng)絡(luò)沒密碼。把它們分別提示出來用戶才知道是“掃錯(cuò)碼了”還是“這張碼印壞了”?；\統(tǒng)地報(bào)“二維碼無效”用戶唯一能做的就是再掃一次然后你收到第二條同樣的日志。4. 連接鏈路Android 10 這道分水嶺兩套 API 與三條權(quán)限鏈到這一步SSID 和密碼都在手上了剩下的看起來只是“調(diào)個(gè) API”。但 Android 10API 29把舊的WifiManager.addNetwork標(biāo)記為廢棄并收緊了權(quán)限同一個(gè)功能從此分裂成兩條完全不同的實(shí)現(xiàn)路徑。更麻煩的是新路徑還分叉成兩個(gè)語義不同的 APIWifiNetworkSpecifier是臨時(shí)的、應(yīng)用級(jí)的、退到后臺(tái)可能斷WifiNetworkSuggestion是持久的、系統(tǒng)級(jí)的、需要用戶點(diǎn)一次通知同意。選錯(cuò)了不是連不上是“連上了但過一會(huì)兒自己斷了”這種問題最難解釋。4.1 API 29 以下WifiConfiguration 直連注意引號(hào)老路徑繞不開WifiConfiguration它的字段賦值有幾個(gè)格式要求寫錯(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)制原始的寫法去解析返回 -1 且沒有任何錯(cuò)誤信息這是最容易卡住新手的地方。第二enableNetwork(netId, true)第二個(gè)參數(shù)是attemptConnect必須傳true傳false只是把網(wǎng)絡(luò)標(biāo)記為可用但不主動(dòng)連。第三先disconnect()再enableNetwork再reconnect()這個(gè)順序不是玄學(xué)某些定制 ROM 上如果不先斷開新網(wǎng)絡(luò)會(huì)一直處于“已保存但未連接”的狀態(tài)。還需要注意addNetwork的返回值語義它返回的是系統(tǒng)分配的netId同一個(gè) SSID 且密碼相同的情況下重復(fù)調(diào)用會(huì)返回同一個(gè) ID冪等但密碼變了會(huì)新建一條配置舊的那條還留著。做門店應(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 語義完全不同選錯(cuò)就是線上事故。WifiNetworkSpecifier配合ConnectivityManager.requestNetwork使用特點(diǎn)是會(huì)彈出系統(tǒng)選擇框讓用戶確認(rèn)、連接是應(yīng)用級(jí)的、App 進(jìn)程退到后臺(tái)或銷毀時(shí)網(wǎng)絡(luò)會(huì)被回收、不需要用戶去系統(tǒng)設(shè)置里操作。它適合“掃完碼馬上要用一下”的場(chǎng)景比如掃碼后立刻打開一個(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ǎng)”的探測(cè)也就不會(huì)彈出那個(gè)“此網(wǎng)絡(luò)無法訪問互聯(lián)網(wǎng)是否保持連接”的二次確認(rèn)。門店的 WiFi 很多是內(nèi)網(wǎng)、沒有外網(wǎng)出口不加這行的話用戶會(huì)被多問一次很多人就在這里點(diǎn)了“否”然后反饋“你們這個(gè)掃碼連不上”。bindProcessToNetwork也不能省。requestNetwork只是“建立”了連接你的 App 默認(rèn)流量還是走原來的網(wǎng)絡(luò)可能是移動(dòng)數(shù)據(jù)。不綁的話你以為連上了 WiFi實(shí)際請(qǐng)求還是從 4G 出去的訪問局域網(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之類的狀態(tài)碼注意它只代表“建議已提交”不代表“用戶已同意”真正的連接結(jié)果要靠監(jiān)聽ACTION_WIFI_NETWORK_SUGGESTION_POST_CONNECTION廣播。所以選型結(jié)論很清楚掃碼后馬上就要用網(wǎng)絡(luò)配網(wǎng)、局域網(wǎng)控制——用WifiNetworkSpecifier希望用戶下次來門店自動(dòng)連上——用WifiNetworkSuggestion。兩個(gè)都要的話就都調(diào)先 specifier 保當(dāng)下再 suggestion 保下次。4.3 權(quán)限與版本分派一張表把分支寫清楚運(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)”。版本分派寫成表更清楚系統(tǒng)版本連接 API必須權(quán)限用戶交互≤ API 28WifiConfigurationenableNetworkCHANGE_WIFI_STATE、ACCESS_FINE_LOCATION無彈窗直接連API 29–32WifiNetworkSpecifierACCESS_FINE_LOCATION、ACCESS_NETWORK_STATE系統(tǒng)選擇框 可能的“無互聯(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è)異常在文檔里寫得很輕線上卻是高頻崩潰點(diǎn)。5. 避坑排查五類掃描后連不上的現(xiàn)場(chǎng)復(fù)盤前面四章講的是“應(yīng)該怎么寫”這一章講“寫完為什么還是不通”。下面五條都是我在真機(jī)上反復(fù)遇到過的按“現(xiàn)象 → 原因 → 解決”記每條都對(duì)應(yīng)一個(gè)具體的日志特征方便你對(duì)照自己的現(xiàn)場(chǎng)。5.1 現(xiàn)象掃出來了提示密碼錯(cuò)誤但密碼肉眼看著沒錯(cuò)原因基本鎖定在轉(zhuǎn)義還原。生成端把;、,、:、轉(zhuǎn)義了解析端卻沒還原導(dǎo)致傳給系統(tǒng)的密碼里還帶著反斜杠abc\;123被當(dāng)成密碼去認(rèn)證當(dāng)然失敗。還有一種變體解析端做了一次unescape連接層又做了一次\\被還原成\之后又被當(dāng)成轉(zhuǎn)義符吃掉一個(gè)字符密碼少一位。解決在parse返回之前打一條日志把最終password的長(zhǎng)度和hashCode打出來跟生成端對(duì)比。長(zhǎng)度對(duì)不上就是轉(zhuǎn)義問題長(zhǎng)度對(duì)得上但連不上就是加密類型判斷錯(cuò)了。我現(xiàn)在的習(xí)慣是parse方法里常駐一行Log.d(WifiQr, ssid${ssid.length} pwdLen${password?.length})不為別的就為了這種時(shí)候不用改代碼重打包。5.2 現(xiàn)象addNetwork一直返回 -1沒有任何報(bào)錯(cuò)在 API 28 及以下的機(jī)型上addNetwork返回 -1 最常見的原因是 SSID 或密碼沒加雙引號(hào)。WifiConfiguration.SSID期望的是帶引號(hào)的字面量你直接塞Shop-5G系統(tǒng)會(huì)嘗試按十六進(jìn)制解析解析失敗就返回 -1日志里連個(gè) warning 都沒有堪稱黑匣子。解決SSID \${qr.ssid}\preSharedKey \${qr.password}\兩個(gè)都要。另外檢查allowedKeyManagement有沒有設(shè)置只填preSharedKey不設(shè)WPA_PSK同樣返回 -1。這兩條占了我早期踩坑記錄的絕大部分。5.3 現(xiàn)象Android 10 上彈窗點(diǎn)了“連接”然后什么也沒發(fā)生requestNetwork的回調(diào)有三個(gè)onAvailable、onUnavailable、onLost。很多人只處理了onAvailable用戶點(diǎn)取消走onUnavailable代碼里靜默無聲界面就卡在那里。更隱蔽的一種是onAvailable觸發(fā)了但業(yè)務(wù)請(qǐng)求還是超時(shí)——因?yàn)闆]調(diào)bindProcessToNetwork流量仍然走默認(rèn)網(wǎng)絡(luò)。解決三個(gè)回調(diào)全實(shí)現(xiàn)onUnavailable里給明確提示“已取消或密碼錯(cuò)誤”onAvailable里立刻bindProcessToNetwork(network)onLost里置回null。驗(yàn)證方法是連上之后訪問一個(gè)局域網(wǎng)內(nèi)的固定 IP能通才說明綁定生效。用公網(wǎng)地址驗(yàn)證是無效的因?yàn)楣W(wǎng)走哪條路都能通。5.4 現(xiàn)象連著連著網(wǎng)斷了尤其是切到后臺(tái)再回來WifiNetworkSpecifier建立的連接生命周期綁在發(fā)起請(qǐng)求的進(jìn)程上。App 退到后臺(tái)被系統(tǒng)回收、或者用戶手動(dòng)劃掉網(wǎng)絡(luò)就會(huì)被移除。這不是 bug是設(shè)計(jì)如此。把它當(dāng)“臨時(shí)連接”用沒問題當(dāng)“連上就一直在”用必然翻車。解決需要長(zhǎng)期保持的場(chǎng)景改用WifiNetworkSuggestion讓系統(tǒng)接管這條網(wǎng)絡(luò)的生命周期。如果兩個(gè)都要就在 specifier 連上之后再提交一次 suggestion用戶同意之后下次就由系統(tǒng)自動(dòng)連不再依賴你的進(jìn)程。這里有個(gè)細(xì)節(jié)suggestion 提交后用戶沒點(diǎn)同意的話那條通知會(huì)一直掛著所以提交時(shí)機(jī)最好放在“用戶已經(jīng)成功連上一次”之后轉(zhuǎn)化率會(huì)高很多。5.5 現(xiàn)象部分機(jī)型掃得飛快部分機(jī)型死活掃不出來同一張碼某廠商 Android 13 的機(jī)器一秒出結(jié)果另一臺(tái) Android 11 的機(jī)器舉十秒都沒反應(yīng)。原因通常是相機(jī)分辨率協(xié)商失敗——ResolutionSelector請(qǐng)求 1280×720但該機(jī)型不支持這個(gè)預(yù)覽尺寸組合回退到了 640×480二維碼在畫面里像素太少。另一種可能是該機(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 秒沒有識(shí)別結(jié)果就主動(dòng)unbindAll后用 1920×1080 重試一次。這個(gè)“重試一次”的邏輯聽著土但在中低端機(jī)型上救回過好幾個(gè)現(xiàn)場(chǎng)。6. 生成端與自檢自己造碼、批量回連把兼容性驗(yàn)證做成流水線真機(jī)兼容性這件事靠手動(dòng)一臺(tái)臺(tái)試是撐不住的。我的做法是把驗(yàn)證拆成兩段先在生成端造一批“故意刁難”的碼再在連接端跑一遍自動(dòng)化回連把兼容性問題在發(fā)版前逼出來。6.1 造一批邊界碼把轉(zhuǎn)義和長(zhǎng)度全覆蓋正常碼誰都能過邊界碼才是照妖鏡。我一般固定造這么一組SSID 含分號(hào)、SSID 含中文、SSID 正好 32 字節(jié)、密碼含反斜杠和雙引號(hào)、密碼 8 位與 63 位各一、無密碼開放網(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é)果撈出來別靠肉眼看真機(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ò)說明bindProcessToNetwork沒生效或者連接壓根沒建立。第二條用來確認(rèn) suggestion 是否真的被系統(tǒng)接受——addNetworkSuggestions返回成功只代表提交成功系統(tǒng)側(cè)可能因?yàn)橹貜?fù)提交或策略限制而丟棄。6.3 一個(gè)收尾習(xí)慣把“連不上”的日志字段固定下來排查這類問題最耗時(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)加起來不到一百字節(jié)但基本能把問題定位到具體某一步不用再問用戶“你手機(jī)什么系統(tǒng)”。吃過一次虧某批門店的 Android 11 設(shè)備反饋“掃碼后彈窗閃一下就沒了”日志里只有一句籠統(tǒng)的失敗。后來補(bǔ)上分支標(biāo)記才發(fā)現(xiàn)是WifiNetworkSpecifier拋了IllegalStateException——上一個(gè)請(qǐng)求沒注銷。加了“先unregisterNetworkCallback再發(fā)新請(qǐng)求”之后同類問題再?zèng)]出現(xiàn)過。從那以后我每次發(fā)版前都會(huì)強(qiáng)制走一遍這套邊界碼加 adb 交叉驗(yàn)證的流程寧可多花半小時(shí)也不想再在群里被追著問“為什么我這臺(tái)連不上”。希望幫到你。本文還有配套的精品資源點(diǎn)擊獲取