在 Mac mini M4 雲主機上搭建 iOS CI/CD 全流程

團隊規模變大之後，「誰的電腦能出包」這件事本身就會變成瓶頸。我們把 iOS 專案的 CI/CD 整體遷移到 Kvmzen 的 Mac mini M4 雲主機之後，出包等待時間明顯縮短，簽署事故也幾乎歸零。這篇手記記錄了從零搭建這套流水線時踩過的坑，以及最終收斂出來的 Fastfile 與快取策略，供同樣在評估雲端 Mac 的團隊參考。

為什麼選擇雲端 Mac mini M4 做 CI/CD

Xcode 的建置是典型的「運算密集 + 強依賴系統版本」的任務，本機 Runner 很難長期穩定維護。選擇雲端 Mac 節點主要基於三點判斷：

• 規格可控：映像固定 Xcode 與命令列工具版本，不會因為某人手動升級系統而「團隊裡只有他能編譯」。
• 隨時擴容：發版前的回歸測試可以臨時多開幾個節點並行跑，跑完即釋放，不用為峰值常年預留硬體。
• 7×24 值班：M4 晶片待機功耗低，夜間建置、定時安全掃描都可以放心常駐運行，不用擔心電費或噪音。

我們踩過的第一個坑：以為「雲主機」等於「遠端顯示器」，只用它做手動打包。真正把收益吃透，是把它接入 CI 觸發鏈之後才開始的。

CI/CD 流水線設計

階段劃分

一次完整的發版流水線，我們拆成了四個階段：

1. 程式碼拉取與相依解析（SPM / CocoaPods）
2. 單元測試與靜態分析（並行執行）
3. xcodebuild archive 歸檔與簽署
4. 上傳 TestFlight 並通知值班群組

鉤子與觸發條件

main 分支的每次合併會自動觸發階段 1-2；只有打上 release/* 標籤才會繼續跑階段 3-4，避免每次小改動都消耗簽署配額。本地除錯 Fastlane 腳本時，我們習慣先用 Ctrl+C 中斷一次完整跑批，單獨重跑失敗的那一步，能省下不少等待時間。

範例 Fastfile 片段

lane :ci_archive do
  cocoapods
  run_tests(scheme: "Kvmzen")
  build_app(
    scheme: "Kvmzen",
    export_method: "app-store",
    output_directory: "./build"
  )
  upload_to_testflight(skip_waiting_for_build_processing: true)
end

這段腳本本身並不複雜，關鍵是要讓它在同一套映像基線上重複運行都能得到一致結果——這也是我們把映像版本號寫進建置日誌的原因，方便回溯某次失敗是環境問題還是程式碼問題。

快取與相依管理

快取沒配好，雲端建置的速度優勢會被下載相依的時間吃掉。以下是我們線上跑了三個月後總結的對照表：

幾個術語的口徑先對齊一下：

DerivedData

Xcode 的增量編譯產物快取目錄，跨建置重複使用可以顯著縮短二次編譯時間。

SPM 快取

Swift Package Manager 拉取到本機的套件原始碼與解析結果快取，避免每次建置都重新拉取遠端倉庫。

映像基線

雲主機開機即用的系統快照，包含固定版本的 Xcode、CLT 與預熱好的相依快取。

常見問題排查

最容易被忽略的一點：憑證過期不會立刻報錯，而是在上傳 TestFlight 的最後一步才失敗，這時候整條流水線已經空轉了十幾分鐘。我們現在把憑證有效期檢查放進了階段 1，提前失敗、提前告警。

早期我們用過一種「每晚全量清空快取重新建置一次」的笨辦法來防止快取腐化，後來改成按映像版本號做快取失效（版本號不變就重複使用，升級映像才清空），既保住了速度，也不會讓髒快取悄悄潛伏幾週才暴露問題。

「不要相信一次綠燈的 CI；要相信連續十次綠燈的 CI。」——這是我們值班手冊裡反覆強調的一句話，尤其適用於剛遷移到新雲節點的頭兩週。

常見問題