Buildkite Agent 遠端 Mac 怎麼部署？2026 Xcode 27 CI 指南

截至 2026 年 8 月 31 日，Apple 的 Xcode 27 仍以 Beta 工具鏈發布；因此，Buildkite Agent 遠端 Mac 部署可以做，但不應直接把它放進穩定生產佇列。請使用符合 Apple Xcode 27 Beta Release Notes 與官方系統要求的 Apple Silicon Mac，先驗證命令列建置，再逐步加入 Simulator、簽名及重啟恢復。

本週建議動作：先準備一個與生產環境隔離的遠端節點，建立專用 macOS 帳戶與 Queue，提交只輸出系統、架構及 Xcode 路徑的最小工作；在真實專案完成建置與測試前，不要宣稱節點已可上線。

這篇文章適合把 iOS 或 macOS 建置從本機電腦遷入 Buildkite 的開發者，也適合維護長期在線 CI 節點的 DevOps 工程師。若你正在隔離驗證 Xcode 27 Beta、同時保留穩定版生產流水線，下面的時間線可以幫你界定每個階段何時繼續、何時停止。

SECTION 01 動手前：Buildkite Agent 可以安裝在遠端 Mac 上嗎？

可以。Buildkite 官方確認，自託管 Agent 能安裝在 macOS，並由遠端主機主動向控制平面建立出站連線、領取工作；這不代表你需要為 Agent 任意開放入站連接埠。具體安裝方式與執行條件，應以 Buildkite macOS Agent 安裝文件為準。

先把三個角色分清楚：

• Buildkite 控制平面：管理 Pipeline、Cluster、Queue、工作狀態與權限。
• Agent 程式：在遠端 Mac 上接收工作、執行 Shell 指令並回傳日誌與狀態。
• 遠端 Mac：提供 macOS、Apple Silicon、Xcode、Simulator、鑰匙圈與專案工具鏈。

你還要先界定工作負載。純命令列編譯只需要非互動式 Shell 與穩定工具鏈；Simulator 或 UI 測試需要檢查使用者登入會話、模擬裝置及圖形環境；簽名與發布則會接觸私密金鑰、Provisioning Profile 與發行權限。把三者混在同一個無限制節點上，隱性風險會隨著佇列任務增加。

進入條件與停止條件

進入部署前，確認 Apple Silicon、macOS 版本及 Xcode 27 的要求都能在 Apple 文件中對應。若系統版本、架構或 Beta 已知問題不符合你的專案條件，應停止配置，改用隔離驗證節點；不要先註冊 Agent，再期待建置錯誤替你找出硬體邊界。

SECTION 02 第一個里程碑：建立專用帳戶與 Queue

Buildkite self-hosted agent 不應使用日常管理員帳戶執行。建立只供 CI 使用的 macOS 帳戶，將工作目錄、日誌目錄與憑證存取範圍分開；帳戶名稱、主機名稱、Queue 和 Token 在文件與命令中都使用佔位符。

依照 Buildkite 自託管 Agent 工作方式完成安裝後，按官方規則設定：

export BUILDKITE_AGENT_TOKEN="<AGENT_TOKEN>"
export BUILDKITE_AGENT_NAME="<REMOTE_MAC_NAME>"
export BUILDKITE_AGENT_TAGS="queue=<QUEUE_NAME>,arch=arm64,xcode=27-beta"

buildkite-agent start

上例只展示變數邊界，不是把真實 Token 寫入 Shell 歷史或 Pipeline 日誌。Token 應放在受控的設定檔或秘密管理流程中，並依 Buildkite Token 文件確認其作用範圍。Queue 路由則參考官方 Queue 設定說明，讓 Xcode 27 Beta 工作只落到隔離節點。

第一個工作不要立即拉取完整專案，可以先執行：

sw_vers
uname -m
xcode-select -p
xcodebuild -version

通過證據是日誌中能看見預期的 macOS、arm64、開發工具路徑及 Xcode 版本，而且工作確實由指定 Queue 的節點執行。若標籤遺漏、Queue 誤投或輸出與預期不符，停止後續配置，先修正路由。

SECTION 03 第二個里程碑：指定 Xcode 27 並完成首次建置

Buildkite 如何指定 Xcode 27 構建節點？不要依賴互動式 Shell 中偶然存在的 PATH 或 DEVELOPER_DIR。你應在 Pipeline 或步驟內明確指定工具鏈，並透過標籤限制 Agent：

steps:
  - label: "Xcode 27 build"
    agents:
      queue: "<QUEUE_NAME>"
      xcode: "27-beta"
      arch: "arm64"
    command:
      - 'export DEVELOPER_DIR="/Applications/<XCODE_27_APP>/Contents/Developer"'
      - 'xcodebuild -version'
      - 'xcodebuild -workspace "<WORKSPACE>.xcworkspace" -scheme "<SCHEME>" -destination "<DESTINATION>" build test'

<XCODE_27_APP>、Workspace、Scheme 與 Destination 都必須替換成你的實際值；不要把團隊憑證、Repository URL 或 Team ID 寫進公開範例。Apple 的系統與 SDK 要求頁面及 Xcode 27 Release Notes 是確認相容性與已知問題的依據，Beta 工具鏈的失敗不能直接歸咎於 Agent。

首次真實建置按以下順序取證：

1. 以專用帳戶取得 Repository，確認最小化讀取權限足夠。
2. 固定 Xcode 路徑，輸出 xcodebuild -version。
3. 執行依賴解析，記錄解析失敗與退出碼。
4. 編譯真實專案，再執行單元測試。
5. 檢查 .xcresult、Archive 或其他產物是否在預期目錄。
6. 清理工作區後重跑，確認結果不是沿用舊的 DerivedData。

若專案需要私有套件，優先使用可輪換的機器身分或平台級金鑰，不要把個人 SSH 金鑰長期留在 Agent 帳戶。Buildkite 對程式碼存取與認證方式有獨立說明，應按照 Repository 的實際權限模型配置。

SECTION 04 第三個里程碑：自託管 Mac 能執行 iOS Simulator 測試嗎？

可以，但要把它視為另一個驗收階段，而不是命令列建置的自然延伸。自託管 Mac 執行 iOS Simulator 測試時，Agent 所屬使用者會話、Simulator Runtime、模擬裝置可見性及圖形登入狀態都可能影響結果；純編譯節點不應無條件增加桌面會話複雜度。

先確認 Pipeline 是否真的需要 UI 測試或 Simulator。需要時，再在遠端 Mac 上：

xcrun simctl list devices
xcrun simctl list runtimes
xcodebuild -showsdks

接著用一個最小測試驗證四件事：模擬器能否啟動、測試能否執行、結果檔能否收集、測試後裝置與程序能否清理。這裡的通過只表示模擬環境可用，不等於真機測試、推送驗證或發布流程已完成。

如果 Agent 在登入桌面後才能看到模擬裝置，便要把「使用者會話恢復」列入重啟驗收；不要只在手動登入的螢幕前測試一次，就把節點標記為無人值守可用。

SECTION 05 第四個里程碑：把簽名與發布從普通工作隔離

Buildkite Agent 如何隔離 Apple 簽名證書？最穩妥的做法不是只加一個標籤，而是將普通 Pull Request 建置與簽名發布拆到不同 Queue、帳戶或受控步驟。一般程式碼變更不應直接讀取生產私密金鑰。

部署發布步驟前，逐項驗證：

• 登入的鑰匙圈是否是 CI 專用，而非個人預設鑰匙圈。
• 私密金鑰是否只授權給必要的建置工具。
• Provisioning Profile 是否與 Bundle ID、Team ID 和配置一致。
• 非互動式 Shell 是否能完成解鎖與簽名。
• 發布工作是否只能由受保護分支或人工核准觸發。

Apple 的Code Signing 官方討論與文件入口可用來核對簽名錯誤的處理方向。證書名稱、密碼、Team ID 及 Repository 資訊在文章、命令和日誌範例中一律使用佔位符。

單節點並發也要實測。兩個工作若同時寫入相同 DerivedData、Simulator 或鑰匙圈，可能造成互相清理、鎖定或簽名失敗；在沒有隔離證據前，先將簽名工作設為串行，不要因為 Agent 顯示在線就立即增加 Agent 程序。

SECTION 06 第五個里程碑：讓重啟後的 Agent 自動上線

Buildkite macOS Agent 重啟後怎麼自動上線？要把 Agent 設為由 launchd 管理的常駐工作，並在受控重啟後驗證完整鏈路。Buildkite 的 macOS 安裝文件提供執行方式；Apple 的 launchd 工作建立文件則是確認啟動代理、執行帳戶與載入行為的官方依據。

部署時不要只檢查程序是否存在，應依序觀察：

1. 遠端連線是否恢復，專用帳戶是否能正常使用。
2. 需要圖形測試時，使用者會話與 Simulator 是否恢復。
3. launchd 是否載入正確的 Agent 工作設定。
4. Agent 是否重新出現在指定 Cluster 與 Queue。
5. 真實建置是否能領取、完成並回傳產物。
6. 日誌、工作區與磁碟使用量是否維持可控狀態。

若某一步失敗，保留穩定工具鏈節點作為回滾入口；不要在沒有日誌與恢復路徑的情況下重裝 Agent、刪除鑰匙圈或大範圍清理工作區。破壞性清理前，先說明會刪除哪些資料、是否影響其他 Queue，以及如何重新載入設定。

SECTION 07 上線前的可勾選驗收清單

• [ ] Apple Silicon、macOS 與 Xcode 27 的要求已對照官方文件確認。
• [ ] Xcode 27 Beta 節點未與穩定版生產節點共用未隔離的 Queue。
• [ ] Agent 使用專用 macOS 帳戶，Token 沒有出現在命令或建置日誌。
• [ ] 最小工作能輸出系統、架構、開發工具路徑與 Xcode 版本。
• [ ] 真實專案已完成依賴解析、編譯、單元測試及結果檔收集。
• [ ] Simulator 測試已驗證啟動、執行、收集與清理；若不需要，已明確停用。
• [ ] 普通建置無法直接讀取生產簽名資產。
• [ ] 單節點並發已測試；沒有隔離證據時，簽名工作維持串行。
• [ ] 受控重啟後，Agent、Queue、真實建置與產物回傳全部恢復。
• [ ] 已安排日誌輪替、工作區清理、Agent 更新與 Xcode 版本固定責任。

SECTION 08 方案判斷：哪一種節點適合進入生產？

如果你目前使用的是本機 Mac mini，長期在線、硬碟清理、遠端恢復和硬體維護都由團隊自行承擔；若改用一般 Linux 雲主機，則無法直接提供 Xcode、macOS SDK、Apple Silicon 或完整簽名工具鏈。即使採用虛擬化方案，也可能遇到圖形會話、工具鏈相容性和維護邊界。對於只想隔離驗證 Xcode 27、短期增加建置節點或暫時承接 macOS CI 的團隊，租用 VPSNIX 的遠端 Mac 會比臨時購買硬體更容易控制投入；你可以先依本文清單核對節點，再查看 VPSNIX 的方案與租用週期。

這不是所有情況都適合租用：若你需要長期穩定的高負載、實體 USB 裝置或完全掌控硬體生命週期，自購 Mac 可能更合理；但現有 Linux 方案的主要限制是不能原生執行 Xcode，臨時本機方案則受開機狀態、遠端恢復與單一使用者環境牽制。當你的目標是先驗證 Xcode 27 流水線，再決定是否擴充生產容量，使用 VPSNIX 的遠端 Mac 作為隔離節點，通常能以較小的承諾完成 Buildkite Agent、Simulator、簽名和重啟恢復的實際驗收；需要時可從繁體中文服務入口開始評估。