先核对构建状态、工作流触发和团队用量，再查看 Apple 系统状态；本周先用真实构建记录定位卡点，只在确认配置无误后决定等待、受控重试或分流。不要把所有排队都当成项目故障，更不要反复取消重跑。
企业 IT 或平台负责人：需要区分 Xcode Cloud 服务状态、工作流设置与团队用量问题，并规划关键任务的备用路径。
iOS 发布负责人：构建迟迟未启动，需要判断等待、重试还是改走其他 CI。
研发效能或 FinOps 负责人：要用团队构建记录评估交付影响，而不是凭个别案例扩容。
SECTION 01 构建状态边界：排队、失败与上传后处理不是一回事
诊断的第一步不是重跑，而是找出构建停在流水线的哪个阶段。至少要分清：预期触发是否发生、构建记录是否已创建、构建是否开始执行、构建动作是否失败，以及构建完成后是否仍在 App Store Connect 处理中。
App Store Connect API 的构建记录包含触发、提交、状态和产物等信息；构建动作还可查看执行进度与完成状态。Apple 将构建动作的完成状态区分为成功、失败、错误、取消和跳过；这些终态不能与尚未完成的等待混为一谈。你可以查看构建记录 API及构建完成状态说明，核对字段含义。
如果构建已完成上传，但 App Store Connect 中还看不到对应构建，也要考虑 Apple 系统后续处理。Apple 说明，上传的构建需要经过系统处理后才会显示；因此，Xcode Cloud 的排队、构建执行和上传后处理是不同问题，应分别查看对应记录。Apple 对上传后处理的说明指出了这一区别。
SECTION 02 工作流触发核验：先确认任务有没有被创建
没有构建记录，不等于构建正在排队。Xcode Cloud 按工作流配置的启动条件监测分支、拉取请求、标签或计划任务；事件不符合条件、工作流未启用，或提交进入了预期之外的分支，都可能让构建根本没有启动。Xcode Cloud 工作流参考介绍了工作流的触发与配置方式。
按以下顺序对照，不要一边改配置一边连续重跑：
- 查看触发提交的分支、标签或拉取请求，确认它与工作流的启动条件相符。
- 在 Xcode 或 App Store Connect 检查目标工作流是否启用，以及实际关联的应用和仓库是否正确。
- 将预期事件、提交标识和构建记录并排核对，确认是“没有生成记录”还是“已有记录但未执行”。
- 在测试或低风险分支上做一次受控触发，再与原始工作流记录比较；保留提交与触发证据，避免把新旧运行混在一起。
- 如果新触发成功而原事件没有对应记录，优先修正触发配置；如果记录仍创建但停在执行前，再进入服务状态和用量核查。
SECTION 03 积压与团队用量：用记录找关联，不猜并发上限
多个任务同时等待时，先检查是否存在重复提交、重复工作流，或同一事件触发了不止一个工作流。Apple 的工作流资料说明，启动条件决定何时创建构建；默认启用的自动取消设置也可能取消同一工作流中被新构建取代的运行。查看构建记录中的触发来源和取消状态，再决定是否调整工作流，而不是假设存在某个固定并发上限或普遍排队时长。
团队用量应作为一项证据，而不是未经验证的归因。App Store Connect 可查看团队及单个应用的用量信息、构建数量、构建持续时间和趋势，也支持导出用量数据；按发生时间与具体构建对照，才有机会判断它是否与当前等待相关。Apple 的 Xcode Cloud 用量说明描述了可查看的数据范围。若用量看起来偏高，也不能单凭这一点推断它就是排队原因。
| 观察到的记录 | 优先核对项 | 下一步判断 |
|---|---|---|
| 没有对应构建记录 | 分支、触发事件、工作流启用状态 | 先验证配置，不按排队处理 |
| 已创建构建，尚未开始 | 触发时间、同一工作流的其他运行、团队用量 | 与其他构建和系统状态对照，再决定等待或一次受控重试 |
| 已进入动作执行并出现失败状态 | 失败动作、构建日志、测试结果 | 按动作日志排错，不当作排队故障 |
| 构建已成功完成，但尚未可供测试 | App Store Connect 构建与处理状态 | 继续查上传后的 Apple 处理，不重复启动相同构建 |
SECTION 04 本周排障时间线：按证据推进到决定点
第一阶段：固定原始证据。 从 Xcode 报告导航器或 App Store Connect 的构建列表记录应用、工作流、提交、触发来源和当前状态。若使用 API，可读取构建记录及其动作；动作接口支持查询执行进度、完成状态和起止时间，单次请求的 limit 上限为 200，这是接口返回条数限制，不代表构建并发额度。构建动作 API列出了可查询字段和请求限制。
第二阶段：判断是否触发。 若记录不存在，逐项核验工作流条件并执行一次受控测试；若记录存在，则保留原运行，继续观察状态和动作信息。不要把“没有触发”写成“排队”，否则后续的故障统计会把配置问题误计为服务等待。
第三阶段：核对积压和用量。 对比同期触发的工作流、重复提交、自动取消情况，以及团队和应用用量趋势。要把这次等待放进项目自己的记录中观察：是否跨多个工作流、是否只集中于特定应用、触发后是否都停在同一阶段。不要从单次异常外推固定时长或扩容结论。
第四阶段：对照 Apple 系统状态。 查看 Apple Developer 系统状态页，并记录检查时点、受影响服务、构建标识和项目范围。状态页没有显示异常，只能说明页面当时未显示已知问题，不能据此排除所有服务端问题。若页面显示相关服务异常，也要保留你自己的构建记录，便于判断受影响范围。
第五阶段：选择等待、重试或升级。 触发和配置仍未确认时，不要重复运行；配置无误且没有新的证据表明重试会改变结果时，保留当前记录并按发布风险决定等待或联系 Apple 支持。需要提交诊断时，附上构建标识、工作流、提交、动作状态、发生时点及系统状态页信息，而不是只写“构建卡住”。
构建完成后，Apple 文档说明构建信息和产物自完成时起可访问 30 天。如果工作流用于正式发布，应按团队的留存要求及时下载并归档日志、构建报告和产物；不要把云端记录当成长期审计档案。Xcode Cloud 首次工作流文档说明了这项留存期限。
SECTION 05 Mac CI 备用方案：按任务边界分流
备用 Mac CI 的作用是承接经过验证、可在独立节点执行的构建或测试任务，不是让 Apple 服务端处理更快。先拆开工作流：哪些动作只依赖代码检出、构建和测试，哪些动作依赖 Apple 账户、签名、上传、TestFlight 或 App Store Connect 后续处理。后一类依赖要单独验证，不能因为换了构建节点就假设处理等待消失。
可将不依赖上传后处理的内部构建、特定测试任务作为候选；正式签名与发布任务则先验证证书和私钥的授权边界、秘密信息存放方式、产物回传、审计日志及重复执行保护。Apple 的工作流参考资料还说明了环境变量的使用与保密要求；因此，分流验收应覆盖凭证保护，而不能只看构建是否跑通。
验收时使用真实项目、真实工作流和非生产凭证，记录输入提交、执行动作、输出产物及回传结果。为关键发布预先写明切换条件、负责人、回切路径和防重复发布检查；如果没有演练结果，不要在正式发布窗口临时把 Mac CI 当作未经验证的救援方案。你也可以先查看 VPSNIX 的服务说明，再按团队实际要求核验接入与交付条件；本文没有本站配置、价格或性能实测数据，因此不对这些项目作承诺。
SECTION 06 可勾选的决策清单
- [ ] 构建记录存在，且状态明确停在开始执行之前：保存原记录，核对同期任务与 Apple 系统状态，再按发布风险选择等待或一次受控重试。
- [ ] 没有对应构建记录：先核验分支、触发事件和工作流启用状态，不要当作服务排队。
- [ ] 已进入动作执行并失败：转查动作日志和测试结果，不要重复排队排查流程。
- [ ] 构建已完成，但 App Store Connect 尚未显示可用构建：单独跟踪 Apple 后续处理状态。
- [ ] 等待影响关键发布，且候选任务可脱离 Apple 后续处理：安排独立 Mac CI 验收，明确签名权限、产物回传和回切条件。
- [ ] 任务强依赖 Apple 服务端处理，或备用节点未经验证：不要把 Mac CI 视为即时修复；继续分别确认 Apple 处理状态和项目侧证据。
SECTION 07 常见问题
“Queued”状态要不要马上取消？
不必。先确认构建是否存在、动作是否开始，以及是否有新构建取代旧运行；取消会改变证据链，也可能让你无法分辨原任务与重试任务。只有确认原任务不再需要，且团队的发布策略允许时，才按工作流管理规则取消。
状态页正常，是否代表排队一定是配置问题？
不是。状态页是服务状态核对点，不是对每个项目构建的完整诊断。你仍需将页面显示与具体构建的触发、记录和动作状态对照；若证据无法解释持续等待，可整理记录联系 Apple 支持。
团队用量接近计划额度，就应该立即切换 CI 吗？
不应只看计划或预算推断原因。先检查 App Store Connect 可见的团队及应用用量趋势，并与发生等待的构建记录对齐；再评估任务时效、重试成本和备用节点维护成本。只有关键任务反复受阻且备用路径通过验收，分流才有决策依据。
SECTION 08 结尾决策：备用节点解决的是承载，不是 Apple 后端
只依赖 Xcode Cloud 的路径简单，但遇到等待时，你对服务端执行环节的控制有限；把所有构建留在员工本地 Mac，又会让节点可用性、环境一致性和维护责任分散；自购专用 Mac 则需要承担采购、配置、更新和闲置容量管理。若这些限制已影响关键发布，可评估 VPSNIX 的远程 Mac 租赁作为独立 CI 承载选择，并先用真实工作流验证权限、产物回传和回切流程，再决定是否扩大使用；它不能替代对 Apple 服务端处理状态的确认。需要比较租赁方案时，可查看 VPSNIX 套餐信息，并以页面实际列出的条件为准。
SECTION 09 常见问题 FAQ
Xcode Cloud 的构建一直显示 Queued，排查从哪里开始？
先在 Xcode 或 App Store Connect 中确认是否已经生成对应构建记录，再核对其工作流、提交和当前动作状态。记录存在但尚未开始执行，才属于等待执行方向；如果没有记录，应优先查触发条件。不要连续取消并重跑，以免增加重复任务、模糊原始证据。
怎么分辨 Xcode Cloud 排队是服务问题还是工作流没触发？
将预期触发事件与工作流记录逐项对照：分支、拉取请求或标签是否匹配，工作流是否启用，提交是否进入关联仓库。若没有对应构建记录，优先验证配置；若记录已创建但未开始，再对照团队内其他工作流和 Apple 系统状态。状态页正常也不能单独证明服务端完全无异常。
团队的 Xcode Cloud 用量会不会导致构建排队？
用量信息值得核对，但不能只凭预算、计划名称或一次失败，就认定用量已导致排队。查看 App Store Connect 中团队及应用的 Xcode Cloud 用量趋势，并将构建数量、持续时间与发生等待的记录按时间对照；若没有相关性证据，继续检查触发、动作状态和服务状态。
哪些 iOS 任务适合从 Xcode Cloud 转到备用 Mac CI？
优先评估可以在独立 Mac 上构建、测试并留存产物的任务，例如内部验证或不依赖 Apple 后续处理的测试环节。签名、凭证、产物回传和重复执行都要先验证；上传后的 Apple 处理仍须单独观察，因此备用 Mac CI 不能修复 Apple 服务端的问题，也不应未经演练就接管正式发布。