Xcode 27 私有 Swift Package 拉取失败？2026 修复指南

Apple 的 CI 指南明确要求：私有 SSH 依赖所需的 known_hosts，应放在实际运行 CI 任务的 macOS 用户的 ~/.ssh 目录中。排查 Xcode 27 远程 Mac 私有 Swift Package 拉取失败，本周先核对执行账户、SSH 凭据和主机校验，再看 Package.resolved 与依赖 URL；不要先关闭主机校验，也不要盲目清缓存。(Apple 的 Swift Package CI 指南)

本周排障安排：先用同一提交复现并划定失败阶段；再逐层检查账户、SSH、锁定文件和 Git 配置；最后在干净工作区复测，决定修账户还是隔离节点。

维护 Xcode 项目、需要从远程 Mac 获取私有 Swift Package 的开发者，可以按错误阶段缩小范围。
管理 Mac CI 节点和 SSH 凭据的 DevOps 工程师，可以据此设置最小权限。
正在把本机构建迁往远程环境的研发负责人，可以判断问题来自执行账户，还是依赖锁定与解析设置。

先不要把“依赖拉取失败”当成单一故障。相同的构建结果可能来自 SSH 身份认证、主机密钥校验、依赖版本解析，或 Xcode 调用 Git 时使用了不同配置；修复错层，通常只会增加变量。

在 CI 中保留同一提交、同一 scheme、同一构建命令和完整解析日志，再与本机结果对照。日志应能回答：失败发生在连接仓库之前、SSH 握手期间，还是包版本解析完成之后？本机成功只能说明本机当前账户与环境可访问，不能证明 Runner 使用同一身份、SSH 目录或配置。

为什么本机能解析，远程 Mac 却拉不到私有包？
先对比两边的执行用户、仓库 SSH URL 和 ssh -vT 输出。若远程日志出现 Permission denied (publickey)，优先检查认证身份；若提示主机密钥验证失败，先核对 known_hosts；若仓库连接成功但包版本不同，再检查锁定文件与自动解析行为。不要用清缓存处理尚未分类的故障。

在开始前，也要核实 Xcode 与 macOS 是否处于受支持的组合。Apple 当前兼容页面列出 Xcode 27 RC 支持 macOS Tahoe 26.6 或更新版本；发布状态及要求可能变化，部署前应以Apple 的 Xcode 系统要求页面为准，不能假定所有远程节点都已满足条件。

打开管理员的交互式终端测试成功，不等于 CI 能读取同一把 SSH key。Runner 可能以独立服务账户运行，拥有不同的 home 目录、SSH 配置和 agent 环境；将密钥只放在管理员账户下，任务进程通常无法使用它。

SSH key 和 known_hosts 应属于哪个账户？
应属于实际启动 xcodebuild 的 macOS 用户，而不是默认属于登录桌面的管理员。Apple 的 CI 指南要求在运行任务账户的 ~/.ssh 中配置 SSH 凭据和 known_hosts；若私钥有口令，也要按指南在调用 xcodebuild 前准备 SSH agent。具体操作可参考前文的 Apple CI 指南和Apple 关于 SSH agent 的技术说明。

按以下顺序检查：

• ✅ 从 Runner 配置或任务日志确认 macOS 用户与 $HOME，不要仅凭网页登录账户推断。
• ✅ 在该用户的会话中检查 whoami、echo "$HOME"、ssh-add -l，确认任务实际可见的身份。
• ✅ 核对依赖地址是否为 SSH URL，并在同一账户下用只读方式测试仓库访问；不要把密钥内容、令牌或完整环境变量输出到日志。
• ✅ 将凭据限制到构建所需的仓库和操作范围。若仓库托管平台支持只读部署密钥，可参考只读部署密钥的权限说明评估适用性；它的权限范围和凭据管理限制也应纳入运维决策。

如果 ssh-add -l 显示没有身份，或 SSH 调试信息没有尝试预期的密钥，先修复任务账户的密钥加载方式。不要为了让管理员终端和 Runner“看起来一样”，把管理员 home 目录或宽泛权限直接共享给 CI。

认证和主机校验是两关：私钥证明客户端是否有仓库访问权限；known_hosts 用于识别连接到的服务器。SSH 在主机身份未知或发生变化时拒绝连接，不能通过换一把客户端密钥来修复。

在运行任务的账户下检查实际使用的主机名、端口、SSH 别名和 known_hosts 路径，并核对仓库 URL 与 SSH 配置中的匹配规则。首次加入主机时，必须通过可信来源核验指纹后再写入；例如，若仓库托管方提供官方 SSH 指纹页，可按其公布的信息核对，而不是照抄未经验证的扫描结果。官方 SSH 指纹说明和主机密钥校验错误说明提供了这一核验思路。

⚠️ 不要把 StrictHostKeyChecking=no 当成常规修复。它会降低对未知或变化主机密钥的保护；若排障期间确需短暂例外，应限定测试范围、记录原始设置，并在验证后恢复，不能把例外留在持续集成配置中。OpenSSH 对主机密钥的校验机制和配置选项见官方手册。

SSH 连接已经成功，但依赖版本与本机不一致时，再检查 Package.resolved，不要把认证故障和版本解析混为一谈。Apple 建议将适用的 Package.resolved 提交到仓库；直接调用 xcodebuild 时，可使用 -disableAutomaticPackageResolution，使 CI 遵循锁定的依赖版本。相关规则见前文的 Apple CI 指南。

锁定文件已经提交，CI 解析结果仍然不同怎么办？
先确认 CI 检出的提交确实包含目标项目或工作区对应的锁定文件，再确认该文件中的私有依赖 URL 与 CI 的 SSH 配置相符。检查是否在构建前运行了会更新解析结果的命令；若构建直接由 xcodebuild 执行，核实命令是否带有上述参数。不要先更新依赖或删除解析缓存，否则可能把原始故障掩盖成另一份新的锁定结果。

Package.resolved 的位置取决于项目结构，不能只检查仓库根目录。若使用 Xcode Cloud，则另按私有依赖配置说明处理，避免把 Xcode Cloud 的授权方式直接套用到自建 xcodebuild Runner。

xcodebuild 可能使用 Xcode 自带的 Git 工具链，而不是管理员在系统 Git 中配置的所有 URL 重写、代理或 SSH 特殊规则。Apple 指出，在特定场景下，可通过 -scmProvider system 让 xcodebuild 使用 Mac 的系统 Git 配置；但这应是有证据后的单变量测试，而不是默认开关。操作前先核对前文的 Apple CI 指南。

怎样确认构建进程使用了预期的 SSH 环境？
先让任务以实际执行账户运行，检查该用户的 SSH 配置和仓库 URL，再通过 ssh -vT 确认使用的主机、端口和身份。若普通 SSH 可访问而 xcodebuild 仍失败，进一步比较 Xcode 内置 Git 与系统 Git 的差异；只有日志证明问题与系统 Git 配置相关时，才单独测试 -scmProvider system。

每次只改一处，并保留改动前后的依赖解析日志、实际仓库 URL 和版本结果。否则，账户、代理、Git 选择和缓存同时变化，即使构建恢复，也难以判断真正原因。

在干净工作区用原提交、原执行账户和原构建命令复测；保存失败阶段、解析出的依赖版本和 SSH 诊断结果。Apple 的 Xcode 27 发布说明可用于核对当前版本变化，但不能据此推断每个私有仓库问题都是 Xcode 缺陷；涉及行为差异时，应先回看对应版本的官方发布说明。

按条件选择修复路径：

• 若同一账户下 SSH 认证失败，则修复该账户的密钥授权与 agent；不要扩大共享节点的权限。
• 若认证成功、主机校验失败，则核验服务端指纹并更新该账户的 known_hosts；不要关闭校验来掩盖问题。
• 若仓库可访问但依赖版本偏离，则核实提交中的 Package.resolved、依赖 URL 和自动解析设置。
• 若只有 Xcode 调用失败，且日志指向 URL 重写、代理或特殊 SSH 规则，再单独测试系统 Git 配置。
• 若共享节点无法让执行账户稳定、隔离地取得私有依赖权限，则改用独立执行账户或隔离节点；若原账户和配置均可复现成功，就先修配置，不必因一次失败扩容。

最后，用下表把“修现有环境”和“隔离构建环境”分开判断：

已有共享方案若依赖管理员登录会话，常见隐患是凭据与任务账户不一致、多人共用配置难以隔离，以及缓存和 SSH 规则互相影响。若团队需要稳定的 macOS 执行环境，却不想购置并维护专用实机，可以把JEXCLOUD 的远程 Mac 方案作为隔离节点候选，再结合可选租用方案评估是否适合当前 CI。它不替代凭据管理，也不适合必须使用本地物理接口或长期固定负载的任务；租用前应先验证执行账户、私有包访问和干净构建流程。