CircleCI Machine Runner 3 遠端 Mac 部署的本週建議是：只有在你需要固定 Xcode 環境、內網依賴或簽名憑證控制時才部署自託管 Runner；標準化、無需控制主機環境的任務，繼續使用 CircleCI 的託管執行器。上線前不要只看 Runner 顯示 Online，必須完成任務路由、Xcode 建置、重啟恢復與工作區清理驗收。

這篇文章適合三類讀者：

  • 維護 CircleCI iOS 或 macOS 流水線、需要固定工具鏈的開發者。
  • 要把簽名、私有儲存庫或內網服務接入 CI 的 DevOps 工程師。
  • 負責遠端 Mac 權限隔離、更新與故障恢復的平台維護者。

最後更新於 2026 年 8 月 29 日；部署模型、macOS 支援、設定欄位與排障步驟核實自 CircleCI Runner 官方概覽、Machine Runner 3 設定參考 及 Apple 官方 Xcode 文件。若官方安裝包、設定格式或支援狀態變更，本文的驗收結果也需要重新確認。

01

先判斷：你的流水線是否真的需要遠端 Mac

Machine Runner 3 會直接使用註冊主機已有的作業系統、工具鏈、檔案權限與網路環境。它不是把普通 Linux 工作搬到另一個執行器，而是讓 CircleCI 任務進入你管理的真實 macOS 主機。這個執行模型可參考 CircleCI 自託管 Runner 工作方式。

適合遷移的任務包括：

  • 必須使用指定 Xcode 版本、Apple SDK 或 macOS 專屬工具的建置。
  • 需要存取公司內網、私有套件來源或內部 API 的測試。
  • 需要由你控制簽名憑證、描述檔與 Keychain 存取範圍的發布流程。
  • 需要固定的 macOS 建置節點，而不是每次重新準備環境。

不適合直接遷移的任務包括：

  • 純粹的格式檢查、文件產生或與 macOS 無關的單元測試。
  • 不需要固定工具版本，也不接觸私有網路或簽名資料的工作。
  • 團隊沒有能力處理主機更新、磁碟清理、帳戶權限和故障恢復的任務。

你的選擇可以按以下條件執行：

  • 若任務需要 Xcode、Apple SDK 或 macOS 專屬工具，選遠端 Mac 自託管節點。
  • 若任務需要簽名或內網存取，但一般測試不需要，採用託管執行器加遠端 Mac 的雙軌流水線。
  • 若任務只使用通用編譯器與測試工具，回退到託管執行器，避免增加主機維護負擔。
  • 若一台主機同時承接測試與發布，先拆分 resource class；否則回退到只承接無簽名測試的隔離節點。

這樣做能避免三種隱性成本：主機長期在線卻沒有任務、快取或工作區污染造成偶發失敗，以及低權限邊界不清導致簽名資料暴露。即使 CircleCI Runner 平台確認支援 macOS，實際可用性仍取決於節點上的使用者、工具鏈與檔案權限。

02

第一階段：建立 namespace、resource class 與低權限帳戶

開始前先準備一台可持續管理的真實 Mac，並為 Runner 建立獨立 macOS 帳戶，例如 <runner-user>。不要使用日常管理員帳戶，也不要讓 Runner 直接共用你的登入工作階段。

帳戶規劃可按以下範圍切開：

  • <workspace-path>：只放當次工作的原始碼與中間產物。
  • <cache-path>：只放可重新產生的套件或編譯快取。
  • <log-path>：只保留 Runner 與工作紀錄，不放憑證。
  • <signing-path>：若流程需要簽名，使用更嚴格的 Keychain 與檔案權限。
  • <private-dependency-path>：私有依賴的暫存位置，任務結束後清除。

接著在 CircleCI 管理介面建立 <namespace>，再建立與節點用途對應的 <resource-class>。resource class 的作用是把指定工作路由到符合條件的自託管節點，具體欄位與命名規則應對照 官方 resource class 說明。

權杖只放在受限的設定位置，使用 <runner-token> 這類佔位符。不要把真實權杖寫進儲存庫、.circleci/config.yml 或建置紀錄。部署完成後要記下保存位置、輪換入口和撤銷入口。若權杖曾出現在公開紀錄，先撤銷，再建立新的註冊流程。

03

第二階段：依官方 macOS 流程安裝 Machine Runner 3

安裝時不要直接套用搜尋結果中的舊指令。CircleCI 可能調整安裝包、簽名方式、設定檔欄位或啟動方法；請逐行對照當天的 Machine Runner 3 macOS 安裝指南。

可依以下順序執行：

  1. 以 <runner-user> 登入遠端 Mac，確認主機名稱、磁碟空間、網路出口和時間設定符合你的平台規範。
  2. 依官方文件下載並安裝 Machine Runner 3，不自行替換下載來源或重新封裝執行檔。
  3. 若 macOS 對下載程式提出簽名、公證或隔離檢查，先確認檔案來源與雜湊，再按官方指示處理，不要以關閉整體安全機制代替驗證。
  4. 建立 <workspace-path>、<log-path> 等目錄，將擁有者設定為 <runner-user>，避免用管理員權限執行建置。
  5. 寫入節點名稱、<namespace>、<resource-class>、工作目錄與 <runner-token> 等設定欄位；欄位名稱以官方設定參考為準。
  6. 啟動 Runner 後，同時檢查本機程序、Runner inventory、CircleCI 控制台狀態與本機紀錄。
  7. 若只在控制台看到 Online，卻沒有本機程序或持續更新的紀錄，停止後續建置，先處理註冊、權杖或權限問題。

Apple 的 Command Line Tools 也必須由執行帳戶可用。先依 Apple 安裝 Command Line Tools 的文件 安裝或確認工具，再依 Apple 的命令列工具選擇方法 檢查目前選用的 Xcode 或工具目錄。這裡的重點不是「已安裝 Xcode」，而是非互動式工作能否找到正確工具。

04

第三階段：讓 resource class 路由到正確的 macOS 建置節點

CircleCI self-hosted runner 的註冊完成後，先不要接入正式發布工作。建立一個可丟棄的最小專案，讓它只做以下驗證：

  • 印出目前工作目錄與執行使用者。
  • 輸出 Xcode 和 Command Line Tools 的選用狀態。
  • 執行一次不含簽名的建置或測試。
  • 將退出狀態、建置結果包和完整工作紀錄保存到指定位置。

在設定檔中以 <namespace>/<resource-class> 指向節點。不要只用「macOS」這類過於寬泛的名稱，否則日後增加不同 Xcode 或不同權限節點時，很難判斷任務到底落在哪一台主機。

CircleCI 自託管 macOS Runner 的 resource class 應如何設計

每一個 resource class 都應對應清楚的運維邊界，例如：

  • <namespace>/macos-build：只做無簽名編譯和測試。
  • <namespace>/macos-signing：只給發布流程使用，限制可接觸的憑證。
  • <namespace>/macos-private-network：只允許需要內網依賴的任務。

驗證時觀察三項證據：工作紀錄顯示的執行主機、節點 inventory 中的工作狀態，以及遠端 Mac 本機的工作目錄變化。三者不一致時，不要把任務結果視為路由成功。

05

第四階段：讓 Xcode CI 在非互動工作中穩定執行

CircleCI 自託管 Runner 怎麼呼叫 Xcode，關鍵不是在工作中臨時安裝所有工具，而是先把工具鏈版本和執行帳戶固定下來。Xcode CI 的最小驗證應先不含簽名，避免把工具問題和憑證問題混在同一次失敗中。

請依時間線檢查：

  • Xcode 命令列工具指向預期的開發者目錄。
  • <runner-user> 能讀取專案、套件管理器資料夾與必要的腳本。
  • 私有依賴的認證不會依賴你的互動式登入工作階段。
  • 工作目錄可在任務結束後清除，結果包則保存到獨立位置。
  • 建置程序不等待螢幕上的對話框、Keychain 解鎖提示或滑鼠操作。

若最小專案成功，再加入實際專案的依賴解析、編譯和測試。每次只新增一類變更，保留退出狀態與紀錄。這能區分 Xcode 選用錯誤、私有依賴連線失敗、權限不足和專案本身的建置錯誤。

06

第五階段：把簽名憑證與發布任務隔離

簽名任務不應與普通測試共用同一個 resource class。較穩妥的做法是將編譯、測試、封裝和發布拆成不同工作，並讓只有發布工作可以進入 <namespace>/macos-signing>。

需要檢查的權限邊界包括：

  • Runner 執行帳戶是否能讀取不必要的憑證或描述檔。
  • 憑證是否只在簽名工作期間進入指定 Keychain。
  • 建置紀錄是否可能輸出密碼、權杖或私有儲存庫網址。
  • 任務失敗時，暫存簽名檔案是否仍留在工作區。
  • 具備簽名權限的節點是否仍承接一般外部貢獻者工作。

簽名方式要按照 CircleCI 當日支援狀態與你現有的團隊流程選擇。本文不放入真實憑證名稱、Apple 帳戶、權杖或 Keychain 密碼。任何破壞性清理、權杖撤銷或服務重裝，都應先確認恢復通道，並保留可重新註冊節點的設定資料。

07

第六階段：重啟、清理與連續任務驗收

遠端 Mac 重啟後，CircleCI Runner 如何自動恢復，不能靠推測。完成官方啟動設定後，執行一次計劃內重啟，依序觀察：

  1. <runner-user> 能否正常登入或啟動必要的背景工作。
  2. Runner 本機程序是否重新出現，紀錄是否持續寫入。
  3. 控制台 inventory 是否重新顯示可接任務狀態。
  4. 新工作是否能透過同一 resource class 被領取。
  5. Xcode 是否仍能被非互動式工作呼叫。
  6. 上一次中斷任務留下的工作區、快取和結果包是否按策略處理。

重啟成功不代表節點已經能上線。還要測試連續任務、並發排隊、失敗後重跑、快取污染、紀錄保留和權杖輪換。若任務卡在佇列，先查看 CircleCI 自託管 Runner 排障文件，再檢查 官方連線問題排查說明。

你的上線判定可以很直接：

  • 若路由、無簽名 Xcode 建置、重啟後重新接任務及工作區清理全部成功，才進入小範圍生產試跑。
  • 若只有 Runner Online 成功，其他任一項失敗，維持測試狀態，不接發布任務。
  • 若簽名或內網任務失敗，先縮小權限和 resource class 範圍，不要用提高帳戶權限來掩蓋問題。
  • 若重啟後無法恢復，保留失敗紀錄，修正啟動方式後重新執行完整驗收。
08

遠端 Mac 與本地方案的取捨

本地 Mac 的優點是螢幕操作直接、實體介面在手邊，適合需要 USB 裝置或人工除錯的團隊。但把它長期當成 macOS 建置節點，常見缺點也很具體：辦公室網路中斷會讓流水線停擺；休眠、登出或系統更新可能中斷任務；簽名資料與日常開發環境混在一起，清理和權限稽核更困難。

若你需要固定的 macOS 建置節點，但不想先購買和維護另一台實機，可以先閱讀 遠端 Mac 的 Xcode CI 驗收方案，再按專案週期試部署。若團隊正在比較自購硬體與按期使用，也可參考 Mac mini 遠端租用方案。

完成最小流水線後，如果你仍缺少可持續運作的真實 Mac，VpsMesh 的遠端 Mac 可作為隔離試部署節點：先執行無簽名測試，再做重啟和工作區清理驗收，通過後才把發布任務遷移過去。相較於把本地 Mac 長期暴露在 CI 連線、更新和清理風險中，按專案週期租用遠端主機更適合短期驗證、版本遷移或需要固定 macOS 工具鏈的團隊；但若你長期承受穩定的高負載，或必須接觸實體 USB 裝置，本地自有硬體仍可能更合適。