Kotlin Multiplatform 官方文件說明，建置 Apple 平台目標需要 macOS 與 Xcode。因此，本週先依標準流程評估託管 macOS Agent；只有在你需要固定工具鏈、持續控制節點、接入私有環境或自行維護節點時，才把遠端 Mac CI 納入候選。簽名與發布憑據要獨立評估，不能只看是否擁有 Mac。
適合閱讀的人 - 沒有 Mac、但要驗證 Kotlin Multiplatform iOS 目標的獨立開發者。 - 正把 KMP 專案從試驗推向團隊交付、需要劃分建置與發布責任的技術負責人。 - 維護 Apple 平台 CI，正在評估託管 Agent 與受控遠端 Mac 的 DevOps 工程師。
SECTION 01 交付範圍：哪些工作真的需要 Mac？
先把流水線拆成不同交付階段：共享程式碼驗證、iOS 目標建置、模擬器測試，以及簽名與發布。它們的執行環境與憑據要求不完全相同，不應把「專案用了 Kotlin Multiplatform」直接等同於「所有 CI 工作都必須搬到 Mac」。
Kotlin Multiplatform 的共享程式碼與可在現有 Linux 或 Windows 環境執行的通用測試，可以先留在既有流水線；但涉及 Apple 平台目標的建置，以及需透過 Xcode 執行的 iOS 工作，便要安排 macOS 執行階段。官方的 KMP iOS 建置說明與託管 macOS Agent 的 iOS CI/CD 範例可用來核對這條平台邊界。
換句話說，Kotlin Multiplatform iOS 專案沒有 Mac，仍可先在現有 CI 驗證共享邏輯；但只要交付要求包含 iOS 建置、模擬器執行或 Apple 平台發布，就要另外安排 Mac 執行階段。不要把前者的綠燈當成整條 iOS 交付鏈已通過。
SECTION 02 環境控制：託管 macOS Agent 還是遠端 Mac？
兩者差異不在名稱，而在你能控制多少環境，以及團隊是否有能力承擔相應設定與維護。下表是選擇執行環境的工具，不代表任何一方必然更快或更穩定。
| 判斷指標 | 託管 macOS Agent | 遠端 Mac |
|---|---|---|
| 節點管理 | 由服務方案提供執行環境；需核對可用映像、工具鏈選項與使用限制 | 你可管理節點設定，但也要負責環境建立、變更與復原 |
| 工具鏈控制 | 適合先按平台提供的映像與工作流程試跑；可選版本及自訂程度要以當期文件為準 | 適合需固定設定或自行安排工具鏈的情況；仍須驗證 Xcode、macOS 與專案依賴相容 |
| 私有環境接入 | 先確認網路、權限與憑據流程是否符合團隊要求 | 可評估特定連線與環境需求，但不能假設所有私有網路或存取控制都已解決 |
| 維護責任 | 平台負責部分節點管理；工作流程、憑據與建置失敗仍要由團隊診斷 | 你需要規劃節點存取、系統更新、工具鏈維護與故障復原 |
| 適合的試跑方式 | 用標準流程驗證建置、測試與交付步驟 | 用自訂環境驗證固定工具鏈、節點控制及必要的接入條件 |
GitHub 的託管 Runner 官方限制說明列出其執行環境與使用條件；實際可用映像和限制可能隨服務文件更新，應以你採用方案的當期資料為準。需要自訂節點不代表一定要選遠端 Mac；先確認託管方案無法滿足的具體條件，再衡量自行維護是否值得。
對標準建置流程，先以託管 macOS Agent 驗證較容易分離「工作流程是否可行」與「是否需要管理節點」。若你已確定要固定環境、維持節點控制或接入特定私有環境，遠端 Mac CI 才有明確評估理由。單憑「託管」或「遠端」兩個標籤，不能推斷速度、穩定性或故障恢復能力。
SECTION 03 相容性里程碑：先用專案現有設定驗證工具鏈
在改動 CI 設定或升級工具前，以專案目前鎖定的設定建立基線。應逐項確認 Kotlin、Gradle、Xcode、macOS、iOS 目標及原生依賴的組合；不要根據某一項工具支援某個版本，就推定整個專案也相容。
Kotlin 官方多平台相容性指南用於核對 Kotlin Multiplatform 的相容資訊；Kotlin 版本更新時，應再查閱當前發布記錄。版本支援範圍要按發布方文件判斷，不能用團隊曾經成功建置的經驗替代官方相容要求。
Gradle 版本則應從專案的 Gradle Wrapper 設定確認。官方 Gradle Wrapper 說明指出，Wrapper 會依專案設定取得指定的 Gradle 發行版；這讓試跑能以專案設定為起點，而不是在 CI 節點上任意換用另一個版本。此設定仍不會替你驗證 Kotlin 外掛、Xcode 或原生依賴是否互相相容。
把試跑結果記錄為可回查的組合：提交版本、目標平台、Kotlin 與 Gradle 設定、Xcode 與 macOS 版本、關鍵原生依賴，以及建置與測試結果。若既有設定失敗，先分辨是平台要求、相容性衝突、節點環境差異，還是專案外掛或原生依賴問題，再決定要調整工作流程或更換執行環境。
SECTION 04 發布里程碑：建置成功不等於簽名與 TestFlight 已驗收
把「能建置」與「能交付」分成兩個驗收條件。iOS CI 可能已通過編譯和測試，但憑據管理、簽名、封存或上傳步驟仍可能未經驗證；因此，不要因為建置工作成功，就宣告 TestFlight 發布鏈路已完成。
Apple 的應用程式發佈準備說明與 App Store Connect 建置版本上傳文件可用於核對發佈準備與上傳流程。實際的簽名設定、憑據存放方式與審批流程，仍應依你的團隊政策與目前採用的 CI 方案確認。
在託管流程上，先核實憑據如何注入工作、哪些人能存取、發布是否需要審批，以及工作結束後如何處理敏感資料。如果這些控制符合團隊要求，便可在不自行維護節點的前提下驗收交付鏈。若流程不符合治理條件，再比較遠端 Mac 的存取隔離、憑據使用與清理方式；遠端節點本身不會自動替你完成安全治理。
提醒：試跑應分別記錄建置、測試、簽名和上傳結果。若只測過其中一段，請在交付狀態中明確標示尚未驗收的環節。
SECTION 05 維護里程碑：能否重現、診斷與恢復？
CI 長期可用與否，應由可核對的執行記錄判斷，而不是看單次成功或節點標籤。測試結果是否能取回、失敗是否有足夠日誌、重新執行是否能定位到同一提交，以及節點重啟後環境是否可恢復，都會影響團隊實際承擔的維護工作。
可按以下順序試跑：
- 固定基線：選定一個現有提交與明確的 iOS 目標，保留當時的 Wrapper 設定、Xcode 與 macOS 資訊。
- 先跑共享驗證：確認共享程式碼與通用測試仍可由既有環境執行，避免把不需要 Mac 的工作全部搬遷。
- 加上 Mac 工作階段：在候選執行環境執行 iOS 目標建置及所需測試，保存完整日誌和測試結果。
- 單獨驗收發布：按團隊的憑據與審批要求測試簽名及上傳；未完成的階段不要標記為交付成功。
- 測試失敗復跑與恢復：用同一提交和目標重跑，確認能否追查失敗原因、取回產物，並依方案實際驗證節點重啟後的恢復方式。
- 記錄變更與責任：寫明工具鏈升級由誰確認、節點或工作流程變更如何審核，以及失敗時由誰處理。
這套流程能讓託管 macOS Agent 與遠端 Mac CI 使用相同輸入比較，避免把環境不一致誤認成方案優劣。若遠端節點需要額外維護，也要把更新、權限、存取與復原工作列入責任清單；若採託管環境，也要確認服務文件與工作流程是否足以診斷失敗。
SECTION 06 成本與准入：按實際投入選擇或保留雙軌
不要在沒有任務量和當期方案資料時預填總成本，也不要把租用或託管的價格直接當成完整成本。比較時，至少要納入實際使用週期、工作數量、工具鏈維護時間、憑據治理投入，以及未來切換流程的成本。再把試跑中可觀察的維護工作和失敗處理記錄納入決策，而不是用假設的速度或穩定性補足空白。
可按條件作出選擇：
- 若工作流程標準、所需工具鏈可由託管方案提供，且測試、憑據與發布控制符合要求，先以託管 macOS Agent 驗證。
- 若固定工具鏈、節點控制或私有環境接入是明確需求，並且團隊能承擔維護，才評估遠端 Mac。
- 若關鍵發布環節尚未驗收，先保留小範圍雙軌，直到同一提交、同一目標與可追蹤產物的測試結果能支持決策。
- 若你只做共享邏輯驗證，暫時不必為此單獨配置 Mac CI；待 iOS 建置或 Apple 平台交付進入範圍，再安排 Mac 階段。
目前託管流程可涵蓋哪些環節、遠端 Mac 提供哪些實際配置與交付方式，都應在採用前查看當期資料，不宜把未核實的方案內容寫成成本結論。你可先透過方案資訊頁核對現行選項；若已確認專案需要固定的 macOS 工具鏈、可控執行節點或特定環境接入，再參考遠端 Mac 使用說明，按自己的流水線逐段試跑。
相較於單純沿用現有非 Mac 節點，這類工作可能需要額外處理 Apple 平台建置環境、工具鏈差異、簽名憑據和失敗後的恢復；但自行購買 Mac 也不一定適合短期試驗或需求未定的團隊。當你需要的是階段性驗證或特定期間的受控 Mac 環境，可把 VPSNIX 遠端 Mac 納入比較，再以實際工作流程和當期方案資料決定是否租用；若需要長期固定重負載，或依賴實體介面與本機設備，則應先比較自購設備是否更符合需求。
最後更新於 2026 年 10 月 18 日；平台要求與工作流程核對自 Kotlin Multiplatform 官方 CI/CD、iOS 建置及相容性文件，以及 GitHub 託管 Runner 和 Apple 發佈說明。方案可用性與內容請於採用前再次確認。