Apple 的 Xcode 命令列工具參考列出 xcodebuild 與 xcresulttool 等建置和結果分析工具。官方工具參考顯示：遇到 Xcode 建置失敗排查，先保存日誌與結果包、定位錯誤階段，再分查專案設定、依賴、工具鏈和 Mac 打包機；不要先重裝 Xcode 或換機。本週先為失敗工作保留可供檢視的結果包，並用同一提交、同一命令做隔離複現。
本文適合負責 iOS/macOS CI 的平台工程師，建立可重複使用的故障分類流程。
如果你管理團隊 Mac 打包機，可用下列線索區分節點問題與專案錯誤。
若你負責技術決策，也能據此規範日誌留存和故障升級路徑。
先看錯誤落在哪個階段，再判斷是否持續
先記下失敗提交、工作流程、建置節點、執行命令和錯誤階段。若不同工作、不同提交都在同一節點失敗，節點或工具鏈值得優先檢查；若失敗跟著同一提交移動，則先比對專案設定、依賴和程式碼變更。這些是排查方向，不是單憑症狀即可確認的因果。
不要把「建置失敗」當成單一問題。編譯錯誤、簽署錯誤、套件解析中斷和工作被取消，涉及的負責人與證據不同。先從 CI 工作日誌找到第一個實際錯誤，而不是只看最後的失敗摘要；後續的連鎖錯誤可能只是前一個故障的結果。
先從哪裡找 iOS CI 建置日誌？
先在 CI 工作紀錄中找到失敗工作與第一段錯誤輸出，再確認它對應的命令、目標與時間點。若使用自託管 runner，應一併查看 runner 狀態、應用程式及作業日誌，辨識工作是尚未啟動、執行中斷，還是由建置命令回報錯誤。自託管 runner 監控與排障文件說明可透過狀態和日誌追查 runner 問題。
把日誌中的第一個明確錯誤連同前後文保存，不要只複製最後一行。你也要記下最近是否更動 Xcode 選擇、憑證、鎖定檔、網路設定或工作流程；若沒有變更記錄，就難以比較成功與失敗執行之間的差異。
從專案設定與依賴錯誤開始分流
如果日誌指出找不到 scheme 或 target、建置設定不匹配，或簽署設定不完整，先確認 CI 使用的 scheme、target、configuration 和命令，是否與團隊已驗證的建置路徑一致。尤其要核對命令列實際指定的工作區或專案，以及該 scheme 是否包含 CI 預期執行的建置或測試步驟。
Apple 的常見設定與建置問題文件可協助辨識設定與建置錯誤。若日誌指出設定值錯誤、目標不存在或簽署資料不匹配，應讓專案維護者核查專案設定和憑證配置；不要只因錯誤出現在 Mac 節點上，就直接把責任歸給硬體。
依賴相關故障則要從失敗階段判斷。檢查套件解析是否中止、鎖定檔是否與成功版本一致、私有套件來源是否可連線，以及憑據是否在該 CI 工作的執行範圍內。外部工具下載失敗也可能是網路路徑或授權問題，不能一概歸因於 Xcode 或 Mac 主機。
第二步：核對命令列實際選到的 Xcode
CI 使用的開發者目錄未必等同於互動登入時的設定。先記錄 xcode-select -p 的輸出，再以 xcodebuild -version 確認命令列所用的 Xcode 版本；若懷疑建置設定不同，可把 xcodebuild -showBuildSettings 的輸出保存下來與成功工作比較。這些檢查結果是定位依據，不代表版本不同必然就是故障原因。
Apple 說明命令列工具可透過完整 Xcode 提供，也有獨立命令列工具的安裝方式。安裝說明可用來確認目前節點的工具來源。若工作需要完整 Xcode 提供的工具或 SDK，僅確認命令列工具存在並不足以證明環境符合要求；需進一步核實 CI 選用的開發者目錄與實際建置需求是否相符。
如何用 xcresult 定位編譯或測試錯誤？
為建置工作保存 .xcresult 結果包，並將它與提交識別、建置命令和原始日誌一同留存。xcodebuild 的 -resultBundlePath 選項可指定結果包的儲存路徑；Apple 的命令列工具參考亦列出 xcresulttool，供你檢視結果資料。測試結果文件說明如何查看測試執行結果與診斷線索。
結果包有助於區分測試失敗與編譯失敗，也可協助你確認失敗動作及相關診斷資訊。若只留下 CI 的摘要行，可能缺少定位失敗測試或建置階段所需的上下文。注意，結果包能提供證據，但不會自行證明根因；仍要將其中的失敗資訊與命令、提交及節點紀錄交叉核對。
Mac 打包機偶發失敗時，如何隔離複現？
若相同工作只在曾執行其他工作、或狀態不明的節點上失敗，先記錄 runner 是否在線、工作是否啟動，以及日誌中的中斷位置。再安排隔離複現：保持提交、建置命令和工具鏈選擇一致，改在狀態已記錄的環境執行，並保存新的日誌和結果包。若隔離後仍無法重現，不應僅憑一次偶發失敗就判定硬體性能不足。
例如，某提交在共用節點出現套件解析中斷，但隔離執行後建置完成。此時應先比較兩次執行的網路、憑據、鎖定檔與節點狀態，確認是否存在工作間環境殘留；直接更換 Mac 會讓原始證據消失，也可能讓真正的依賴或網路問題繼續存在。
可勾選的故障留存與升級清單
- [ ] 記錄失敗提交、CI 工作流程與執行命令。
- [ ] 記錄實際使用的 scheme、target、configuration 和開發者目錄。
- [ ] 從日誌擷取第一個明確錯誤及其前後文，標記錯誤發生階段。
- [ ] 保存
.xcresult結果包，並確認檔案與該次建置相對應。 - [ ] 記錄節點狀態、近期環境變更，以及依賴來源和憑據是否可用。
- [ ] 在隔離環境以相同提交與命令複現，將結果和原始執行逐項比較。
- [ ] 依證據交由專案維護者、CI 平台負責人或工具鏈負責人處理。
若現有線索仍不足以定位，可依自託管 Mac 建置環境指南補齊環境檢查與紀錄方式。涉及採購或租用遠端 Mac 的決策時，也可參考方案比較資訊，先把環境可重現性與管理責任納入評估。
依證據決定下一個處理對象
以下對照用來縮小排查範圍，不是將某個錯誤訊息直接等同於唯一根因。每種情況都應以日誌、結果包和隔離複現結果驗證。
| 可觀察到的線索 | 優先檢查範圍 | 下一個處理動作 |
|---|---|---|
| 找不到 scheme、target 或設定不匹配 | 專案設定與 CI 命令 | 交由專案維護者核對建置目標與設定 |
| 套件解析、私有來源或工具下載中斷 | 鎖定檔、憑據、網路路徑 | 比較成功與失敗執行的依賴和連線條件 |
| 命令列選用的 Xcode 或開發者目錄不符預期 | 工具鏈選擇與安裝內容 | 保存路徑與版本輸出，再交由工具鏈負責人核查 |
| 節點離線、作業中斷或同一節點才出現失敗 | runner 狀態、服務日誌與工作間環境 | 隔離節點，以相同提交和命令重現 |
| 相同提交在不同隔離環境都穩定報出同一錯誤 | 專案或工具鏈的可重現問題 | 附上日誌、結果包和複現紀錄後升級處理 |
若目前依賴的是共用本機 Mac，工作可能受到其他用途佔用與環境差異影響；自行採購則需要承擔設備維護和環境管理。一般非 Mac 建置環境也不能直接取代需要 macOS 工具鏈的原生建置工作。當你已排除專案與工具鏈問題，卻需要一個可獨立使用、方便重現的遠端 Mac 環境時，按需租用實際 Mac 可免去先購置專用設備的負擔，並能透過遠端方式進行檢查。你可查看 VpsKeep 的遠端 Mac 租用方案；若工作長期穩定且負載固定，仍應將自購與自管的維護需求一併比較。