Kotlin Multiplatform 哪些 iOS 工作一定要放在 macOS 執行？

Kotlin 共用模組的部分靜態檢查與非 Apple 目標工作可以留在 Windows 或 Linux；涉及 iOS Framework、iosArm64、iosSimulatorArm64、Apple 模擬器、Xcode 工程、簽署憑證及 Archive 的工作，則應放在 macOS。實際分界要以建置輸出和 Xcode 命令列結果驗證。

Kotlin 2.4.10 iOS 建置：2026 遠端 Mac CI 怎麼部署

Q: 沒有本地 Mac，還能建置 Kotlin Multiplatform 的 iOS 應用程式嗎？

可以，但 Windows 或 Linux 應只負責共用程式碼、Gradle 檢查與一般開發；iOS Framework 整合、Apple 模擬器、Xcode 測試、簽署和 Archive 必須路由到具備完整 Xcode 的真實 Mac。先用全新複製的儲存庫驗證，確認不依賴本地路徑或互動式設定。

Q: 遠端 Mac 生成 Kotlin XCFramework 後，要怎樣確認產物真的可用？

不要只看 Gradle 成功。你應同時保存 Gradle 任務結果、XCFramework 內的目標架構清單、Xcode 匯入結果和可重複生成記錄，並分別在裝置與模擬器流程中驗證。修改共用程式碼後，iOS 工程必須能取得新 Framework，才算完成閉環。

Q: Kotlin Multiplatform iOS 專案怎樣接入 CI 自動歸檔？

把依賴解析、Kotlin Framework 建置、Xcode 測試、Archive 和匯出拆成獨立階段，每階段列明輸入、輸出與停止條件。CI 使用固定 Scheme、工作目錄和簽署環境，憑證與描述檔不進入儲存庫或一般日誌；最後以無人工點擊完成 Archive 和產物校驗作為驗收。

Q: Kotlin iOS 建置節點應該快取哪些 Gradle 和 Xcode 檔案？

先分開觀察 Gradle 依賴、Kotlin/Native 快取、Xcode Derived Data 和套件依賴的命中情況，再決定保留策略。快取不能取代乾淨建置驗證，也不能讓不同專案共用同一工作目錄。每個工作應使用隔離路徑，並定期以全新目錄重跑。

這篇文章面向以 Windows 或 Linux 為主力環境的 Kotlin Multiplatform 開發者與 DevOps 工程師。你會取得一套以場景劃分的遠端 Mac CI 部署方法，涵蓋 Framework、模擬器、Xcode 測試、簽署歸檔、快取隔離與節點恢復驗收。

截至 2026 年 8 月 27 日，Kotlin 官方文件列出的 iOS 目標至少要分辨 iosArm64 與 iosSimulatorArm64；這個架構差異已足以說明：Windows 或 Linux 可以承擔共用程式碼開發，但 iOS Framework 整合、模擬器驗證、Xcode 測試與最終 Archive，應交給安裝完整 Xcode 的真實 Mac。Kotlin/Native 目標支援文件

本週建議動作：先建立一個只路由 iOS 工作的遠端 Mac 節點，以全新複製、Framework 產物、測試結果、Archive 和重啟恢復五類證據完成小型驗收；不要一開始就把整個桌面環境或所有 CI 工作搬過去。

這篇文章適合三類人：

以 Windows 或 Linux 為主力環境，卻要交付 Kotlin Multiplatform iOS 應用程式的開發者；
準備把 Kotlin/Native 與 Xcode 建置接入 CI 的移動 DevOps 工程師；
需要管理共享遠端 Mac、簽署憑據、快取與並發工作的研發平台負責人。

先劃清 Windows、Linux 與遠端 Mac 的責任邊界

主力系統適合保存共用原始碼、執行一般 Gradle 檢查、處理分支與程式碼審查；遠端 Mac 則應被視為獨立的 Apple 建置出口，而不是把 Windows 或 Linux 的整個桌面搬到雲端。

建議把工作流拆成以下資料流：

原始碼與建置參數：由 CI 從指定提交複製到隔離工作目錄，不能依賴開發者電腦上的絕對路徑。
共用模組：在遠端 Mac 生成 Kotlin Framework 或 XCFramework，並留下任務輸出與架構資訊。
Xcode 工程：只接收已明確產生的 Framework，透過固定 Scheme 和設定檔執行測試與 Archive。
快取：Gradle、Kotlin/Native、Xcode Derived Data 和套件依賴分開管理，避免一個專案的狀態污染另一個專案。
最終產物：Archive、匯出檔、測試報告和 xcresult 必須上傳至 CI 產物區，而不是只留在遠端 Mac 硬碟。

最有用的邊界測試不是「開發者本機能否編譯」，而是全新複製後能否進入 Apple 建置階段。若流程需要手動開啟 Xcode、修改本地路徑或重新選取 Scheme，代表 CI 尚未具備可重現性。

Kotlin 2.4.10 iOS 建置的部署選擇與評分

你可以先按團隊的儲存庫結構和交付方式選擇整合形態，再決定遠端 Mac 的 CI 路由。不要先選工具，之後才被工具的目錄結構牽著走。

選項	適合情況	主要輸入與產物	CI 風險	建議評分
直接整合 Framework	iOS 工程與共用模組同一儲存庫，追求路徑簡單	Gradle 任務、Framework、Xcode Scheme	本地路徑或 Build Phase 寫死後難以搬遷	4/5
CocoaPods 整合	團隊已有 Pod 結構，需由既有工作流管理依賴	Pod 設定、Framework、Xcode 工程	依賴解析與生成步驟未固定時，乾淨節點容易失敗	3/5
XCFramework 分發	共用模組要供多個 iOS 工程或團隊使用	多目標 XCFramework、版本化產物	架構漏打包、產物版本與原始碼不同步	4/5
遠端二進位依賴	需要把建置與消費端分離，並已有產物儲存方案	已驗證二進位檔、校驗資料、版本標記	下載來源、校驗與回滾設計不完整	3/5

這裡的評分是部署判斷工具，不是效能測試分數。若你只有一個工程且需要快速建立第一條流水線，直接整合通常較容易定位；若同一個共用模組要交付多個工程，XCFramework 的邊界更清楚。Kotlin 官方對 Native binary 的輸出方式與 Framework／XCFramework 建置有明確說明，應以其任務與輸出定義作為腳本依據。官方 Native binary 建置文件

共享模組的 Framework 與 XCFramework 驗收

裝置、模擬器與分發產物不是同一件事

iosArm64 應對應實體 iOS 裝置流程，iosSimulatorArm64 則對應 Apple Silicon Mac 上的模擬器流程。這不是「一個目標成功，其他目標自然可用」的關係；每個目標都要有自己的任務結果和產物證據。Kotlin Multiplatform iOS 整合概覽

部署時至少保存四項資料：

Gradle 執行的任務名稱、提交識別和退出結果；
Framework 或 XCFramework 的目錄清單與目標架構；
Xcode 工程匯入後的編譯結果；
相同提交在乾淨目錄再次生成時的差異記錄。

如果只需要同一儲存庫內的 iOS 工程使用，直接輸出 Framework 可以減少分發層；如果需要交給其他工程或其他團隊，XCFramework 更適合，因為它能把多個 Apple 目標包在同一個可分發產物中。這個選擇應由消費端數量、版本管理和產物保存方式決定，而不是由單次建置是否成功決定。

第二步：讓 Xcode 取得「新」Framework

在 CI 中加入一個閉環檢查：修改共用 Kotlin 程式碼中的可辨識輸出，重新生成 Framework，再由 Xcode 工程編譯並執行對應測試。若 iOS 工程仍取得舊產物，常見原因包括：

Build Phase 指向開發者本機路徑；
Gradle 任務沒有被 Xcode Scheme 呼叫；
Derived Data 保留了舊 Framework；
XCFramework 產物名稱固定，但內容沒有提交識別；
CI 只執行 Xcode，而沒有先完成 Kotlin/Native 建置。

若你使用 Swift Package Manager 匯出 Kotlin Framework，請把套件生成、路徑和版本化產物納入可重複流程，並對照Kotlin 官方的 SPM 匯出說明。驗收條件不是工程能否在某台 Mac 開啟，而是全新工作目錄能否自動取得正確產物。

注意：遠端 Mac 適合承擔可腳本化的建置和測試，但不要把「能透過 VNC 點開 Xcode」當成 CI 就緒證據。互動式圖形除錯、模擬器狀態和自動化建置是不同驗收項目。

測試場景要分層，失敗才找得到責任方

Kotlin Multiplatform 專案的測試失敗，不能只看最後一個 Xcode 退出碼。你應把測試分成三層：

Common 測試：驗證共用業務邏輯，優先由主力系統或一般 Gradle 工作處理。
Kotlin/Native 測試：驗證 Apple 目標上的原生互操作、記憶體行為和平台實作，必須在遠端 Mac 的對應目標上執行。
Xcode 測試：驗證 iOS 工程、Framework 匯入、Scheme、模擬器或實體裝置流程，失敗時要回看 Xcode 建置設定與 Apple 平台環境。

模擬器驗證要同時確認執行時、目標架構和圖形工作階段。遠端節點即使能完成命令列編譯，也不代表一定適合長時間互動式除錯；因此 CI 應優先保存機器可讀的測試結果、日誌和 xcresult，讓平台負責人能在沒有即時螢幕的情況下重現失敗。Apple 的Xcode 建置與執行文件可用來核對 Scheme、目的地和建置流程。

第三步：把 Archive、簽署與發布拆成可停止的階段

一條可維護的 Xcode CI，不應是一個「建置並上傳」的黑盒命令。建議按以下順序設計，每一階段都有明確停止條件：

依賴解析：鎖定儲存庫提交、套件版本與工具鏈，解析失敗時停止，不進入簽署階段。
Framework 建置：完成必要的 Kotlin/Native 目標，檢查產物名稱、架構和提交識別。
Xcode 測試：固定 Scheme 與目的地，保存測試日誌和 xcresult；測試失敗時不得產生可發布 Archive。
Archive：使用非互動式 xcodebuild 流程，指定工作區、Scheme、輸出位置與簽署設定。
匯出與校驗：檢查 Archive 內容、Bundle 識別、簽署狀態和匯出產物，任何一項不符就回滾到上一個可用產物。

命令中的儲存庫、路徑、Scheme、Team ID、憑證和金鑰都應使用環境變數或 CI 秘密管理，不能直接寫入腳本。Apple 提供的建置分發工作流文件可作為 Archive 和分發階段的核對依據；簽署所需的環境變數也應參照Apple 的 Xcode 環境變數說明。

簽署帳戶、憑證、描述檔和金鑰要與日常開發帳戶隔離。CI 日誌中應遮罩秘密值，並限制遠端 Mac 的登入權限；發布權限不應因為建置節點擁有 root 權限而自動擴大。最終驗收是無人工點擊完成 Archive、匯出和產物校驗，失敗後能保留前一份可追溯產物，而不是讓工程師登入桌面手動補救。

共享遠端 Mac 的快取、並發與恢復設計

快取是降低重複工作的手段，不是穩定性的替代品。你應分開處理：

Gradle 依賴快取；
Kotlin/Native 編譯快取；
Xcode Derived Data；
Swift Package 或 CocoaPods 依賴；
CI 產物與 Archive 保存區。

先在日誌中記錄快取命中或失效，再決定哪些快取可以跨工作保留。Derived Data 若被不同提交或不同工程混用，可能讓舊 Framework 掩蓋新程式碼；因此至少要按工程、分支或提交建立隔離規則。對於無法判斷來源的失敗，先以乾淨工作目錄和清理後建置重跑，不要直接把問題歸因於 Kotlin 版本。

共享節點還有三個容易被忽略的爭用點：

不同任務寫入相同工作目錄，導致產物互相覆蓋；
多個任務同時操作同一模擬器，造成狀態和測試資料污染；
多個簽署任務共用同一組暫存金鑰或描述檔，讓失敗難以追蹤。

你可以在 CI 路由中用標籤把 iOS 任務送至指定 Mac，並將一般 Linux 工作排除；若採用自託管 Runner，應參照官方 Runner 標籤管理文件設計路由規則。若節點本身需要調整硬體或存取方式，可先查看VPSMAC 的技術支援頁面，不要把節點設定直接寫死在專案腳本中。

第四步：用故障注入決定能否長期承載 CI

至少執行以下恢復驗收：

建置進行中斷開 SSH，確認工作是否由 CI 控制而非依賴終端機；
重啟遠端 Mac，確認 Runner 能重新上線或被重新調度；
以新的工作目錄重新複製同一提交；
重新生成 Framework、執行 Xcode 測試並產生 Archive；
檢查失敗前後的日誌、產物識別和簽署狀態是否仍可追蹤。

如果重啟後只能靠人工登入、快取遺失便無法建置，或同一節點的兩個專案會互相改寫檔案，就不應把它標記為穩定 CI 節點。你可以先以短期租用方式驗證這條恢復路徑，再決定是否建立長期節點；VPSMAC 提供的遠端 Mac 節點選項可作為評估入口，但實際配置仍應以你的建置腳本和簽署需求驗收。

上線前的證據清單與退出條件

把以下結果保存到 CI 產物區，才足以證明部署不是「某次剛好成功」：

全新複製後的依賴解析記錄；
iosArm64 和 iosSimulatorArm64 對應任務的結果；
Framework／XCFramework 的目標架構與提交識別；
Kotlin/Native 測試、Xcode 測試和 xcresult；
Archive、匯出檔及簽署校驗結果；
快取命中資訊與清理後重跑結果；
斷線、重啟、重新調度及新工作目錄重跑記錄。

任何一項缺失時，退出條件應是「暫不投入發布用途」，而不是先放行、日後再補文件。Kotlin 官方版本與 iOS 整合文件、Apple Xcode 大版本或建置方式若有變動，應重新執行整套驗收；不要把預發布版本的行為當成 Kotlin 2.4.10 穩定版本的既定能力。

常見問題

沒有本地 Mac，還能建置 Kotlin Multiplatform 的 iOS 應用程式嗎？

可以，但不能把所有工作都留在 Windows 或 Linux。共用程式碼和部分 Gradle 檢查可在主力系統完成，涉及 Apple Framework、模擬器、Xcode 測試、簽署與 Archive 的階段，應由具備完整 Xcode 的真實遠端 Mac 執行，並以全新複製流程驗證路徑獨立性。

Kotlin Multiplatform 哪些 iOS 工作一定要放在 macOS？

只要工作需要 Apple SDK、iOS 模擬器、Xcode 工程或簽署資源，就應放在 macOS。iosArm64 和 iosSimulatorArm64 也不應被視為同一目標；裝置和模擬器要分別生成、測試並保存結果，否則單一架構成功不能代表 iOS 交付完成。

遠端 Mac 生成 Kotlin XCFramework 後，要怎樣確認產物真的可用？

先確認 Gradle 任務成功，再檢查 XCFramework 的目標架構和提交識別，接著由 Xcode 工程實際匯入與測試。最重要的閉環是修改共用模組後重新生成，iOS 工程能在乾淨工作目錄取得新 Framework；只看檔案存在或命令退出碼都不足夠。

Kotlin Multiplatform iOS 專案怎樣接入 CI 自動歸檔？

將依賴解析、Framework 生成、Xcode 測試、Archive 和匯出分成獨立工作階段，為每階段設定輸入、產物和停止條件。Scheme、路徑和 Team ID 由環境變數提供，簽署秘密放在 CI 的秘密管理機制中；沒有測試結果或產物校驗時，不應進入發布階段。

Kotlin iOS 建置節點應該快取哪些 Gradle 和 Xcode 檔案？

Gradle 依賴、Kotlin/Native 快取、Xcode Derived Data 和套件依賴應分開觀察與隔離。先保存命中證據，再決定是否跨任務保留；對不同工程使用不同工作目錄，並用清理後建置與全新複製定期檢查快取沒有掩蓋依賴、架構或 Framework 版本問題。

目前以 Windows 或 Linux 雲端主機作為唯一建置環境，會遇到 Apple SDK 缺失、Xcode 工程無法原生驗證、模擬器與簽署資源不可用等限制；即使以虛擬化方式繞過其中一部分，也容易增加圖形工作階段、權限和恢復流程的維護成本。對已能在主力系統完成共用程式碼開發、只是缺少穩定 Apple 出口的團隊，租用 VPSMAC 的真實遠端 Mac，先跑通全新複製、Framework、Xcode 測試、Archive 和重啟恢復，通常比立即購置並長期維護一台 Mac mini 更適合驗證需求；通過驗收後，再決定是否轉為長期 CI 節點。