本文做一件事
- 建立 Flutter iOS CI = 控制面 + 執行面 + 快取面 的三層心智模型。
- 提供 macos-latest vs 自架 的決策矩陣，5 分鐘做出決定。
- 把深度實作分流到 5 個專題子文章——依你的痛點直接進入。
CI 本質模型
在看任何具體工具之前，先建立一個等式——它決定了你該調整哪一層：
Flutter iOS CI =
控制面 （GitHub Actions：觸發 · 審核 · Secrets 管理）
+ 執行面 （Mac mini M4 ：iOS 原生建置 · 簽署 · 環境確定性）
+ 快取面 （本地 SSD ：依賴套件與建置產物的持久化存儲）三個推論直接決定決策方向：
- 控制面不執行程式碼。 最佳化 workflow YAML 不會讓建置變快；要縮短分鐘數必須替換執行面。
- 執行面決定可重現性。 共用池（
macos-latest）的 Xcode 版本隨 GitHub 更新；自架機器的版本由你控制。 - 快取面決定速度。 自架的速度優勢不來自 CPU，而來自本地 SSD 取代了每次 Job 的遠端快取上傳／下載。
Flutter iOS CI 為何需要專用 macOS 執行面？
Flutter 可以在 Linux 上完成 Android 建置和單元測試，但 iOS 建置與 App Store 發佈流程只能在 macOS 上完成——這是 Apple 工具鏈的硬性限制，與 Flutter 本身無關。
因此 Flutter 團隊的 CI 必然面臨一個架構選擇：iOS 那條腿放在哪裡執行？常見的三類摩擦驅動團隊離開 macos-latest：
- 成本：GitHub 託管 macOS Runner 的計費單價顯著高於 Linux，iOS 冷建置時間長，帳單隨建置頻率快速增加。
- 環境確定性：託管映像檔的 Xcode 版本隨 GitHub 更新，無法固定——本地通過、CI 失敗的排查成本極高。
- 建置速度：iOS 依賴套件體積大，託管 Runner 每次需要遠端快取；自架本地 SSD 直接消除這個瓶頸。
「把 macOS 執行面收回可控邊界」是這套架構的核心決策——控制面仍保留在 GitHub（PR 觸發、Review 門禁、Secrets 管理），只把執行層換成租戶專屬的 Mac mini M4。
官方參考：GitHub 自架 Runner 文件 · Flutter 持續部署指南
三層架構總覽
把整條鏈路映射到三面向模型——遇到問題時先判斷屬於哪一層，再進入對應專題文章：
| 面向 | 負責什麼 | 不負責什麼 | 出問題的訊號 |
|---|---|---|---|
| 控制面 | 觸發規則、權限邊界、Secrets 注入、產物上傳 | 不執行任何建置程式碼 | Job 不觸發 / 權限報錯 / PR 門禁失效 |
| 執行面 | iOS 原生建置、Xcode 版本固定、簽署鏈 | 不管觸發邏輯與 Secrets 來源 | 建置環境漂移 / 簽署失敗 / Runner 離線 |
| 快取面 | 依賴套件與建置產物的跨 Job 持久化 | 不決定建置觸發與執行環境 | 熱建置 ≈ 冷建置 / 磁碟警告 / 隨機失敗 |
任何 Flutter iOS CI 故障都能歸到以上三行之一。歸對面向，修復路徑就清晰了。
決策矩陣：什麼時候值得遷移？
自架不是預設答案。下面的矩陣用於 5 分鐘內做出決定：
| 訊號 | 建議保留 macos-latest | 建議遷至自架 |
|---|---|---|
| 建置頻率 | 每月 < 40 次 iOS 建置 | 每月 > 40 次，或每日多次 |
| 環境穩定性 | 對 Xcode 小版本不敏感 | 需要固定 Xcode / SDK 版本 |
| 建置速度 | 熱建置 < 8 分鐘可接受 | 熱建置持續 > 8 分鐘影響迭代 |
| 發佈鏈 | 無 App Store 簽署需求 | 有 App Store / TestFlight 發佈鏈 |
| 維運意願 | 零維運優先 | 接受每月一次維護窗換取可控性 |
經驗法則：命中以上 3 條或以上「建議遷至自架」的訊號——遷移通常在 2–4 週內回本（機器租金 vs 節省的託管 macOS 分鐘費）。
專題系列：依痛點直達
本文只建立架構認知與遷移決策。每個執行層面的深度內容在獨立專題文章裡：
| 專題 | 回答的核心問題 | 面向 | 連結 |
|---|---|---|---|
| ① Runner 建置 | 如何讓 Mac mini 穩定在線、可排程、安全隔離 | 執行面 | 即將發佈 |
| ② 三層快取模型 | iOS 建置為何快不起來，如何用本地 SSD 解決 | 快取面 | 即將發佈 |
| ③ 簽署與發佈 | 如何在無人值守的 CI 裡完成 iOS 簽署與 App Store 上傳 | 執行面 | 即將發佈 |
| ④ Workflow 設計 | 如何設計 Android/iOS 分離、路徑篩選與並發策略 | 控制面 | 即將發佈 |
| ⑤ 維運與穩定性 | CI 為何會掛掉、Runner 離線如何恢復、磁碟如何不撐爆 | 執行面 + 快取面 | 即將發佈 |
依場景選擇入口
- 從零建立：本文確認架構方向 → 專題①「Runner 建置」上機 → 專題②「快取模型」提速 → 專題③「簽署」接發佈鏈。
- Runner 已有，iOS 建置慢：直接進入專題②「三層快取模型」。
- 簽署或 TestFlight 卡住：進入專題③「簽署與發佈」。
- Runner 離線 / 建置隨機失敗：進入專題⑤「維運與穩定性」。
- 從 Bitrise 等雲端 CI 遷移：見「Bitrise vs 自架雲端 Mac Runner 決策」，有遷移成本對比表。