症狀：Xcode Cloud 建置停在 CocoaPods 依賴流程時，先從日誌找出第一個有效錯誤，再判斷失敗是在腳本、工具、依賴下載還是 Pod 安裝。
最快處理：核對建置腳本、Podfile 與 Podfile.lock，以及私有依賴的存取條件；只有確認需求超出 Xcode Cloud 可控制的環境範圍，才評估改用遠端 Mac。
適合使用 CocoaPods、在 Xcode Cloud 建置 iOS 或 macOS App 時遇到依賴安裝問題的獨立開發者。
如果本地建置正常、雲端建置失敗，本文會協助你區分鎖定檔、私有依賴與腳本問題。
若你負責發布流程，也可以據此判斷應繼續修復現有工作流程，還是評估自主管理的 macOS 環境。
Xcode Cloud CocoaPods 安裝失敗：先鎖定首個有效錯誤
不要先刪除 Podfile.lock、重寫 Podfile，或把所有失敗都歸因於 Xcode Cloud 不支援 CocoaPods。Apple 說明可透過建置腳本讓依賴與第三方工具在 Xcode Cloud 環境中備妥；實際問題仍需依工作流程和建置日誌確認。Apple 的 Xcode Cloud 依賴準備說明
先在失敗的建置記錄中找到第一個具有診斷價值的錯誤，而不是從末尾的建置失敗摘要倒推。記下它出現在哪個工作流程階段、前一項操作是否成功，以及錯誤涉及的命令或依賴名稱。分享記錄前，先遮蔽帳號、專案名稱、倉庫網址與認證內容。
請先把故障分到以下類別：
- 腳本未執行：預期的依賴準備步驟沒有對應日誌，或執行順序與預期不符。
- 工具不可用：腳本有執行，但 shell 找不到
pod，或安裝 CocoaPods 的命令本身失敗。 - 下載或解析失敗：CocoaPods 已啟動，但依賴來源、版本解析或套件下載出錯。
- Pod 安裝失敗：依賴來源可讀取，但 Pod 安裝流程因設定、相容性或安裝階段錯誤而中止。
- 後續建置失敗：依賴安裝已完成，真正的失敗發生在 Xcode 編譯或其他後續步驟。
最後一類尤其容易誤判：如果日誌已證明 Pod 安裝完成，就應轉查後續 Xcode 建置錯誤，而不是反覆調整 CocoaPods 設定。Apple 也建議按實際錯誤與工作流程設定排查，而非只看最終失敗狀態。Apple 的 Xcode 建置問題排查說明
腳本沒有執行或 pod 找不到時，檢查建置環境
Xcode Cloud 的自訂建置腳本可以用於準備第三方工具，但「建置已開始」不等於「工具已安裝成功」。Apple 對腳本的放置、命名與執行方式有說明；先依官方規則確認專案內的 ci_scripts 目錄和腳本名稱，再以建置日誌驗證該腳本是否真的執行。Apple 自訂建置腳本文件
逐項核對以下事項：
- 目錄與檔名：確認腳本位於版本庫中預期的位置，名稱符合所配置的工作流程階段。
- 執行權限：確認提交後腳本仍具備執行權限；不要只在本機檢查檔案存在。
- shebang 與 shell：查看腳本開頭指定的直譯器，並從日誌確認腳本實際在哪個 shell 環境執行。若在互動式終端可用、在建置腳本內找不到命令，PATH 或 shell 初始化差異可能是線索。
- 安裝命令結果：檢查安裝工具的輸出及結束狀態，再於同一執行環境確認
pod是否可用。只看到腳本開始，不能當作安裝成功的證據。 - 執行順序：確認 CocoaPods 的準備步驟先於呼叫
pod install的步驟；若順序相反，即使安裝腳本內容正確也無法解決問題。
Apple 說明 Xcode Cloud 的自訂腳本有其執行與權限界線，因此，不要假定可以把本機 shell 設定、互動式登入狀態或所有系統層變更直接照搬過去。應先確認必需操作是否能在受支援的建置腳本中完成，再決定是否需要其他環境。Apple 對自訂建置腳本的執行說明
Podfile 與 Podfile.lock 不一致時，先保留可追溯的依賴狀態
若 CocoaPods 命令能執行，但依賴版本與本地預期不同，先檢查版本庫中的 Podfile 和 Podfile.lock。兩者應對應同一份已審核的依賴狀態；若其中一份未提交、分支內容不一致，或建置時發生非預期變動，就可能讓雲端解析結果偏離團隊預期。
CocoaPods 說明，pod install 與 pod update 的用途不同：前者用於依照現有鎖定狀態安裝依賴，後者會更新依賴版本。遇到建置失敗時，應先確認目前操作與鎖定檔相符，不要把更新依賴當成一般重試手段。CocoaPods 對 pod install 與 pod update 的說明
若要判斷鎖定檔是否意外被修改，可在建置流程中檢查版本控制狀態，並比對建置前後的差異。若依賴沒有刻意更新，應恢復並提交經審核的 Podfile 與 Podfile.lock；若你確實需要更新，先在可控環境完成變更審查與驗證，再把更新後的鎖定狀態納入版本庫。
CocoaPods 的專案整合指南也將依賴設定與專案納管視為建置流程的一部分；因此，除了檢查檔案是否存在，也要確認工作分支和來源碼管理設定包含所需檔案。CocoaPods 專案整合指南
私有依賴無法取得時，分開查網址、認證與權限
如果錯誤指向私有 Pod 倉庫或第三方來源，先不要急著改版本。從脫敏後的日誌辨認失敗發生在哪一段：倉庫網址是否可解析、來源是否回應、認證是否提供，以及目前憑據是否具有讀取該依賴的權限。不同原因可能出現相似的下載失敗訊息，應以日誌中的具體錯誤和工作流程設定交叉確認。
再檢查建置環境實際可取得哪些環境變數，以及憑據是否只授予完成拉取依賴所需的權限。Apple 提供 Xcode Cloud 環境變數的參考資料；你應依該文件和團隊自己的憑據管理方式核對設定，不要假設本機 shell 中的登入狀態會自動出現在雲端建置環境。Apple 環境變數參考
涉及倉庫存取時，也要確認 Xcode Cloud 的來源碼管理設定和工作流程對應的程式碼來源正確。Apple 的來源碼管理設定說明 無論問題最後是否與權限有關，都不要把存取令牌、私鑰或含有認證內容的完整建置日誌放進版本庫、公開範例或工單附件。
常見問題：依照日誌判斷下一個檢查點
日誌顯示找不到 pod，代表 CocoaPods 安裝指令失敗嗎？
不一定。這項訊息能說明執行中的 shell 找不到命令，但單靠它無法確認是安裝失敗、PATH 不包含安裝位置，還是負責準備工具的腳本沒有執行。應先回看同一工作流程中安裝命令的輸出與執行順序，再檢查呼叫 pod install 時的環境。
CocoaPods 應由哪個自訂建置腳本負責準備？
應由工作流程中能在 pod install 之前執行、且符合 Apple 腳本規則的階段負責。具體採用哪個階段，取決於你的依賴準備流程；不能只因某個腳本存在，就推定它一定在依賴安裝之前運作。以實際建置日誌驗證呼叫順序和命令結果。
Podfile.lock 與雲端解析結果不符時，是否重新產生鎖定檔？
先查清楚檔案是否已提交、是否與 Podfile 一起更新，以及建置工作流程是否有意變更依賴。若本次建置應沿用既有依賴，就修復或還原經審核的鎖定狀態；只有你決定更新依賴時，才重新解析、檢查差異並提交新的鎖定檔。
私有 Pod 在本機可用、Xcode Cloud 卻無法下載，怎麼定位？
把本機登入狀態與 Xcode Cloud 可用的認證分開看。先從日誌確認來源網址及失敗階段，再核對建置工作流程能否取得必要憑據，以及該憑據是否有讀取權限。完成檢查後，以不暴露祕密的方式重建；如果只能靠未受支援的本機狀態存取，應重新設計憑據流程或評估可控環境。
需要固定工具或額外控制權時，如何選擇下一步
只有依據可觀察的失敗證據，才把「環境控制不足」列為遷移理由。先依下列條件分支判斷：
- 若問題是腳本路徑、權限、執行順序或 PATH 設定，而且能在 Xcode Cloud 支援的自訂腳本中修正，就先修復工作流程，再以實際日誌驗證。
- 若問題是 Podfile 與 Podfile.lock 不一致，而團隊希望保留目前依賴，就還原並提交已審核的鎖定狀態，不要以刪除鎖定檔代替診斷。
- 若問題是私有依賴存取，先調整建置環境可用的憑據、來源網址或權限；只有在必要的憑據管理方式無法符合環境限制時，才比較其他方案。
- 若流程必須長期保留自訂工具狀態、調整系統環境，或使用目前工作流程無法滿足的權限控制，而且受支援的腳本方法仍無法完成，才評估自主管理的遠端 Mac。這是環境控制的選項，不是每種 CocoaPods 安裝失敗的必然解法。
選擇遠端 Mac 時，需一併考慮工具維護、憑據保護與發布責任，而不是只看能否登入 macOS。你可以先查看 遠端 Mac 的使用情境，確認工作負載是否適合在自主管理環境執行；若只在發布或排錯階段需要環境，則可再比較租用方案與週期。若建置長期穩定、工作量持續且需要實體介面，本地 Mac 也可能較合適。
乾淨重建：確認修復不是偶然快取造成
修改設定後，不要只以「腳本這次沒有報錯」判定完成。先固定要驗證的分支和依賴輸入，再執行完整建置，檢查依賴安裝是否按預期完成，以及後續 Xcode 建置是否也通過。Apple 的依賴準備文件可用來核對工具與依賴應在工作流程的哪個環節備妥；若你更換了建置環境，也要重新驗證依賴取得和後續建置鏈路。
可勾選以下項目作為驗收紀錄：
- [ ] 已保存脫敏後的首次錯誤及其所在工作流程階段。
- [ ] 已確認預期的自訂腳本確實執行，且工具準備命令有可查證的結果。
- [ ] Podfile 與 Podfile.lock 已檢查並與預期依賴狀態一致。
- [ ] 私有依賴來源與建置憑據已核對，沒有把祕密值寫入版本庫或公開日誌。
- [ ] 已從乾淨建置確認 CocoaPods 安裝及後續 Xcode 建置均完成。
- [ ] 已記錄驗證所用分支、環境及日誌；若更換環境，已重新確認整條依賴鏈路。
若問題只是工作流程設定或鎖定檔管理，修正 Xcode Cloud 通常比遷移整套環境直接；但如果你需要更高的 macOS 工具、權限與憑據環境控制，雲端流程的臨時環境、可設定範圍與工具狀態維護方式，就可能與專案需求不合。KVMFLUX 提供透過 VNC、SSH 或網頁主控台存取真實 Mac 的租用服務，並提供完整 root 權限；你仍需自行確認專案工具、依賴和安全流程。若問題屬於短期驗證或發布環境需求，先按專案條件評估可用的遠端 Mac 租用方案；若需要長期穩定運作或實體介面，則應一併比較自購 Mac，而非把遠端租用當成唯一答案。