Flutter Dev Playbook

> 🌐 English version · 繁體中文（正本 / canonical）

Flutter 開發判準手冊

核心原則

1. Debug(JIT) 的綠燈不算數：release/profile 是 AOT 編譯，行為與 debug 不同——assert 被剝除、tree shaking 移掉只被反射/字串引用的符號、timing 更快會抖出 race。凡 release 相關的改動與所有效能量測都必須用 profile/release 驗，見 references/platform-build.md。
2. build() 是純函式，每 frame 都可能被呼叫：禁止在 build 內做 IO、網路、setState、建 controller、寫檔——副作用會每幀重跑。
3. 狀態先分 ephemeral 與 app state：只有這個 widget 自己用、丟了無所謂 → setState；跨 widget 共享或要存活 → provider/Bloc。錯層＝rebuild 風暴或狀態遺失。
4. rebuild 範圍要主動收窄：讀 state 的位置越低越好；用 select / Consumer 下沉到真正用到值的葉節點，別讓整棵子樹跟著重建。
5. 兩平台是兩份工程：權限宣告、簽章、build mode、plugin 原生實作在 Android 與 iOS 各一份，release 各跑一次才算驗過。

開工分流

| 情境 | 路徑 | 先讀 | |------|------|------| | 新增畫面/功能 | 先定狀態擁有者與分層，再寫 widget | references/state-architecture.md | | 選 setState / Riverpod / Bloc | 走選型決策樹，別憑喜好 | references/state-architecture.md §1 | | UI 卡頓 / 掉 frame / rebuild 太多 | 先 profile，不要先改 code | references/widgets-performance.md §jank | | 抽 widget、const、ListView | 判準在此，別亂抽 helper method | references/widgets-performance.md | | 要碰原生（相機/藍牙/系統 API） | 先問能否用現成 plugin | references/platform-build.md §channel | | debug 正常、release 才爆 | 先假設 tree shaking / AOT / 環境差異 | references/platform-build.md §模式差異 | | 出 release / 上架 | 逐條跑必查清單，兩平台各跑 | references/release-checklist.md | | 加依賴套件 | 先查 pub.dev 分數與維護狀態 | references/release-checklist.md §套件 |

紅線（絕對禁止）

• 禁止在 debug/JIT 下量效能就下結論——debug 有 JIT warmup 與額外檢查，數字比 release 慢數倍且失真；效能只在 profile mode 量。
• 禁止在 build() 裡做 IO / 網路 / 建立 controller / setState——每次 rebuild 重跑，造成迴圈、洩漏、掉 frame。
• 禁止只用 debug build 就宣告 release 相關改動完成——tree shaking、obfuscation、assert 剝除、簽章都只在 release 生效，debug 零證據力。
• 禁止用 GlobalKey 只為了「拿到某個 widget」——重量級、破壞 rebuild、跨樹移動風險；先問是不是狀態設計錯了。
• 禁止 helper method 回傳 Widget 卻假設它有獨立效能邊界——它不是 element、無法 const、父層重建就整段重跑，見 references/widgets-performance.md §抽 widget。
• 禁止 catch 後只 print 不改 state——使用者看到永遠轉圈；錯誤要進 AsyncValue.error 或 error state。
• 禁止改測試斷言讓它變綠——連紅兩次是方向錯誤訊號，退回上一決策點。

失敗訊號（該回頭，不是重試）

| 徵兆 | 多半是 | 退回 | |------|--------|------| | 加了一堆 const、rebuild 還是卡 | state 讀太高、整棵樹重建 | state 讀取位置設計（§收窄） | | 到處補 if (mounted) 才不 crash | 在錯的地方持有 State/context | 生命週期與狀態擁有權 | | release 才 crash，改一處又爆下一處 | tree shaking 掃掉反射/字串引用符號 | 序列化與 build mode 策略 | | 效能「改了有感又沒感」反覆 | 在 debug mode 量，數字本身是噪音 | 改用 profile mode + DevTools timeline | | MissingPluginException 換 plugin 還在 | 沒 flutter clean / 原生端沒註冊 | plugin 整合流程，不是換套件 | | 一個 Bloc/Provider 越塞越多 event | 職責邊界沒切、當成垃圾桶 | 分層與擁有者設計 |

references 索引

• references/state-architecture.md — 狀態選型決策樹、ephemeral vs app state、分層與依賴方向、AsyncValue 三態、rebuild 收窄。動架構或選型前讀。
• references/widgets-performance.md — build 純淨性、helper vs class、const、ListView、key、jank 排查、圖片記憶體。寫 UI 或查卡頓前讀。
• references/platform-build.md — 三種 build mode 證據力、platform channel、兩平台陷阱、obfuscation、web/desktop 現實。碰原生或 release-only bug 時讀。
• references/release-checklist.md — release 冒煙、versioning、雙平台簽章、套件審查、效能驗收。出版前逐條打勾。
• references/test-scenarios.md — 判準測驗集，驗證接手模型是否照走。不給執行中的模型讀。

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: tienenwu
• Source: tienenwu/fables
• License: MIT

Install and usage instructions live in the source repository linked above.