Xcode Cloud 私有依赖拉取失败怎么办？2026 排查指南

症状： Xcode Cloud 因私有依赖拉取失败，先别急着迁移 CI。
最快解法： Apple 文档要求连接 Git 仓库使用 HTTPS 的 443 端口；接着按构建报告定位仓库授权、依赖解析或脚本阶段，再修对应问题。Apple 的代码托管连接说明可核对连接前提。私有依赖本身并不意味着必须放弃 Xcode Cloud；只有当工作流无法满足团队的私有网络、工具链或环境控制要求时，才评估自托管 Mac。

负责 Xcode Cloud 工作流的工程师，可根据构建报告定位私有依赖访问失败的阶段。
维护内部 Swift Package、Git 子模块或多仓库依赖的负责人，可沿授权与解析路径核对配置。
评估 CI 环境的 IT 或技术负责人，可据真实网络和工具要求判断是否需要自托管 Mac。

Xcode Cloud 私有依赖拉取失败，先按日志确定故障阶段

单条“无法获取依赖”的报错不能直接证明是仓库授权问题。相同表象也可能出现在锁定文件不匹配、第三方工具未安装、脚本退出异常或网络访问失败时。先打开失败构建报告，找到最早出现的错误及其所在步骤；后续错误可能只是前一阶段失败的结果。

表格用于初步分流，不是根因清单。Apple 说明，Xcode Cloud 无法访问私有依赖或所需第三方工具时，构建可能失败；但项目的具体原因仍须由构建日志和可重复测试确认。依赖准备与私有访问文档

仓库授权：主项目可访问，不代表所有依赖可访问

Xcode Cloud 私有仓库授权要逐个核实仓库的实际位置。Xcode 会识别项目所用的代码托管服务，以及私有 Swift Package、Git 子模块或脚本访问的 Git 仓库；当新增私有依赖而构建无法访问时，可从失败构建报告或 Xcode 提供的流程继续连接依赖所在的服务。Apple 对私有依赖授权的说明

按以下顺序检查，避免只在主仓库上重复授权：

• 确认构建报告失败的是应用主仓库、私有 Swift Package、Git 子模块，还是脚本中访问的另一个仓库。
• 对照依赖声明里的实际仓库地址，确认它属于哪个代码托管服务；不要依据团队常用的服务名称推断。
• 查看主仓库与依赖仓库是否分别位于不同服务或自托管实例，并分别核对 Xcode Cloud 的连接状态。
• 如果是刚加入的私有依赖，从失败构建报告继续授权，然后重新运行构建验证。
• 若应用和依赖位于同一自托管服务的不同实例，先完成应用代码所在实例的初始接入；首次构建后，按 Xcode 或 App Store Connect 给出的提示连接另一个实例。Xcode Cloud 工作流配置说明

⚠️ 多实例场景要区分“同一个服务的不同实例”和“不同代码托管服务”。授权某个服务或实例成功，并不能据此推断其他实例也已连接。

自托管代码托管服务还要确认 Xcode Cloud 能否访问仓库本身。Apple 的文档要求 Git 仓库提供连续、安全的 HTTPS 连接，并说明项目配置时需要由 Xcode 引导完成对应服务的授权；具体支持的服务和接入方式应以其代码托管配置文档为准。

依赖解析：把 Package.resolved 当作团队构建状态的一部分

检查Package.resolved时，不要只在本机项目里搜索文件名。Apple 文档指出，Xcode Cloud 不使用自动包解析，而是依赖 Package.resolved 解析 Swift Package；文件应提交到 Git、不能被 .gitignore 排除，并位于对应项目的预期路径。强制改为自动解析可能导致未定义行为或构建失败。Xcode Cloud 依赖文档与Swift 包 CI 指南均有说明。

可以这样核对：

• 在仓库中检查文件是否被跟踪、是否已提交；仅在开发者本地存在并不能保证 CI 检出得到。
• 对照 Xcode 项目或工作区的实际位置，确认文件处于预期的 xcshareddata/swiftpm/Package.resolved 路径。
• 比较最近提交中的锁定状态与团队本地解析结果；如果依赖版本刚变更，确认相应文件更新也已提交。
• 检查依赖仓库是否已授权。锁定文件记录解析状态，不会替代私有仓库访问权限。

需要验证的是“仓库中声明的依赖状态能否在 CI 中复现”，而不是一遇到解析失败就删除锁定文件或强制更新依赖。直接改变解析策略，可能把一次可定位的访问错误扩大为版本漂移问题。

第三方工具与自定义脚本：核对准备时点和实际执行条件

CocoaPods、Carthage 等第三方工具不应被假设为构建环境中已经准备好。Apple 文档说明，Xcode Cloud 的临时构建环境包含 macOS 和 Xcode 自带工具，并提供 Homebrew 支持安装额外工具；团队需要在项目或工作流中明确准备依赖的方式。第三方依赖准备说明

如果日志指向工具缺失或脚本报错，先检查脚本是否按预期执行，再决定是否需要改安装步骤。Apple 规定的脚本目录是项目或工作区旁的 ci_scripts，脚本要放在目录顶层，并使用相应文件名：ci_post_clone.sh 在克隆后运行，ci_pre_xcodebuild.sh 在 xcodebuild 前运行，ci_post_xcodebuild.sh 在构建后运行。脚本还应包含 shebang 并具备执行权限；Apple 特别说明，脚本不能通过 sudo 获取管理员权限。自定义构建脚本文档

从最早失败的脚本开始核对：

• 时点与文件位置：脚本名称、所在目录和依赖它的文件是否与执行阶段相符。脚本要访问的资源应按文档要求放入可用位置。
• 退出状态：找到首个返回非零状态的命令；不要只盯着后续 xcodebuild 的错误。
• 环境变量与代理：确认工作流自定义变量是否设置正确。Xcode Cloud 提供预定义环境变量；其构建环境使用 HTTP 代理，并提供 HTTP_PROXY 与 HTTPS_PROXY 环境变量，依赖网络访问的工具需要在实际构建中验证。环境变量参考
• 锁定文件与安装过程：核实依赖管理器及其锁定文件已纳入版本控制，脚本使用的是仓库可复现的输入，而非某台开发机上的隐含状态。
• 敏感信息：访问令牌等凭据不要写入普通日志；用工作流的密钥环境变量承载敏感值，并检查脚本输出是否意外打印变量内容。工作流环境变量说明

脚本能安装工具，不等于它可以自动满足所有企业网络策略。若安装步骤必须访问内部源、代理或私有制品库，要在实际工作流中验证网络路径和凭据，而不是假设本地终端的配置会随构建环境带入。

可勾选的复测清单：修复后再决定是否迁移

每次只改变一个可能原因，再运行构建并对照失败阶段；这样才能确认修复是否有效，而不把多个配置变更混成一个无法归因的结果。

• [ ] 已找到失败报告中最早的错误，并记录它发生在克隆、依赖解析、脚本还是 Xcode 构建阶段。
• [ ] 已核对主仓库、私有 Swift Package、Git 子模块和脚本所访问仓库的托管服务与实例。
• [ ] 对新增私有依赖，已按构建报告提示完成访问连接，并通过重新运行构建验证。
• [ ] 已确认 Package.resolved 已提交、路径正确，且没有把自动解析当作默认修复。
• [ ] 已确认第三方依赖工具的安装步骤、锁定文件和构建脚本在临时环境中可复现。
• [ ] 已检查自定义脚本的文件名、路径、执行方式、退出状态、环境变量和日志敏感信息。
• [ ] 已验证工作流实际需要的私有网络、代理、凭据和工具访问；若这些要求仍无法满足，再评估执行环境调整。

如果团队发现现有工作流必须依赖 Xcode Cloud 当前无法满足的私有网络路径、工具准备方式或环境控制，下一步才是评估自托管 Mac 构建节点。可以先参考团队 iOS CI/CD 执行环境对比，把实际仓库连通、凭据管理和维护责任列为验收项；自托管节点能提供不同的环境控制方式，但也增加主机维护、持续可用性和密钥管理工作，且不会自动修复仓库授权或依赖锁定错误。若你考虑用 zshmac 租用远程 Mac 做环境验证，应先确认目标代码托管服务与私有网络能否从该环境访问，不要把租用本身当作连通性或 Xcode Cloud 兼容保证。需要确认具体环境是否适合验证时，可通过联系 zshmac询问可核验的访问条件；最终仍应以你们自己的构建复测结果决定是否调整执行环境。

常见问题