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