TeamCity Mac 建置代理怎麼部署？2026 企業實施指南

症狀：代理已安裝，TeamCity 卻沒有可用的 Mac 建置節點。
最快解法：JetBrains 將代理連線與授權列為不同狀態，必須分開核對；完成 Mac 端安裝後，再確認連線、授權、Xcode 能力及代表性建置，四項都通過才算部署完成。TeamCity 官方文件說明代理連線與授權狀態

這篇適合需要規劃 TeamCity macOS 建置容量與主機接入方式的企業 IT 負責人。
TeamCity 管理員可依步驟檢查代理設定、授權狀態、建置需求及工作路由。
平台工程師可用文中的驗收流程，確認 Mac 上的 Xcode 建置確實可執行。

里程碑：先確認 Mac 代理部署選項與故障位置

安裝程式完成，不等於代理已經連上 TeamCity Server；代理在線，也不代表它已獲准接單，或符合特定建置設定的要求。若直接從「代理在線」跳到「部署完成」，常見結果是工作排隊、轉派到其他節點，或建置時才發現工具鏈不符。

先依團隊的主機管理方式選擇部署路徑。無論選哪一種，代理安裝目錄、執行帳號、網路連通及啟動方式都需要納入維運紀錄。

比較選項時，別只看取得主機的方式。至少要核對三類隱性成本：主機由誰維護與更新、建置期間是否需要圖形使用者工作階段，以及故障時誰能取得 Mac 端日誌。若工作依賴特定使用者環境或圖形工作階段，無人登入時的啟動結果可能與手動測試不同，必須用實際執行方式驗證。

里程碑：代理沒有連上 Server 時，回到連線設定逐項核對

TeamCity 建置代理怎麼安裝到 Mac 上？

在目標 Mac 上取得與 TeamCity Server 配合使用的代理套件，按官方安裝說明完成代理目錄及相關設定。先確認代理設定檔中的 Server 位址、代理名稱和認證資訊，再啟動代理；不要把安裝完成訊息當成成功接入的證據。JetBrains 代理安裝文件及代理安裝設定說明可用來核對當前流程與設定項目。

接著在 Mac 端查看代理日誌，確認它是否嘗試連線、連線期間是否出現網路或設定錯誤；同時在 TeamCity 管理介面查看代理狀態。這兩邊的證據要對得上：若日誌顯示無法連線，先查 Server 位址、DNS、防火牆及網路路徑；若代理已連線但等待授權，就轉到平台端處理授權，而不是反覆重裝。

如團隊透過遠端方式管理 Mac，先把可用的遠端 Mac 接入方式與代理實際需要的管理權限分開規劃。遠端桌面可供管理操作，但不應取代對代理服務狀態與日誌的核對。

里程碑：連線後仍不可用時，分開處理授權與相容性

代理完成連線後，管理員應在 TeamCity 介面核對代理授權及啟用狀態。若等待授權，依組織的變更流程完成授權；若已授權但停用，確認停用原因與重新啟用是否符合團隊政策。記下狀態變化及對應時間，後續才容易將建置失敗與平台操作對起來。TeamCity 代理官方文件說明了狀態與授權管理方式。

授權只代表代理具備平台接入資格，不代表它符合某個建置設定的要求。此時要查看建置設定所要求的代理條件，再與代理回報的環境參數及工具能力比對。TeamCity 的代理需求文件可協助確認要求如何設定；預先定義的建置參數則可用來核對代理回報的環境資訊。代理需求設定文件與預先定義的建置參數清單是定位不匹配項目的依據。

TeamCity Mac Agent 已連線但建置工作不執行時，先查哪裡？

先確認建置工作是否真的被排入，以及目前代理是否符合該設定的要求。若沒有相容代理，檢查要求條件是否寫得過窄、代理是否回報預期的工具或平台參數；依實際需要調整條件或安裝依賴後，再重新確認代理相容性與工作派送結果。

如果代理顯示可用但工作仍未派送，繼續檢查建置佇列、代理啟用狀態與工作路由。不要僅憑「在線」推斷建置設定可以使用該節點；應留存當時的代理狀態、相容性資訊及建置結果，避免排查時把授權問題、要求不符和工作派送問題混為一談。

里程碑：Xcode 步驟執行時，驗證實際使用的工具鏈

如何確認 Xcode 建置使用正確的 Mac 代理？

先在目標 Mac 確認已安裝的 Xcode，以及命令列工具目前指向的路徑；再檢查 TeamCity 建置步驟是否指定了預期的 Xcode，或依賴系統預設選擇。Apple 提供命令列工具設定說明及工具參考，應以目前 Mac 上的實際設定配合官方文件核對，不要只根據建置設定的顯示名稱推斷工具鏈。Apple 的命令列工具設定說明及命令列工具參考可供查驗。

再以代表性專案執行一次完整建置。TeamCity 的 Xcode 建置步驟有專屬設定方式，應比對專案採用的動作、目標平台與該步驟參數。TeamCity Xcode 專案建置文件可用來核對步驟設定。若工作會啟動模擬器或連接實體裝置，還要依實際執行目標確認環境；Apple 對模擬器與實體裝置的執行方式有分別說明，不能假設命令列建置成功就代表裝置測試也可用。Apple 的模擬器與實體裝置執行說明

驗收結果至少要能回答：工作由哪個代理執行、使用哪套 Xcode、採取哪種建置動作，以及產物是否符合預期。若只看到步驟成功，卻沒有檢查產物與目標平台，仍不足以確認實際工具鏈正確。

里程碑：手動啟動成功後，再驗證 macOS 自動啟動

TeamCity 在 macOS 上如何設定建置代理自動啟動？

自動啟動方式要配合團隊實際的登入政策與工作負載。JetBrains 提供代理啟動相關說明，但各團隊仍須在自己的 Mac 上核對啟動設定、使用者環境與日誌；不可把某種設定直接視為所有工作都適用。TeamCity 代理啟動說明

排查時，先確認重啟後代理程序是否存在，再確認該程序是否成功連到 Server。若程序不存在，優先檢查 macOS 的使用者工作階段、LaunchAgent 設定、檔案擁有權與啟動日誌；若程序已啟動但未連線，則回頭檢查 Server 位址、認證資訊與網路連通。這樣可把「程序未啟動」與「已啟動但無法連線」分開處理。

對依賴圖形工作階段或特定使用者設定的任務，必須在正式運行方式下重啟並重跑建置。手動登入後可用，只能證明該登入情境成立，不能證明重新啟動後或無人登入時也能正常工作。

里程碑：完成端到端試跑，留下可重複查核的驗收紀錄

可依以下流程完成上線驗收：

1. 在目標 Mac 安裝代理，記錄安裝位置、執行帳號及所用設定。
2. 啟動代理，保存 Mac 端關鍵日誌，並在 TeamCity 管理介面確認連線及授權狀態。
3. 檢查建置設定的代理需求，確認該 Mac 回報的環境參數與所需工具相符。
4. 核對 Xcode 實際安裝與命令列工具選擇，檢視 TeamCity 的 Xcode 步驟設定。
5. 觸發代表性建置，記錄派送到的代理、建置輸出及產物檢查結果。
6. 依正式使用方式重新啟動或恢復工作環境，再次確認代理連線與建置派送。

驗收紀錄應包括代理狀態、關鍵日誌、建置設定要求、Xcode 核對結果與產物檢查結果。若採用需要圖形工作階段的工作方式，還應保存該情境下的試跑結果。這份紀錄能協助團隊區分代理離線、授權失效、要求不匹配及工具鏈錯誤，也能在節點維護後確認工作是否仍會派送到合適的 Mac。

團隊可從企業 Mac CI 建置節點與接入指南延伸規劃節點管理流程；如部署時遇到帳戶或接入問題，可參閱站內常見支援資訊。

若現有做法是每位開發者各自準備 Mac，硬體採購與維護會分散在不同使用者手上，也較難維持一致的建置環境；若改用團隊自管的共享 Mac，仍須安排主機維護、重啟測試及故障排查人力。對需要短期擴充 TeamCity macOS 建置容量、但不想立即增加自有硬體的團隊，可評估租用 NowMini 遠端 Mac，先核對接入方式、權限與代表性工作負載是否符合內部要求，再決定是否納入正式流程。聯絡 NowMini 了解遠端 Mac 接入評估