2026-05-12 在租用的 Apple Silicon 雲端 Mac（香港 / 東京 / 首爾 / 新加坡 / 美國）上，以 Xcode 方案、建置組態 與 xcconfig 分層 做 多分支 CI 隔離
當 main、release/x.y 與大量 feature/* 分支都落在同一台租用的 Mac mini M4 建置機上時，最常見的失敗並不是「Xcode 不會編譯」，而是組態靜默漂移：昨天的作業在帶生產描述檔的 Release 方案上跑通，而今天的實驗分支卻以為自己在 Debug 權利集下工作；又或者兩條並行作業寫進同一個 CONFIGURATION_BUILD_DIR，只因包裝指令稿忘了依作業加前綴。本 2026-05-12 手冊把 索引儲存車道隔離、並行 xcodebuild 佇列 與 GitHub Actions 自託管 Runner 落地 串成一條鏈：顯式方案對應表、可審查的 xcconfig 堆疊，以及把解析後的建置設定當作基礎設施程式碼來斷言的 CI 門檻。
為何在共用租用主機上，「方案」比個人筆電上更重要
本地開發者在 Xcode UI 裡切換方案，肌肉記憶會攔截大量錯誤；無頭環境下的 xcodebuild 在共用 UID 上沒有任何「手感」——只有編排器傳入的字串。於是工作流 YAML 裡一個過期的預設方案名，就可能演變成跨租戶的簽章事故：歸檔繼承了錯誤的 DEVELOPMENT_TEAM 或 PRODUCT_BUNDLE_IDENTIFIER。生產級租用 CI 應發布從分支模式到方案 + 組態對的正向對應，與 .xcconfig 一併入庫，並在建置映像上對照 xcodebuild -list 輸出做漂移偵測，對應不一致則阻斷合併。
-scheme，並在編譯消耗 NVMe 數分鐘之前，斷言解析到的 configuration 與意圖一致。
分支分類 → 方案對應：避免「方案爆炸」
成熟團隊會把方案面收斂得很小：一個主 App 方案、擴充功能成組、可選 Widget 方案，以及在 App Store 匯出設定與日常 CI 明顯不同的時候再拆一個專用歸檔方案。分支透過策略在這些方案之間選擇——例如 main 固定用 App-CI + Debug 跑單元測試，而 release/* 用 App-Store + Release。把正規表示式規則（如 ^release/）寫在與工作流定義同目錄的 Markdown 裡，讓審查在一個 diff 裡同時看到 Git 條件與方案字串。若同一主機上還跑著 OpenClaw 等自動化，應為助手觸發的建置保留即使誤呼叫也無法碰到生產簽章身分的方案集合。
- 主幹方案 —— 追求回饋速度、可偵錯符號、相對寬鬆的編譯告警。
- 發布列車方案 —— 收緊告警，與 App Store Connect 上傳、dSYM 等設定對齊。
- 熱修方案 —— 帶時效的對應項，由 CI 定期工單自動回收。
xcconfig 分層：基線、環境、車道、金鑰
把 .xcconfig 看成可組合策略：Base.xcconfig 固定 Swift 語言模式與告警畫像；Staging.xcconfig 用尾碼覆寫 PRODUCT_BUNDLE_IDENTIFIER；LaneJob.xcconfig（每作業產生、不入庫）注入 CONFIGURATION_BUILD_DIR、OBJROOT 前綴，並與 DerivedData 策略對齊。Xcode 依深度優先解析 include——順序很重要——因此把易變檔案放在最後，並以金鑰管理範本步驟產生、避免入庫。對 include 鏈設定 code owner，讓行動端基礎設施與安全團隊在 ATS 例外或簽章材料跨層遷移時雙人簽字。
與「方案決策」綁定的 xcodebuild 參數
除了 -scheme 與 -configuration，租用側常見還會匯出 -derivedDataPath、-resultBundlePath，以及在 SwiftPM 情境下的 -clonedSourcePackagesDirPath。這些旋鈕要與索引儲存／模組快取車道文章一致，避免 APFS 抖動。執行 xcodebuild archive 時，務必讓測試車道與歸檔車道共用同一份方案對應——把邏輯拆到互不關聯的工作流，是「測試綠、歸檔紅」的經典分叉來源。每個作業抓取 xcodebuild -showBuildSettings -json 並作為建置產物留存，便於在無法單提交 bisect 時對解析結果做差分取證。
xcodebuild -scheme "App-CI" -configuration Debug -destination 'platform=iOS Simulator,name=iPhone 16' -derivedDataPath "$DD" -resultBundlePath "$RESULT" build
合併佇列、堆疊 PR 與「方案穩定契約」
合併佇列會相對分支尖端重排提交；若對應只依賴分支名通常仍安全，但若依賴合併組合成支等臨時分支名，就要加顯式回退。堆疊 diff 工具在佇列中途改寫歷史時，應在每次 rebase 後重新執行方案探測——把它當作 CI 前置步驟，而不是事後補丁。文件化一份穩定契約：重新命名方案必須兩階段上線（先加別名方案、遷移工作流、再刪舊方案），避免租用 Runner 上的 YAML 還是半遷移狀態而開發者本地已刪 legacy 方案。
自動簽章 vs 手動：xcconfig 能幫什麼、會絆什麼
CODE_SIGN_STYLE = Automatic 在筆電上省事，但在共用主機上仍需要確定性的 DEVELOPMENT_TEAM 以及日誌裡可追蹤的描述檔 UUID。手動樣式要求磁碟或鑰匙圈中的 profile——與簽章 Runbook 對齊，防止特性分支上的 xcconfig include 意外翻轉樣式。對 -showBuildSettings 輸出做 CI grep 門檻，禁止危險組合（例如 Debug configuration + App Store 分發 profile）。單倉多 App 時，依目標命名空間拆分 xcconfig，避免跨目標串味。
決策矩陣：策略應落在何處
| 策略 | 最佳歸屬 | 理由 |
|---|---|---|
| 編譯告警級別 | 入庫的 xcconfig | 可 diff、與業務程式碼同級審查 |
| 每作業建置目錄前綴 | CI 產生的 xcconfig 或環境變數 | 不得入庫；與作業 ID 綁定 |
| 各分支跑哪些測試 | 工作流 YAML + 測試計畫 | 更貼近編排層而非 Xcode 工程本體 |
| 歸檔匯出方式 | ExportOptions.plist + 專用方案 | 與既有 ASC 上傳 Runbook 一致 |
八步：方案感知多分支 CI rollout
- 在各租用區域映像上執行
xcodebuild -list -json，將 JSON 納入基礎設施儲存庫歸檔。 - 撰寫「分支正則 → 方案/組態」表，並掛到 PR 範本檢查清單。
- 引入分層 xcconfig；依目標逐個遷移，保持建置全綠。
- 為 Release 類組態增加 CI 步驟，輸出解析後的建置設定 JSON。
- 將
DERIVED_DATA_PATH與建置目錄匯出與並行車道約定對齊。 - 若出現合成合併分支名，為合併佇列補充分支命名回退規則。
- 培訓發布值長：熱修方案條目與時效回收流程。
- 季度稽核：區域間方案列表 diff，消除範本漂移。
組態治理的 SLO 訊號
| 訊號 | 閾值 | 動作 |
|---|---|---|
作業缺少顯式 -scheme |
0 容忍 | 建置失敗；重發工作流範本 |
解析出的 DEVELOPMENT_TEAM 與白名單不符 |
任意 不一致 | 阻斷產物晉升；呼叫簽章負責人 |
| 未經歷「雙寫期」的方案重新命名 | 任意 未申報改名 | 凍結發布分支合併直至對應更新 |
常見問題
| 問題 | 實務答覆（2026-05-12） |
|---|---|
Debug 與 Release 要拆成兩個方案嗎？ |
不必——若同一方案下兩種組態都存在，用 -configuration 選擇，而不是複製方案。 |
| 是否要為每條車道單獨建儲存庫？ | 不需要——目錄前綴與 xcconfig 尾碼在一致執行時即可隔離。 |
為何 Mac mini M4 租用有利於在高負載下迭代方案策略
高速 NVMe 與充裕的統一記憶體讓您可以背靠背執行 -showBuildSettings 探測、冷啟動模擬器建置與歸檔演練，同時觀察 APFS 分配壓力——這在發布凍結前收緊 xcconfig 堆疊時能顯著縮短回饋環。區域容量請從 定價頁 比較；若 SSH 體驗阻礙落地，在擴大方案面之前先把同事導向 SSH/VNC 指南。
