Xcode Cloud 私有依賴拉取失敗怎麼辦？2026 排查指南

構建報告顯示私有套件無法存取，或依賴解析在 Xcode Cloud 中失敗？
先確認問題發生在倉庫授權、依賴解析還是自訂腳本階段，再沿著對應路徑修復；私有依賴本身不代表你必須放棄 Xcode Cloud。

負責維護 Xcode Cloud 工作流程的工程師，可依構建報告定位私有依賴存取問題。
管理內部 Swift Package、Git 子模組或多個程式碼倉庫的團隊負責人，可核對授權與依賴解析狀態。
評估 CI 執行環境的 IT 或技術負責人，可據實際網路、工具與控制要求決定是否需要自託管 Mac。

先用構建報告找出失敗階段

不要只憑一行錯誤訊息，就判定是倉庫權限出了問題。先查看構建報告中最後完成的工作，以及第一個失敗的步驟；同一個「無法取得依賴」表象，可能發生在程式碼複製、Swift Package 解析、第三方工具準備或 Xcode 建置階段。

Apple 說明，Xcode Cloud 必須能存取工作流程所需的程式碼倉庫與依賴；若無法取得私有依賴或建置所需工具，構建可能失敗。這是排查方向，不是某個專案的根因判定。請把 Apple 的依賴準備與私有存取說明 與實際構建報告一起核對。

可依失敗位置先縮小範圍：

• 倉庫複製階段失敗：先檢查主要程式碼倉庫、子模組及依賴倉庫的連線與授權。
• 依賴解析階段失敗：檢查 Swift Package 的來源、Package.resolved 是否提交，以及鎖定檔案所在路徑。
• 腳本或工具準備階段失敗：確認腳本是否被辨識、必要工具是否安裝，以及腳本需要的檔案是否可取得。
• Xcode 建置階段才失敗：再查看建置輸出與目標設定，避免把編譯錯誤誤當成私有倉庫存取問題。

Xcode Cloud 無法存取私有 Swift Package 時，先從哪裡檢查？
先確認該套件實際所在的程式碼託管服務，以及 Xcode Cloud 是否已取得該倉庫的存取授權。若主程式碼倉庫可以複製、但套件解析失敗，請轉查套件所在倉庫的連線狀態，不要只確認主專案是否已授權。Apple 的程式碼託管連線設定文件說明了 Xcode Cloud 與程式碼託管服務的連線方式。

私有倉庫與 Git 子模組授權

新增私有依賴後，既有工作流程可能仍可取得主專案，但無法讀取新加入的套件或子模組。請從失敗構建報告提供的存取提示檢查授權，並確認授權對象是依賴實際所在的倉庫，而非只看主專案的連線狀態。Apple 文件指出，Xcode Cloud 可在發現無法存取的依賴時提示你完成授權。

Xcode Cloud 的私有 Git 子模組要怎樣授權？
先確認子模組指向的倉庫和程式碼託管服務，再依構建報告中的存取提示完成授權。接著重新執行工作流程，確認複製階段能讀取子模組內容；如果子模組位於另一個服務或託管實例，主倉庫已連線並不等於子模組也已授權。

多個倉庫若分散在同一服務的不同企業實例，或分別位於不同程式碼託管服務，必須逐一核對實際連線狀態。對尚未連線的實例，依後續構建所出現的提示繼續完成接入；不要把「同一服務」直接推論為「所有實例都已可用」。Apple 的程式碼託管連線說明可用來確認連線流程，但每個倉庫能否讀取仍須以你的構建結果驗證。

注意：授權完成後仍應重跑工作流程，確認實際使用的依賴倉庫可被讀取。只看設定頁面顯示已連線，不能代替對失敗步驟的驗證。

Package.resolved 與第三方工具的狀態

Swift Package 的解析結果要能在團隊與 CI 間保持一致。請檢查 Package.resolved 是否已提交至版本控制、檔案是否位於預期專案路徑，以及最近的提交是否包含團隊本地解析後的更新。Apple 的Swift Package 持續整合指南說明了在 CI 工作流程中使用套件與鎖定檔案的注意事項。

Package.resolved 缺失或未提交，會怎樣影響 Xcode Cloud 構建？
如果工作流程無法使用預期的鎖定狀態，依賴解析結果可能與團隊本地環境不同，或在解析階段發生錯誤。先確認專案使用的檔案位置與版本控制狀態，再比較失敗構建所採用的提交；不要把強制自動解析當成預設修復，因為它不能取代對依賴來源和鎖定狀態的檢查。

若專案使用 CocoaPods、Carthage 或其他第三方工具，請核對工具如何安裝、必要鎖定檔是否納入版本控制，以及新建的構建環境能否取得所需檔案。Xcode Cloud 的建置環境不應被假設為保留你工作站上的工具或隱含狀態；必要準備工作要明確寫入可重現的流程。Apple 的首次工作流程設定文件可協助你對照工作流程設定。

自訂腳本、網路與密鑰核查

腳本錯誤往往不是套件倉庫本身不可用，而是腳本沒有在預期階段執行、路徑不符，或在乾淨環境中找不到所需檔案。對照 Apple 的自訂建置腳本說明，檢查腳本名稱、ci_scripts 目錄位置、執行階段與結束狀態；並按用途確認 ci_post_clone.sh、ci_pre_xcodebuild.sh 或 ci_post_xcodebuild.sh 是否放在預期位置。

接著核對腳本用到的環境變數、代理設定與密鑰來源。Apple 提供環境變數參考，可用來確認 Xcode Cloud 工作流程可讀取哪些變數。不要在日誌中輸出敏感值，也不要假設建置環境具備未經驗證的管理員權限、本機設定或企業內網路由。

若失敗看似與網路有關，先確認依賴來源、必要服務及代理是否可由目前工作流程存取；若需要固定內網路徑、特定工具安裝方式或可自行管理的執行環境，則應列出具體要求，再評估是否超出現有工作流程可滿足的範圍。不能僅憑一次逾時或連線錯誤，就推論平台存在未公開的限制。

提醒：腳本能執行，不代表它所需的網路、檔案和密鑰都已就緒。把每項前置條件明確化，並在乾淨構建中逐項驗證，較容易分辨設定錯誤與環境需求不符。

修復前的核對清單與環境選擇

完成修改前，逐項確認以下事項；若某項仍無法確認，就先保留構建報告與提交資訊，避免一次改動多個環節而失去線索。

• [ ] 已確認第一個失敗步驟，而非只依最後一行錯誤判斷根因。
• [ ] 已核對主倉庫、私有 Swift Package、Git 子模組及腳本所需倉庫的實際位置。
• [ ] 已依構建提示檢查相應程式碼託管服務或實例的授權狀態。
• [ ] 已確認 Package.resolved 的路徑、版本控制狀態與最近提交內容。
• [ ] 已檢查第三方工具安裝方式，以及乾淨構建所需的鎖定檔和資源。
• [ ] 已核對自訂腳本的名稱、位置、執行時點、退出狀態與必要環境變數。
• [ ] 已檢查網路與代理需求，並確認日誌不會洩露密鑰。
• [ ] 已以修正後的提交重跑工作流程，並確認原失敗步驟已通過。

如果問題已定位，通常應先修正授權、鎖定狀態或腳本準備，而非立即遷移 CI。只有當團隊確實需要 Xcode Cloud 工作流程無法滿足的私有網路、工具鏈或環境控制時，才把自託管 Mac 納入評估。下表是依需求匹配度作出的編輯判斷，不是效能測試或平台保證：

自託管 Mac 並非所有私有依賴問題的解答：它會把作業系統更新、工具維護、存取隔離與故障處理責任交回團隊。若要比較不同執行方式，可先參考zshmac 的 Mac 方案比較頁；若需評估企業環境是否符合實際接入要求，可透過zshmac 聯絡頁提出需求，並在採用前自行驗證私有倉庫連通性與權限邊界。

若你的 Xcode Cloud 已能滿足一般套件解析與建置需求，修好授權或腳本通常比遷移整套 CI 更直接；但若工作流程必須進入現有雲端流程無法觸及的企業私有網路、依賴特定工具狀態，或要求更高的執行環境控制，就要把這些限制與自託管 Mac 的維運成本一併評估。需要臨時或按需求使用 Mac 環境時，可進一步了解 zshmac 的遠端 Mac 租用；先按真實倉庫、網路和工具需求確認是否適用，再決定是否調整建置環境。