症状：Xcode Cloud 排队，构建一直没有开始。
最快解法：先确认构建状态，再检查工作流是否触发，最后查看 Apple Developer System Status；只有这些都无法解释延迟时，才验证备用 Mac 构建路径。
适合遇到构建迟迟未启动、想区分排队与失败的独立开发者；需要排查工作流触发条件的 CI 工程师；以及要判断是否准备另一条已验收构建路径的发布负责人。
Apple 将 Xcode Cloud 的执行进度定义为 PENDING、RUNNING 3 种状态。PENDING 表示构建尚未开始，不代表编译失败；因此，先看记录里的状态和提交，再找原因，不要一看到等待就改本地项目。(developer.apple.com)
Xcode Cloud 构建状态待处理时，先查什么？
从 App Store Connect 或 Xcode 的构建记录找到对应的工作流、提交和状态。App Store Connect API 的构建记录还包含触发信息、状态和构建产物，可用来核对记录是否对应预期提交。(developer.apple.com)
排查里程碑一：确认这次构建是否真正进入队列。
- 如果状态是
PENDING，构建还没开始。继续检查工作流启动条件和当前提交。 - 如果状态是
RUNNING，构建已经开始。转到具体动作和日志排查，不要继续把问题归为排队。 - 如果已经结束，查看完成状态。Apple 列出的结果包括成功、失败、内部错误、取消和跳过；这些状态含义不同，不能把取消或跳过当作编译失败。(developer.apple.com)
别只凭一个界面提示推断根因。 对照最近一次成功构建和当前提交，记下工作流名称、分支或拉取请求、触发时间，以及状态变化。这样可以区分“工作流没触发”和“构建已创建但尚未开始”。
工作流配置还是服务异常？沿触发链排查
如果没有对应的新构建记录，优先核对触发条件，而不是先等待。Apple 说明，工作流启动条件可针对分支变化、拉取请求、标签或定时任务配置；建议的初始工作流也会关联产品、方案和构建动作。条件未覆盖当前分支或事件时，推送代码并不必然启动目标工作流。(developer.apple.com)
排查里程碑二：从最近一次成功运行反向比对。
- 确认目标工作流已启用，且不是选错了应用、产品或方案。
- 对照本次提交的分支、拉取请求目标和工作流的启动条件。
- 检查这次提交是否符合条件，以及源代码仓库和所需依赖是否已授权给 Xcode Cloud。
- 在 App Store Connect 的 Xcode Cloud 工作流管理页或 Xcode 中复查配置；必要时按 Apple 文档手动启动构建，确认工作流本身是否能创建运行记录。(developer.apple.com)
若记录显示 CANCELED 或 SKIPPED，检查该启动条件的 Auto-cancel Builds 设置和连续提交情况。Apple 说明，开启此选项后，同一工作流有新构建进入队列时，进行中的构建可能被自动取消；连续推送时，较早的构建也可能被跳过。因此，先确认被取消的是哪一个提交，再决定是否重跑。(developer.apple.com)
排查里程碑三：核实 Apple 服务状态并留证。
在 Apple Developer System Status 查看 Xcode Cloud 相关服务是否报告异常。状态页没有显示问题，不能证明账户、工作流或服务端一定没有问题；它只是排除公开服务异常的一项检查。若问题仍在，保存受影响的工作流、提交标识、状态变化和大致发生时间，再沿 Apple 官方支持路径提交记录。
状态已运行或报错，就转查动作日志
状态一旦变为 RUNNING，或记录已经显示失败、内部错误，排队就不再是当前主要问题。打开构建报告，展开失败动作并查看日志；Apple 也支持从 App Store Connect 查看构建详情、下载构建日志和其他产物。(developer.apple.com)
排查里程碑四：按失败动作复现，而不是盲目重试。
- 依赖解析失败：确认
Package.resolved已提交且没有被.gitignore排除。私有依赖还要确认 Xcode Cloud 有权限访问。 - 第三方工具缺失：核对工作流是否安装了项目所需工具，以及安装脚本是否位于预期位置。Apple 指出，临时构建环境并不预装所有第三方工具。
- 构建或测试动作失败：先读失败动作的日志，再对照工具链、方案和构建配置。依照 Apple 的建议，在本地用同一提交复现，区分项目配置错误与服务侧问题。(developer.apple.com)
在单独的 Mac 上验证备用路径时，也要固定提交和关键依赖版本，并记录使用的 Xcode 配置、执行的构建动作、测试结果与交付产物。否则即使备用构建成功，也难以证明它和原工作流验证的是同一份代码。Apple 关于持续集成的文档建议提交 Package.resolved，以固定 Swift 包依赖版本；这能减少复现差异，但不能解释 Xcode Cloud 为什么尚未启动。(developer.apple.com)
用两张对照表决定下一步
第一张表用于分流：不要把“等待”“没有记录”和“构建失败”混为一类。
| 观察到的情况 | 优先检查 | 下一步 |
|---|---|---|
PENDING，已有构建记录 |
工作流触发、提交与队列状态 | 记录状态变化；若配置符合预期，再查服务状态 |
| 找不到本次提交对应的构建 | 工作流启用状态、分支或拉取请求条件、目标产品 | 修正触发条件，或按官方方式手动启动以验证 |
CANCELED 或 SKIPPED |
Auto-cancel Builds、后续提交 | 确认状态对应的提交，再决定是否重跑 |
RUNNING |
正在执行的动作与日志 | 排查工具链、依赖和项目配置 |
FAILED 或 ERRORED |
失败动作、构建日志及同一提交的本地复现 | 判断是项目问题还是需要向 Apple 升级反馈 |
第二张表用于判断是否值得准备另一条构建路径。这里的“独立 Mac 构建”是验证和交付的备用选项，不是修复 Xcode Cloud 服务端队列的方法。
| 选择 | 适用条件 | 主要限制 |
|---|---|---|
| 继续排查 Xcode Cloud | 构建未启动，触发条件或公开服务状态尚未核实 | 仍依赖原工作流与服务状态 |
| 在另一台 Mac 验证同一提交 | 有发布节点，且项目需要按计划完成构建或测试 | 需要自行验收工具链、依赖、签名和交付步骤 |
| 暂不切换 | 非紧急任务，或项目尚无经过验证的替代流程 | 不要把状态页正常当作问题已排除 |
如果你的当前方案只有 Xcode Cloud，一旦工作流配置、账户权限或服务侧状态无法解释延迟，就缺少独立复现和按发布计划交付的路径；单纯反复重试也无法区分项目问题和平台问题。远程 Mac 可以作为另一条真实 macOS 构建路径，但不会消除 Xcode Cloud 的服务侧延迟。若只是临时需要 Mac 环境，可先查看 armrdp 的远程 Mac 使用文档，再按项目实际的 Xcode 工具链、构建动作和交付要求验收；若工作负载长期稳定、持续高频，或必须直接接入本地物理设备，则应先评估自购 Mac 是否更合适。需要临时构建节点时，可进一步了解 armrdp 的 Mac 环境方案。