症状：本地能解析私有 Swift 包，远程 Mac 构建却在拉取依赖时失败。 最快解法：先核对远程任务实际使用的仓库 URL、macOS 执行账户和凭据来源，再确认 Package.resolved 已纳入版本控制；Xcode Cloud 与自托管 Mac 的授权步骤不能混用。

本地构建正常、远程解析私有依赖失败的独立开发者：沿着证据链找出本机与 CI 的身份差异。 维护 xcodebuild 或自托管 Runner 的开发者：检查 SSH 凭据、主机验证文件和任务账户。 刚接入 Xcode Cloud 的小团队：确认平台授权流程，不要直接照搬自托管 Mac 的 SSH 配置。

Xcode 27 私有 Swift 包远程构建失败：先定位错误阶段

先找到日志里第一次出现的失败，不要只看最后的“构建失败”。Xcode 的报告导航器和命令行构建日志都可用于查看构建过程；命令行构建由 xcodebuild 执行，具体入口可参考 Apple 的 Xcode 命令行工具说明。

先按日志证据分流：

  • 仓库被拒绝或提示认证失败：检查账号、密钥、授权范围和执行身份。
  • DNS 失败、连接超时或主机不可达：先查网络路径、防火墙和仓库服务状态，不要换凭据碰运气。
  • 找不到分支、标签或满足条件的版本：核对仓库 URL、引用名和依赖版本要求。
  • 包已拉取，随后出现 Swift 编译错误：故障已进入编译阶段；回到编译器报错、目标设置和包源码排查，不要继续轮换 SSH 密钥。
同时记录**触发方式、工作目录和运行用户**。你在桌面登录用户下测试成功，并不能证明计划任务、Runner 或远程会话是同一用户、同一 HOME 或同一套 Git 配置。

仓库地址与网络可达性

本地可以解析，为什么远程构建仍然失败？

远程构建不是复用你本机的 Git 登录状态。即使依赖名相同，项目配置、Package.swift、解析锁定信息或自定义脚本中使用的仓库来源也可能不同；Swift 包依赖关联远程 Git URL 与版本要求，可对照 Apple 的 Swift 包依赖说明核对来源和版本约束。

检查指标与动作：

  • 来源一致性：分别核对 Xcode 项目或工作区、Package.swift、Package.resolved 以及构建脚本中的依赖地址。SSH 与 HTTPS 地址即使指向同一仓库，也可能使用不同认证方式。
  • 网络可达性：在实际构建主机、实际构建账户下检查 DNS 与连接是否可用。能访问代码主仓库，不代表依赖所在的另一台 Git 服务也可达。
  • 仓库和引用存在性：用脱敏后的地址和目标引用执行只读查询，例如：
git ls-remote '<REDACTED_SSH_URL>' '<REDACTED_REF>'

如果命令无输出或报错，先区分地址错误、网络失败与目标分支或标签不存在。不要把改写 URL 当成通用认证修复：它可能改变所需凭据类型，还可能让本地与 CI 解析到不同来源。

执行账户与凭据可用性

自托管 Mac 上的 xcodebuild 怎样使用 SSH 凭据？

先确认执行任务的 macOS 用户，再为该用户配置 SSH 访问。Apple 对直接使用 xcodebuild 的 CI 建议使用 SSH 形式的 Git URL，并将 known_hosts 放在运行 CI 任务用户的 ~/.ssh 目录；密码保护的 SSH 密钥还需要在调用构建前加入 SSH agent。可对照 Apple 的 Swift 包 CI 指南核实这些条件。

在 Runner 的任务脚本中输出并核对以下信息，输出前注意遮盖用户名、路径和仓库信息：

id -un
printf '%s\n' "$HOME"
ssh-add -l
ssh-add -l 没列出预期密钥，可能说明 agent 没有密钥；但若使用其他安全凭据代理，也不能仅凭这一项就判定认证失败。接着在**同一账户、同一任务环境**下测试脱敏后的仓库访问，并检查：
  • SSH 私钥是否只对构建所需的私有仓库有访问权限。
  • known_hosts 是否属于任务账户，且包含目标 Git 服务的主机验证信息。
  • ssh-agent 是否在 xcodebuild 启动时仍可访问。
  • Runner 是交互式会话还是后台服务；后台进程通常不能假设会继承你登录桌面后加载的 agent 或用户环境。
如果确实需要 macOS 系统 Git 的 URL 重写、代理或高级 SSH 配置，Apple 文档说明可让 xcodebuild 使用系统 Git 配置： 
xcodebuild -scmProvider system ...

仅在这些配置确有必要时再启用；它不会自动替你创建密钥、启动 agent 或授予仓库权限。不要为了“让它通过”关闭主机验证，或把共享 Git 配置改到其他任务也受影响的程度。

Xcode Cloud 的私有依赖授权应从哪里处理？

Xcode Cloud 不是你自托管 Mac 上的登录账户。按失败构建报告中的提示，使用 Xcode 或 App Store Connect 引导的 SCM 授权流程连接依赖所在的代码托管服务；通用入口与支持边界见 Apple 的 Xcode Cloud 依赖配置文档及源代码管理授权说明。

如果私有包和应用仓库位于不同的 SCM 服务或不同实例，确认授权覆盖的是依赖实际所在的位置，不能只确认主仓库已连接。托管服务的管理员权限要求会因服务类型而异；例如，授权某一托管服务时应按对应的 Apple 授权步骤执行，不要将单个服务的界面步骤视作所有服务的通用路径。

Apple 也把依赖不可访问、锁定文件不可用列为 Xcode Cloud 构建问题的排查项，可参考常见配置与构建问题说明。

Package.resolved 与版本复现

Package.resolved 没提交，会让远程构建使用不同依赖吗？

有这种可能。Package.resolved 记录依赖解析出的确切版本；Apple 建议将其提交到版本控制，使 CI 使用预期版本。Xcode Cloud 依赖该文件解析项目中的 Swift 包，不要将其加入 .gitignore；自托管 xcodebuild 可在已提交并核实锁定文件后使用 -disableAutomaticPackageResolution，避免 CI 自动重新解析。具体要求见前文的 Apple Swift 包 CI 与 Xcode Cloud 依赖文档。

检查实际项目或工作区对应的 Package.resolved 位置、Git 跟踪状态和提交内容；不要只在开发机上看见文件就认为 CI 一定拿到了它。对 Xcode 项目，Apple 文档给出的典型位置是项目内共享的 SwiftPM 锁定文件路径；如果使用工作区或项目结构不同，应以该构建入口对应的文件为准。

不要用强制自动解析掩盖认证故障。 自动解析不能为 CI 补上仓库权限，也不能修复错误 URL；它还可能让依赖版本偏离你正在验收的锁定结果。若要比较失败任务与预期版本，检查构建检出的锁定文件和解析日志，而不是只看开发机上的 Xcode 界面。

凭据安全与干净构建验收

令牌或私钥若出现在仓库、命令行参数、URL、脚本输出或构建日志中，就可能被复制到版本历史或 CI 日志。发现泄露时，先撤销或轮换凭据，再清理暴露位置；清理提交历史、缓存或共享 Git 配置前，明确影响的仓库、Runner 和协作者，并准备回退方式。新凭据只授予读取所需私有包的最小权限，并用受控的安全存储注入任务。

按以下清单验收修复；每项都必须以生产任务使用的构建入口和执行账户验证，而非只在交互式终端验证：

  • [ ] 日志中的首次失败已定位，明确属于仓库访问、认证、版本解析或 Swift 编译中的哪一类。
  • [ ] 远程任务访问的脱敏后仓库来源与项目配置预期一致，网络、仓库路径和目标引用分别验证通过。
  • [ ] id -un、HOME、SSH agent 与 known_hosts 均对应实际运行构建的 macOS 用户。
  • [ ] 若使用 Xcode Cloud，已从构建报告进入对应 SCM 授权流程；若是自托管 Mac，SSH 凭据已由任务账户实际读取。
  • [ ] Package.resolved 已提交、位置正确，失败任务解析出的依赖版本与预期锁定版本一致。
  • [ ] 在干净工作区执行依赖解析，再执行与发布相同的构建命令；保存访问成功、锁定一致、最终构建通过这三类脱敏证据。
结果可按🟢已通过、🟡待验证、🔴未通过标记，**任何授权或锁定项仍为红色，都不应把问题记作“已修复”**。只有依赖已成功拉取、锁定版本一致后才进入编译错误排查；否则清缓存或重复构建只会增加噪声。

方案判断：托管构建与自托管远程 Mac

  • Xcode Cloud，授权体验： SCM 授权由平台流程引导，适合能在平台支持范围内连接代码托管服务的工作流；如果授权未覆盖私有包所在的服务或实例，仍会在依赖阶段失败。
  • 自托管 Mac，身份控制： 你可以针对 Runner 的 macOS 账户管理 SSH、known_hosts 和系统 Git 配置；代价是自己承担密钥轮换、服务账户维护、网络连通与任务环境一致性。
  • 远程 Mac iOS 构建，环境控制： 适合需要一台真实 macOS 主机运行 Xcode 命令行任务的情况；但远程主机本身不会自动解决 Git 仓库权限、错误锁定文件或泄露的密钥。
这不是“哪种 CI 一定更快”的排名，而是把授权责任放在正确位置。若当前采用 Windows 或 Linux Runner，它不能代替实际的 macOS/Xcode 构建环境；若你已有能稳定运行的 Xcode Cloud 工作流，也不必仅因一次认证失败就迁移。遇到超时再先核验仓库网络路径，遇到拒绝访问则先修复授权。

如果证据指向自托管环境的账户隔离、SSH 凭据维护或需要独立 macOS 构建节点，而不是仓库权限或依赖锁定，你可以先查看 MACGPU 的远程 Mac 方案入口，再对照购买 Mac 的配置选择指南判断长期自购是否更合适。持续、稳定且由你自行维护的重负载工作，更适合评估自购；需要临时或按周期使用真实 Mac 的构建任务，则可了解 MACGPU 的远程 Mac 租赁。Xcode 27 私有 Swift 包远程构建失败时，最终仍应回到同一条证据链：仓库地址、实际执行身份、凭据来源与 Package.resolved。