生物辨識失敗的情境

生物辨識失敗有多種原因，每種原因對使用者的影響和合理的 fallback 不同。

暫時性失敗

Face ID 因光線不足辨識失敗、指紋因手指潮濕讀取失敗。使用者的生物特徵正常，只是當次辨識條件不佳。重試可能成功。

持續性失敗

使用者戴口罩讓 Face ID 無法辨識（較舊的 iOS 版本）、手指受傷影響指紋辨識。生物特徵暫時改變，短期內重試都不會成功。需要替代認證方式。

硬體不可用

裝置沒有 Face ID / Touch ID 模組（較舊機型）、模擬器不支援生物辨識、生物辨識功能被裝置管理策略（MDM）禁用。需要替代認證方式。

使用者未設定

裝置有硬體但使用者沒有設定 Face ID 或指紋。系統的 canCheckBiometrics 回傳 true（硬體存在）但實際認證會失敗。需要引導使用者設定或提供替代認證。

iOS 和 Android 的行為差異

iOS（LocalAuthentication）

iOS 的 LAContext.evaluatePolicy 有兩個 policy：

• deviceOwnerAuthenticationWithBiometrics：只接受生物辨識，失敗後不自動提示密碼
• deviceOwnerAuthentication：先嘗試生物辨識，失敗後系統自動彈出裝置密碼輸入

Flutter 的 local_auth 套件的 biometricOnly 參數對應這兩個 policy。biometricOnly: true 用前者，biometricOnly: false 用後者。

iOS 的行為特點：系統控制認證 UI（不是 app 自行繪製），認證失敗次數過多會自動鎖定（需要輸入密碼解鎖），Face ID 多次失敗後系統會自動提供密碼選項（即使 app 要求 biometricOnly）。

Android（BiometricPrompt）

Android 的 BiometricPrompt 分成三個 class：

• BIOMETRIC_STRONG：只接受 Class 3 生物辨識（經過硬體安全模組驗證的指紋/面部）
• BIOMETRIC_WEAK：接受 Class 2 和 Class 3 生物辨識
• DEVICE_CREDENTIAL：接受裝置 PIN/圖形/密碼

三個 class 可以用 | 組合。BIOMETRIC_STRONG | DEVICE_CREDENTIAL 表示先嘗試強生物辨識，失敗後 fallback 到裝置密碼。

Android 的行為特點：不同廠商的生物辨識品質差異大（Samsung 的面部辨識和 Pixel 的面部辨識安全等級不同）、部分裝置的指紋感測器在螢幕下方（使用者可能不知道在哪裡觸碰）。

安全 vs 可用性的顯式取捨

biometricOnly 的決策涉及安全和可用性的取捨。這個取捨應該在功能規格中顯式記錄，讓後續的 code review 和維護者能理解決策的背景。

記錄格式建議：

1Gate: biometric authentication
2Decision: biometricOnly = false (allow device credential fallback)
3Security trade-off: device credential (PIN/password) is weaker than biometric
4Rationale: self-hosted tool, user = owner, availability > auth strength
5Risk accepted: someone with device PIN can access the app

app_tunnel 選擇 biometricOnly: true 的原始意圖是「安全性更高」，但沒有顯式記錄取捨，也沒有評估「Face ID 不可用時使用者完全無法使用 app」的代價。自用工具的使用者就是 owner，密碼 fallback 的安全風險遠低於完全無法使用的可用性風險（U.C2）。

下一步路由

• Gate 設計的通用方法論 → Gate 分類與三問設計法
• 開發環境遮蔽 gate 問題 → 開發環境 vs 真機的 gate 行為差異表
• 安全 vs 可用性在 monitoring 中的對應 → monitoring 模組七 資安

Back 行為

iOS

iOS 沒有系統級的 back 按鈕。導航列左上角的 back 按鈕由 app 提供（UINavigationController 自動加入）。使用者也可以從螢幕左邊緣向右滑動觸發 back（edge swipe gesture）。

iOS 的 back 行為是 pop — 彈出堆疊頂端，回到前一個畫面。沒有 Android 的系統 back 按鈕覆寫機制。

Android / Material Design

Android 有系統級的 back 按鈕（虛擬或實體）。Material Design 在 app bar 左上角也放 back 箭頭或 hamburger menu 圖示。

Android 的 back 行為由 app 控制（onBackPressed），可以被覆寫。常見的覆寫場景：在首頁按 back 詢問「是否離開 app」、在表單中按 back 詢問「是否放棄編輯」。

跨平台決策

Flutter 預設在 Android 上攔截系統 back 按鈕，在 iOS 上提供 back 按鈕和 edge swipe。GoRouter 的 pop() 在兩個平台上行為一致。

跨平台 app 需要注意的差異：iOS 使用者習慣 edge swipe back，Android 使用者習慣按系統 back 按鈕。兩者都要支援。

Tab bar 位置

iOS

Tab bar 固定在畫面底部。iOS 使用者期望 tab bar 永遠可見、永遠在底部。Apple 的 HIG 明確建議 tab bar 在底部。

Material Design

Material Design 的 bottom navigation 也在底部，但額外支援 top tabs（在 app bar 下方的可滑動標籤列）。Top tabs 適合同一類內容的不同視角（全部 / 未讀 / 已標記）。

跨平台決策

底部 tab bar 在兩個平台上都是標準做法。Top tabs 在 iOS 上較少見（iOS 偏好用 segmented control 代替 top tabs）。跨平台 app 用底部 tab bar 是最安全的選擇。

Modal 呈現

iOS

iOS 的 modal 畫面從底部滑上來，覆蓋前一個畫面但不完全遮擋（iOS 13+ 的 sheet 呈現樣式可以看到前一個畫面的上緣）。Dismiss 操作是向下滑動或點擊關閉按鈕。

Material Design

Material Design 的 bottom sheet 和 dialog 是 modal 的主要形式。Full-screen dialog 從底部滑上來，有 close 按鈕在左上角和 action 按鈕在右上角。

跨平台決策

Flutter 的 showModalBottomSheet 和 showDialog 在兩個平台上都可用。視覺呈現可以用 platform-adaptive widget（CupertinoPageRoute vs MaterialPageRoute）按平台切換。

選擇策略

多數跨平台 app 選擇「共用核心、差異點適配」— 底部 tab bar、push/pop 導航在兩個平台上一致；back 手勢、modal 呈現按平台適配。

下一步路由

• Deep link 設計 → Deep link 設計
• go vs push 的語意差異 → go vs push vs pushReplacement 語意表
• 導航模式分類 → Mobile 導航模式分類

請求時機

首次開啟時一次性請求

App 首次啟動時依序請求所有需要的權限。優點是使用者只被打斷一次；缺點是使用者尚未使用任何功能，不理解每個權限的用途，傾向拒絕。

這個模式適合權限數量少（1-2 個）且和 app 核心功能直接相關的情境。相機 app 在首次開啟時請求相機權限，使用者能直覺理解原因。

功能使用時即時請求

使用者點擊需要權限的功能時才請求。優點是使用者在操作 context 中，能理解為什麼需要這個權限；缺點是操作流程被打斷。

這個模式適合權限和特定功能綁定的情境。掃描 QR code 時請求相機權限，使用者正在嘗試掃描，理解為什麼需要相機。

推薦策略

功能使用時即時請求是多數場景的推薦策略。使用者有操作 context，授權率較高。打斷可以透過 pre-permission 說明畫面降低突兀感。

Pre-permission 說明畫面

在觸發系統權限對話框之前，app 先顯示自己的說明畫面，解釋為什麼需要這個權限和用途。

說明畫面的設計要點：

說明用途而非技術細節。「需要相機來掃描裝置上的 QR code」比「app 需要存取 AVCaptureDevice」更有用。使用者關心的是「為什麼」，不是「用什麼 API」。

提供「稍後再說」選項。使用者可能想先了解 app 再決定是否授權。強制授權（沒有跳過選項）會讓使用者選擇拒絕。

視覺化說明。用截圖或圖示展示「授權後這個功能長什麼樣」，讓使用者預覽授權的價值。

拒絕後的處理

使用者拒絕權限後，app 需要：

記住拒絕狀態。不要在每次使用者操作同一功能時都顯示 pre-permission 說明（使用者已經表達不想授權，反覆詢問是騷擾）。

提供功能降級。如果可能，提供不需要權限的替代方案。掃描 QR code 可以改成手動輸入配對碼。

在適當時機再提醒。使用者多次使用需要權限的功能但都因為沒有權限而失敗時，用非侵入式提示（Snackbar）說明「開啟相機權限可以使用掃描功能」加設定連結。

引導到系統設定。一旦使用者在系統對話框中選擇「不再詢問」（Android）或拒絕（iOS 拒絕後系統不再彈窗），唯一的路徑是引導使用者到系統設定手動開啟。提供直接跳轉到 app 設定頁面的按鈕。

下一步路由

• Gate 設計的通用方法論 → Gate 分類與三問設計法
• 網路 gate 的處理策略 → 網路斷線 UX 模式
• 開發環境遮蔽 gate 問題 → 開發環境 vs 真機的 gate 行為差異表

這類狀態可以稱為 Android emulator 半活（zombie）：emulator host process 還在、ADB 清單仍殘留 device，但 emulator 內的 adbd 或 Android system 已停止回應。Flutter 在掃描階段會對每個 Android device 查 properties，掃描到這個半活 device 就卡在 timeout。

事故場景

事故場景的核心是「Flutter 指令看似卡住，其實卡在下游 device property 查詢」。連續跑 flutter devices 時，輸出長這樣：

1$ flutter devices
2Found 4 connected devices:
3Error -2 retrieving device properties for sdk gphone64 arm64:
4[卡住]
5
6$ flutter devices
7Found 3 connected devices:
8[繼續卡]

這段輸出有兩個值得注意的點：

1. Error -2 retrieving device properties for sdk gphone64 arm64: 訊息出現後仍繼續等待，代表 Flutter 沒有在第一個 device 失敗時 fail-fast
2. 第一次 Found 4、第二次 Found 3，代表 device 數在兩次掃描之間自己少了 1

sdk gphone64 arm64 是 Android Studio AVD 預設模板（Google Phone 64-bit ARM）建出來的 emulator 顯示名稱、macOS 上跑 Android system image 都會看到這個。

為什麼計數變化是關鍵徵兆

device 數從 4 變 3，代表 ADB 對某個 emulator 的狀態判斷在兩次查詢之間變了。ADB server 內部追蹤每個 device 的狀態（device / offline / unauthorized / no permissions）；半活 emulator 在第一次掃描時仍被列在 Found 4，第二次掃描時可能已被標成 offline 或從候選清單移除，所以掉到 Found 3。

判讀訊號是「同一條 list 指令連跑兩次，device 數或 device 狀態自己變」。正常穩定狀態下，清單應該保持一致；清單漂移代表 ADB server 對某個 entry 的看法不穩定，下一步要先找出那個 entry，再決定是否重啟 ADB 或 emulator。

為什麼 flutter devices 會卡住

flutter devices 的責任是把每個候選 device 補成 Flutter 可用的 target，而不只是印出 adb devices 的結果。Flutter 對每個 ADB 看得到的 Android device 還要做幾件事：

1. 跑 adb shell getprop ro.product.cpu.abi 拉 ABI
2. 跑 adb shell getprop ro.build.version.sdk 拉 SDK level
3. 跑 adb shell getprop ro.product.model 拉裝置型號
4. 視情況跑 adb shell 其他指令確認 Flutter 支援度

這些是同步、序列化、有 timeout 的呼叫；timeout 通常設得相對寬鬆，讓慢一點的真機也能跑通。當其中一個 device 是 zombie 狀態：

• adb shell getprop ... 送出後，ADB 把指令轉發給 emulator 內的 adbd
• adbd 收到了但 Android system 沒回應，或 emulator process 整個卡住沒在處理 ADB request
• Flutter 端等 timeout、再 retry、再等更長 timeout，看起來就是「整個指令卡住」

Error -2 retrieving device properties 是其中一次嘗試 timeout 拿到的訊息（-2 是 Dart ProcessException 對應 adb exit code 的內部映射）。Flutter 仍會繼續掃描其他 device，所以使用者看到的是「印出錯誤訊息 + 繼續卡」。

為什麼是半活狀態

Android emulator 在 macOS 上的結構大致是：

1qemu-system-aarch64 (host process)
2  ├─ Android kernel
3  ├─ Android system services
4  └─ adbd (在 emulator 內部，跟 host ADB server 對接)

半活狀態指的是「host process 還在，但 device 內部服務已無法完成 ADB request」。完全正常時 emulator 跑得動、ADB 也通；完全退出時 emulator process 已結束、ADB 清單看不到它。半活介於兩者之間：

• qemu host process 還在（活著）
• emulator 內的某個環節卡住（Android system 沒在 schedule、或 adbd 卡在某個 mutex）
• ADB server 還記得有這個 device，尚未穩定 evict
• 任何 adb shell 指令都打不通

常見成因：

• Quick Boot snapshot 還原失敗或部分還原——AVD 預設關機是 quick boot（存 snapshot），下次開機從 snapshot 還原；snapshot 跟當前 host kernel / hypervisor 狀態不相容時會半開機
• macOS 從 sleep 喚醒後 hypervisor framework 重置——emulator 是用 Hypervisor.framework，喚醒後虛擬 CPU 可能停在奇怪 state
• host 端記憶體壓力導致 emulator 被 swap 嚴重——表面看起來像卡，其實是在等 page fault

這一層的操作目標是恢復工具鏈，而不是追到每個 emulator 內部 race condition。若症狀符合清單漂移與 property 查詢 timeout，先按恢復順序處理；只有反覆發生時，再追 AVD snapshot、system image 或 host 資源壓力。

恢復順序（從輕到重）

恢復順序的核心是先重置最小邊界，再逐層擴大。每一步都要重新跑一次 flutter devices 或 adb devices，確認是否已經恢復，避免直接砍掉 emulator 或清資料。

1# 1. 看 ADB 對每個 device 的狀態
2adb devices
3# 看到 offline / no device / unauthorized 等異常狀態 → 先鎖定該 device

如果有 device 顯示 offline，或正常列出但實際打不通，先重啟 ADB server：

1# 2. 重啟 ADB server（只重置 host 端 ADB session）
2adb kill-server && adb start-server
3adb devices
4# 多數狀況下，ADB 重啟後對該 device 的查詢會 fail-fast，flutter devices 會恢復

如果 ADB 重啟後仍打不通該 emulator，再處理 emulator process：

1# 3. 對特定 emulator 發 emu kill（讓它優雅關閉）
2adb -s emulator-5554 emu kill   # 把 5554 換成實際 port
3
4# 4. 還在的話，終止 qemu process
5pkill -f qemu-system-aarch64

長期修復路由是清掉不穩定的 snapshot。開 Android Studio → AVD Manager → 該 emulator 旁邊的小箭頭 → Cold Boot Now（避免 Quick Boot）。如果冷啟動後仍反覆壞，選 Wipe Data 把 snapshot 與 emulator 內資料整個清掉。

通用診斷思維

工具鏈卡住的診斷核心是先區分「上游 CLI 壞掉」還是「下游 target 沒回應」。flutter / adb 指令卡住時，先用清單穩定性與 device 識別碼定位下游狀態，再決定重啟邊界。

1. 觀察「同一指令連跑兩次結果是否一致」：不一致（device 數變、訊息變）等於某層狀態不穩定
2. 訊息裡有 device 識別碼就釘住它：sdk gphone64 arm64、emulator-5554、序號等都是 ADB 層的識別，可直接拿來 adb -s <id> ... 局部診斷
3. 從外往內排除：ADB server → 個別 device → emulator process → emulator 內 system，逐層重啟
4. 重啟邊界越大、副作用越大：adb kill-server 只影響 ADB session（其他 device 連線會斷一下），pkill qemu 直接砍 emulator，Wipe Data 連 emulator 內的資料都清。能用輕量手段解決就停在那層

操作判準

1. 「device 數兩次掃描之間自己變」是 zombie emulator 的關鍵徵兆：計數變化代表 ADB 內部狀態不穩定
2. Error -2 retrieving device properties 是 property 查詢失敗訊號：Flutter 仍可能繼續處理其他 device，結果是「印出錯誤訊息但繼續卡」
3. adb kill-server && adb start-server 是輕量首選：它只重置 ADB session，不動 emulator 本身，多數狀況下可讓壞 device fail-fast
4. 半活狀態跟 application code 層級不同：先把工具鏈狀態釐清，再回到剛改的程式碼

適用範圍

這個診斷思維不限於 Android emulator：

• iOS Simulator 卡住時 xcrun simctl list 印不出來——同樣的「指令卡 + 訊息看似 fatal 但 process 仍存在」結構
• flutter devices 對任何 device（含 iOS、Web、desktop）的查詢都會走類似的「列出 → 逐個 query property」流程、任一層卡都會表現為類似症狀
• 廣義地說，任何「server 維護一份 client 清單 + 對每個 client 做同步呼叫」的架構（k8s kubectl get pods 對 zombie node、docker docker ps 對掛掉的 container runtime 等）都有同款 failure mode

辨認規則一致：list 指令連跑兩次結果不一致 → 維護清單的 server 對某個 entry 的看法不穩定 → 找出那個 entry 局部處理。這條規則的邊界是：如果清單穩定但操作失敗，問題更可能在該 target 的權限、版本或 runtime 狀態，需要改走對應工具的細部診斷。

這些錯誤表面訊息不同，但根本原因都是「callback 註冊得太晚，或屬性被賦值得太晚」：

想正確治理這些情境，必須先理解 Gradle configuration 的時序模型。

Gradle Configuration 階段的時序

單一 project 的 evaluate 流程

sequenceDiagram
    participant Root as Root build.gradle
    participant Sub as Subproject build.gradle
    participant Plugin as Plugin (apply)
    participant After as afterEvaluate

    Root->>Sub: 開始 evaluate subproject
    Sub->>Plugin: apply plugin 'com.android.library'
    Note over Plugin: plugins.withId callback 觸發
    Plugin-->>Sub: 回到 subproject 腳本
    Sub->>Sub: android { compileOptions = 1.8 }
    Note over Sub: plugin 自己的設定套用
    Sub->>After: subproject evaluate 完成
    Note over After: afterEvaluate callback 觸發

關鍵時機：

1. subprojects {} block 的內容：最早執行
2. plugins.withId("...") { ... } callback：plugin apply 那一刻觸發
3. plugin 自己 build.gradle 內的設定（例如 android { ... }）：在 3 之後
4. afterEvaluate { ... } callback：subproject evaluate 完畢後觸發
5. tasks.withType(...).configureEach { ... }：task realize/configure 時才套用

要覆寫某個設定，必須讓覆寫的時機晚於那個設定的寫入時機。

多 project 的順序

預設情況 Gradle 自己決定 subproject 的 evaluation 順序（通常按字典序）。但若有：

1subprojects {
2    project.evaluationDependsOn(":app")
3}

:app 被強制最先完成 evaluate。這是為了讓其他 subproject 能看到 :app 的 extension 值，但副作用是：對 :app 來說，後面所有 subprojects {} 內的 hook（尤其是 afterEvaluate）註冊時機都太晚了。

錯誤 1：Cannot run Project.afterEvaluate when already evaluated

症狀

1subprojects {
2    afterEvaluate {
3        if (project.name != 'app') {
4            // 想對非 app 的 subproject 做事
5        }
6    }
7}

build 時拋錯，指著 afterEvaluate 那一行。

邏輯推論

• afterEvaluate(Closure) 是註冊動作，註冊當下就執行
• subprojects {} 對每個 subproject 都執行一次，包括 :app
• 當處理到 :app 時，它已經 evaluate 完畢（因為 evaluationDependsOn）
• 對已 evaluate 的 project 註冊 afterEvaluate → 註冊失敗 → 拋錯

把 project.name != 'app' 放在 closure 內救不了——afterEvaluate 方法本身已經先炸。

解法

判斷必須提前到註冊動作之外：

1subprojects {
2    if (project.name != 'app') {
3        afterEvaluate {
4            // 此時 :app 根本不會進到這裡
5        }
6    }
7}

更穩健的通用寫法

若不想 hardcode 名字：

1subprojects {
2    if (!project.state.executed) {
3        afterEvaluate { ... }
4    } else {
5        // 對已 evaluate 的 project 立即執行（如果適用）
6    }
7}

錯誤 2：languageVersion is final and cannot be changed any further

症狀

在 subprojects {} 內嘗試為所有 Kotlin Android 子專案套用 JVM Toolchain：

1subprojects {
2    plugins.withId("org.jetbrains.kotlin.android") {
3        kotlin {
4            jvmToolchain(17)
5        }
6    }
7}

某個 subproject evaluate 時拋錯。

邏輯推論

• plugins.withId callback 在 plugin apply 那一刻觸發
• 但 Kotlin plugin 的部分屬性在另一個更早的時機就被 finalize（例如 plugin 自己內部的 lazy property initialization）
• jvmToolchain(17) 想寫入 languageVersion 這類屬性，發現已 finalize
• Gradle 的 Provider API 對已 finalize 的屬性再賦值會直接 throw

診斷

看錯誤訊息最後幾個字：is final and cannot be changed any further。這是 Gradle Provider API 的通用訊息，指向「lazy property 被 finalize 後無法修改」。

不要去找「誰把它 finalize 了」——這通常是 plugin 內部實作細節，追不到根因。

要找：「有沒有更早的時機點可以設定這個？」

解法

把 toolchain 設定往前搬到 :app/build.gradle 的頂層（而不是在 root 的 subprojects 內延遲套用）：

1// :app/build.gradle
2kotlin {
3    jvmToolchain(17)
4}

Flutter 專案的 :app 是 root configuration 最早執行的 subproject，這個時機點還沒人會 finalize Kotlin plugin 的屬性。

Gradle 會用 :app 的 toolchain 決定整個 daemon 用哪個 JDK，其他 subproject 繼承這個 JDK 環境，不需要自己再宣告 toolchain。

錯誤 3：覆寫了 plugin 設定卻沒生效

症狀

在 root build.gradle 寫了：

 1subprojects {
 2    plugins.withId("com.android.library") {
 3        android {
 4            compileOptions {
 5                sourceCompatibility = JavaVersion.VERSION_17
 6                targetCompatibility = JavaVersion.VERSION_17
 7            }
 8        }
 9    }
10}

但第三方 plugin（例如 external_display）仍然用 JVM 1.8 編譯。

邏輯推論

回到時序圖：

第 4 步晚於第 3 步，覆蓋了我們的 17。

解法

把覆寫時機搬到第 4 步之後：

1afterEvaluate {
2    android {
3        compileOptions {
4            sourceCompatibility = JavaVersion.VERSION_17
5            targetCompatibility = JavaVersion.VERSION_17
6        }
7    }
8}

afterEvaluate 的 callback 在 subproject 的 build.gradle 整個執行完畢後觸發，此時 plugin 已經寫完 compileOptions = 1.8，我們再蓋回 17 就贏了。

除錯決策樹

遇到 configuration 階段的時序錯誤時：

flowchart TD
    A[出現錯誤] --> B{訊息關鍵字}
    B -->|already evaluated| C[註冊 callback 太晚]
    B -->|is final| D[賦值屬性太晚]
    B -->|覆寫沒生效| E[覆寫時機太早]
    C --> F[在註冊前跳過已 evaluate 的 project]
    D --> G[把賦值搬到更早的時機點]
    E --> H[把覆寫搬到 afterEvaluate]

三個解法方向完全相反：

• 太晚 → 提前
• 太早 → 延後

所以看到錯誤時第一件事是判斷時機太早還是太晚，而不是試圖繞過屬性狀態。

判斷「時機太早還是太晚」的速查

Android Flutter 專案升到 Kotlin 2.2 + AGP 8.12 後，build 時出現：

1Execution failed for task ':external_display:compileDebugKotlin'.
2> ⛔ Inconsistent JVM Target Compatibility Between Java and Kotlin Tasks
3  Inconsistent JVM-target compatibility detected for tasks
4  'compileDebugJavaWithJavac' (1.8) and 'compileDebugKotlin' (17).

主專案 :app 已經設定 JVM 17，但第三方 plugin（例如 external_display）的 build.gradle 硬寫死 JVM 1.8。想從主專案這邊強制覆寫，卻發現 Kotlin 用一種寫法能贏、Java 用同樣的寫法卻會輸。

Kotlin 與 Java 的覆寫結果不一樣

Kotlin 端：task 級 configureEach 能贏

1subprojects {
2    tasks.withType(org.jetbrains.kotlin.gradle.tasks.KotlinCompile).configureEach {
3        kotlinOptions {
4            jvmTarget = '17'
5        }
6    }
7}

即使 plugin 的 build.gradle 寫了 kotlinOptions { jvmTarget = '1.8' }，這段覆寫仍然會贏。

Java 端：task 級 configureEach 會被蓋回去

1subprojects {
2    tasks.withType(JavaCompile).configureEach {
3        sourceCompatibility = '17'
4        targetCompatibility = '17'
5    }
6}

這段看起來跟 Kotlin 端對稱，但沒用 —— task 上的賦值會被 AGP 從 android.compileOptions 再同步回來，重新變成 1.8。

為什麼不對稱：兩個 plugin 的內部機制不同

Kotlin Plugin：extension → task 單向流動

Kotlin plugin 讀取 kotlin {} 或 kotlinOptions {} extension 的值，寫入對應的 KotlinCompile task。寫入一次，之後不再同步。

flowchart LR
    E[kotlin extension] -->|一次性寫入| T[KotlinCompile task]
    C[configureEach] -->|後寫的贏| T

這就是為什麼 configureEach 能贏 —— 它註冊的 configuration action 在 task realization 時才套用，比 plugin 的 extension 寫入更晚。

AGP：extension ↔ task 雙向同步

AGP 把 android.compileOptions.sourceCompatibility 視為真相來源，每次 JavaCompile task 被 realize 或 configure 時，都會從 extension 重新同步過去。

flowchart LR
    E[android.compileOptions] <-->|持續同步| T[JavaCompile task]
    C[configureEach] -.->|被 AGP 蓋回去| T

在 task 上直接賦值沒用 —— AGP 會用 extension 的值把你蓋掉。真正有效的治理點是 extension 本身。

正確解法：切入點依 plugin 機制決定

Kotlin：鎖 task

1tasks.withType(org.jetbrains.kotlin.gradle.tasks.KotlinCompile).configureEach {
2    kotlinOptions {
3        jvmTarget = '17'
4    }
5}

Java：鎖 extension，而且要在 afterEvaluate 時機

直接在 subprojects {} 最外層寫 plugins.withId("com.android.library") { android { compileOptions {...} } } 也沒用：這個 callback 在 plugin 被 apply 時立刻觸發，早於 plugin 自己的 build.gradle 執行，會被 plugin 後來的 android { compileOptions = 1.8 } 蓋回去。

必須等 plugin 自己的 android {} 執行完之後再改，也就是 afterEvaluate：

 1subprojects {
 2    if (project.name != 'app') {
 3        afterEvaluate {
 4            if (project.hasProperty('android')) {
 5                android {
 6                    compileOptions {
 7                        sourceCompatibility = JavaVersion.VERSION_17
 8                        targetCompatibility = JavaVersion.VERSION_17
 9                    }
10                }
11            }
12        }
13    }
14}

診斷流程

遇到 JVM target inconsistency 錯誤時，照以下步驟推論：

步驟 1：看錯誤訊息指的是哪個 task

1Inconsistent JVM-target compatibility detected for tasks
2'compileDebugJavaWithJavac' (1.8) and 'compileDebugKotlin' (17).

• compileDebugJavaWithJavac 是 Java 端的 task
• compileDebugKotlin 是 Kotlin 端的 task
• 括號內的數字就是各自的 target

步驟 2：看哪一端低、哪一端高

• 低的那端被 plugin 硬寫死了
• 高的那端是主專案設定已經生效的

這一步決定要覆寫哪一端。

步驟 3：看是哪個 plugin 引起的

從錯誤訊息的 task 前綴 :external_display:compileDebugKotlin 找到是 external_display plugin。

查它的 build.gradle：

1find ~/.pub-cache/hosted/ -type d -name "external_display*"
2cat ~/.pub-cache/hosted/pub.dev/external_display-0.4.2+1/android/build.gradle

通常會看到：

1compileOptions {
2    sourceCompatibility JavaVersion.VERSION_1_8
3    targetCompatibility JavaVersion.VERSION_1_8
4}
5kotlinOptions {
6    jvmTarget = '1.8'
7}

步驟 4：依 Kotlin/Java 差異選擇覆寫方式

• Kotlin 寫死 → 用 KotlinCompile.configureEach
• Java 寫死 → 用 afterEvaluate 改 android.compileOptions

完整的 root android/build.gradle 範例

 1subprojects {
 2    // Java 端：在 plugin 的 android {} 執行完後覆寫 compileOptions
 3    if (project.name != 'app') {
 4        afterEvaluate {
 5            if (project.hasProperty('android')) {
 6                android {
 7                    compileOptions {
 8                        sourceCompatibility = JavaVersion.VERSION_17
 9                        targetCompatibility = JavaVersion.VERSION_17
10                    }
11                }
12            }
13        }
14    }
15    // Kotlin 端：task 級直接覆寫
16    tasks.withType(org.jetbrains.kotlin.gradle.tasks.KotlinCompile).configureEach {
17        kotlinOptions {
18            jvmTarget = '17'
19        }
20    }
21}

:app 跳過是因為它透過 kotlin { jvmToolchain(17) } 自己處理了（見下節）。

延伸：為什麼 :app 不能用同一套覆寫

若專案的 root build.gradle 裡有：

1subprojects {
2    project.evaluationDependsOn(":app")
3}

這行強制 :app 比所有其他 subproject 先 evaluate。等到 subprojects { afterEvaluate {} } 想註冊到 :app 時，:app 已經 evaluate 完畢，Gradle 拋：

1Cannot run Project.afterEvaluate(Closure) when the project is already evaluated.

所以要在呼叫 afterEvaluate 之前用 project.name != 'app' 跳過它。 :app 的 JVM 設定交給 :app/build.gradle 自己處理，例如：

1kotlin {
2    jvmToolchain(17)
3}

• Android 裝置系統版本 Android 11 以上
• 電腦與 Android 裝置連接在同一個區域網路
• 已安裝 ADB 工具（通常隨 Android Studio 安裝）

步驟一：啟用無線偵錯

1. 進入 Android 裝置的 設定 → 開發人員選項
2. 開啟 無線偵錯（Wireless debugging）
3. 在彈出的對話框中選擇「允許」

步驟二：配對裝置（首次連接需要）

在 Android 裝置上

1. 點擊 無線偵錯 進入詳細頁面
2. 點擊 使用配對碼配對裝置
3. 記下畫面上顯示的：
   • IP 位址與配對端口（例如：192.168.1.100:45213）
   • 配對碼（6 位數字）

在電腦終端機上

1adb pair <IP>:<配對端口>

範例：

1adb pair 192.168.1.100:45213

輸入配對碼後，看到以下訊息表示配對成功：

1Successfully paired to 192.168.1.100:45213

注意：配對碼有時效性，產生後請盡快輸入

步驟三：連接裝置

在 Android 裝置上

回到無線偵錯主頁面，查看顯示的 IP 位址與連接端口（與配對端口不同）

例如：192.168.1.100:38745

在電腦終端機上

1adb connect <IP>:<連接端口>

範例：

1adb connect 192.168.1.100:38745

看到以下訊息表示連接成功：

1connected to 192.168.1.100:38745

步驟四：驗證連接

1adb devices

或使用 Flutter：

1flutter devices

應該能看到無線連接的裝置列表。

常用指令速查

疑難排解

配對失敗

• 確認電腦與裝置在同一區網
• 檢查路由器是否開啟 AP 隔離功能
• 暫時關閉電腦防火牆測試

連接後無法使用

• 確認使用的是「連接端口」而非「配對端口」
• 嘗試重啟 ADB 服務：adb kill-server && adb start-server

裝置離線或消失

• 無線偵錯可能因裝置休眠而中斷
• 重新執行 adb connect 即可恢復

流程圖

 1┌─────────────────┐
 2│  啟用無線偵錯   │
 3└────────┬────────┘
 4         ▼
 5┌─────────────────┐
 6│  取得配對資訊   │ ← 配對端口 + 配對碼
 7└────────┬────────┘
 8         ▼
 9┌─────────────────┐
10│   adb pair      │ ← 首次連接需要
11└────────┬────────┘
12         ▼
13┌─────────────────┐
14│  取得連接端口   │ ← 無線偵錯主頁面
15└────────┬────────┘
16         ▼
17┌─────────────────┐
18│  adb connect    │
19└────────┬────────┘
20         ▼
21┌─────────────────┐
22│    連接完成     │
23└─────────────────┘