症状：本地构建正常，Xcode Cloud 却在依赖阶段失败。
最快解法：先从构建日志找到首个有效错误，再判断是脚本未运行、依赖取不到，还是 pod install 本身失败；核对 Podfile、Podfile.lock 和仓库权限后，再决定是否调整环境。
适合使用 CocoaPods、接入 Xcode Cloud 后构建失败的独立开发者和小团队。
如果你正在排查私有依赖、锁定文件或构建脚本，或需要判断是否继续使用托管构建环境，这份排查流程可以帮你把问题拆开处理。
先看失败发生在哪个环节
别把“找不到 pod”“无法克隆依赖”和“Pod 安装后编译失败”统称为 CocoaPods 不兼容。先打开 Xcode 的 Report navigator，进入失败构建对应的 action，展开日志；也可以在 App Store Connect 查看构建报告。Apple 建议从失败构建的日志与状态定位问题，而不是只依据本地结果推断。可参考 Apple 关于 Xcode Cloud 构建故障的排查说明。
截取日志中最早出现、能说明失败原因的错误行，并记下该步骤之前是否成功。不要把账号、私有仓库地址、令牌、私钥或完整认证日志贴到公开问题中；用于协作的日志应先脱敏。
| 日志迹象 | 优先核对 | 下一步判断 |
|---|---|---|
| 没有脚本输出，直接进入 Xcode 构建 | 脚本目录、文件名、执行权限 | 构建是否识别并运行脚本 |
pod: command not found |
运行环境中的命令路径、脚本 shell | 工具确实缺失，还是脚本没有使用预期环境 |
| 克隆、下载、认证报错 | 仓库地址、凭据、访问权限、网络响应 | 是否能访问对应依赖源 |
| CocoaPods 报解析或安装错误 | Podfile 与 Podfile.lock 是否匹配 |
锁定状态、源配置或依赖规格是否有问题 |
| Pod 安装完成，之后 Xcode 编译失败 | 后续构建日志、工作区和工程状态 | 故障是否已离开 CocoaPods 阶段 |
Xcode Cloud 构建时为什么找不到 pod 命令？
Apple 文档说明，Xcode Cloud 构建环境已提供 CocoaPods。因此，出现找不到命令的报错时，不要立刻认定平台没有 CocoaPods；先确认报错发生在哪个脚本、脚本是否按预期执行，以及运行时使用的命令路径。只有日志确实证明构建环境无法找到所需工具，才考虑在构建脚本中安装或配置工具。可核对 Apple 的 Xcode Cloud 依赖准备说明。
脚本没有执行时，先核对入口约定
Apple 文档规定，Xcode Cloud 识别的自定义构建脚本放在项目或工作区旁的 ci_scripts 目录中；用于依赖准备的常见入口是 ci_post_clone.sh。脚本还应纳入 Git、具有执行权限，并在首行提供 shebang。Apple 说明，缺少 shebang 或执行权限时，脚本可能按默认 shell 执行，行为因而与预期不符。可对照 Apple 的自定义构建脚本规则。
CocoaPods 依赖安装应该放在哪个构建脚本中？
需要在拉取代码后、Xcode 开始构建前准备依赖时，通常把 pod install 放入 ci_post_clone.sh。先核对脚本是否位于预期目录、名称是否正确，再确认它是否可执行、是否已提交，以及日志里是否真的出现脚本输出；“构建已启动”不能证明依赖准备脚本已经运行。脚本入口与依赖准备时机应按 Apple 的文档和项目工作流核实。
示例只展示最小结构。运行前，确认脚本可执行，并根据项目实际目录核对 pod install 的执行位置：
#!/bin/sh
set -e
pwd
pod --version
pod installset -e 会让命令失败时中止脚本，避免安装失败后流程仍继续并产生误导性结果。排查阶段可以输出当前目录和 pod --version，但不要打印令牌、私钥或包含认证信息的完整远程地址。不要用 sudo 作为补救方案；Apple 的构建脚本权限说明明确限定了脚本可使用的权限边界。
依赖解析不一致时，先保住锁定状态
检查项目当前提交的 Podfile 与 Podfile.lock 是否来自同一套依赖变更，并确认两者均已纳入版本控制。CocoaPods 官方指南说明，pod install 会依照锁定文件安装已记录的 Pod 版本；对于锁定文件中已有的依赖，它不会为了寻找更新版本而自动重新解析。移除锁定文件或改用 pod update，可能改变依赖解析结果，不能当作通用修复。可对照 CocoaPods 对 pod install 与 pod update 的说明及将 CocoaPods 纳入项目的指南。
| 发现的问题 | 建议处理 | 不建议的快捷操作 |
|---|---|---|
Podfile.lock 未提交或与预期分支不符 |
恢复项目审核过的锁定文件，再重跑构建 | 直接删除锁定文件后提交新的解析结果 |
| 只是需要重装已锁定的依赖 | 保留锁定文件，运行 pod install |
为“清理依赖”执行全量更新 |
| 明确计划升级某个 Pod | 在开发环境有意更新，并审核差异后提交 | 把依赖升级和 CI 故障修复混成一次变更 |
| Pod 已安装，后续才有编译错误 | 转查 Xcode 编译日志及工作区状态 | 反复改动锁定文件 |
Podfile.lock 需要重新生成吗？
只有在你有意更新依赖、确认锁定文件损坏，或项目变更要求重新解析时，才生成并审核新的锁定结果。若本地同一提交可以通过，优先把对应分支的 Podfile.lock 纳入构建并保持不变；如果文件未提交或被错误分支覆盖，先恢复正确版本，再重试。CocoaPods 使用指南建议将 Podfile 和 Podfile.lock 保存在版本控制中。
私有依赖失败时，区分地址、认证与网络
私有 CocoaPods 依赖的失败，不一定都由凭据引起。先按日志判断：仓库地址或分支是否拼错；构建账号是否获得只读克隆权限；认证是否过期或没有注入当前工作流；依赖源是否可访问、是否返回异常。确认具体原因前，不要把令牌写进 Podfile、仓库或公开脚本。
Apple 说明，Xcode Cloud 可以连接受支持的源代码管理服务，并在发现缺少访问权限时引导处理。如果 CocoaPods 的 Podspec 或依赖来自独立的私有 Git 仓库，应另行确认当前构建流程能否访问该仓库。仓库授权和访问边界可参照 Apple 的源代码管理配置说明。
Xcode Cloud 提供预定义环境变量，也允许在工作流中配置自定义变量；标记为 secret 的自定义变量会在日志中遮蔽。使用凭据时，只授予拉取依赖所需的权限，并检查脚本不会通过调试输出意外泄露凭据。具体行为可核对 Apple 的环境变量参考。
私有 CocoaPods 依赖在构建环境中无法获取时，先检查什么？
先确认失败的是主代码仓库还是某个依赖仓库，再核对凭据来源、权限范围与访问方式。若项目把依赖放在另一个 Git 服务实例中，还要确认该实例已授权并可被构建访问；凭据配置无误但日志仍显示连接或响应失败时，再检查仓库地址、网络限制及依赖源状态。不要把私有仓库访问问题直接归结为 CocoaPods 安装故障。
修复后用干净构建验证，不依赖偶然缓存
按以下顺序复测，并记录所用分支、提交和工作流环境：
- [ ] 从失败构建日志找到首个有效错误，并标记失败发生在脚本、下载、解析、安装还是后续编译。
- [ ] 检查
ci_scripts目录、脚本名称、shebang、执行权限和 Git 提交状态。 - [ ] 确认
Podfile、Podfile.lock与当前提交一致；没有明确升级计划时，保留原锁定结果。 - [ ] 对私有依赖逐个验证仓库地址、构建权限和凭据注入方式，并检查日志没有泄露认证信息。
- [ ] 在依赖输入固定的提交上重新构建，确认日志显示 Pod 安装通过，并继续检查后续 Xcode 构建或归档结果。
- [ ] 若切换构建环境，重新验证依赖获取、安装和后续构建链路；不要把单次通过当作所有分支都已修复。
Xcode Cloud 使用临时构建环境，因此复测应以仓库中可重建的输入为准，而不是假设上一次构建留下的文件会继续存在。若问题仍需排查，可从失败 action 的日志和构建产物中追踪故障发生的位置；不要仅凭一次成功或失败推断整条构建链路的稳定性。
何时继续修复 Xcode Cloud，何时评估远程 Mac？
- 若脚本入口、锁定文件或仓库访问配置有明确错误，而且能通过受支持的工作流脚本或凭据设置修复，先留在 Xcode Cloud，按上面的清单复测。
- 若问题只在个别依赖源访问失败，优先修正该源的授权或网络配置，不要因为一次下载失败就迁移整条构建链路。
- 若构建流程确实需要自主管理的 macOS 工具、权限或凭据环境，而受支持的脚本与工作流无法满足，再评估远程 Mac；同时明确谁负责系统更新、密钥管理和构建机维护。
- 若项目长期需要稳定的重负载构建、必须连接物理接口，或团队没有维护自主管理环境的能力，租赁远程 Mac 未必合适，应先比较自购设备、现有 CI 和远程环境的责任边界。
自主管理的 macOS 环境可让你直接控制工具安装和依赖访问，但也意味着你要承担环境维护、凭据保护与故障复现；它不是所有 CocoaPods 故障的自动解法。如果你的问题确实落在这些控制边界上，可先查看 KVMFLUX 的适用场景，再结合租赁方案信息判断是否适合短期验证或发布准备。若当前方案反复受限于无法调整的工具或凭据环境，租用远程 Mac 可以提供另一种环境控制选择；但在迁移前，仍应在目标环境重新验证依赖拉取、Pod 安装和完整构建。