Xcode Cloud 构建产物怎么自动归档？2026 指南

构建结束后才发现日志、测试结果或归档包没保存？等需要复现时，云端文件可能已无法访问。
最快做法：在构建完成后尽快下载所需产物，核验文件，再存入团队控制的归档位置；低频构建可手动保存，重复流程用 App Store Connect API 自动化。

这篇指南适合需要复现历史失败、追查崩溃符号，或保存测试证据的开发者、CI 工程师和小型团队。
如果只需要临时查看一次构建报告，不必把每个文件都纳入长期留存。

Xcode Cloud 构建产物自动归档，先按用途划定范围

Xcode Cloud 的构建产物不只有可发布的应用包。Apple 列出的产物包括详细构建日志、导出的应用归档或二进制文件，以及测试结果包；API 资源还会提供产物类型、文件名、文件大小和下载地址。发布追溯、崩溃诊断、失败复现，所需文件并不相同。可先对照 Apple 的 Xcode Cloud 产物与归档说明 确认范围。

符号信息尤其容易被忽略。分发版本的归档产物可能需要用于崩溃报告诊断；如果团队只存了可安装包，却没有保存对应符号或无法关联到构建的记录，事后排查会多一道补救工作。Apple 将构建日志、应用归档、测试结果和符号信息等列为构建相关产物。

⚠️ 不要把“能下载”理解成“必须全留”。 先写清每类文件要解决什么问题，再决定保留范围；否则存储会越堆越多，真正要找的证据仍可能没有索引。

构建完成后，先用报告确认要保存什么

低频构建或需要人工审批时，可以先走 Xcode 或 App Store Connect 的手动流程。Xcode 的构建报告可查看动作与日志；App Store Connect 的 Xcode Cloud 构建页也能查看构建信息。人工下载适合有人负责复核的场景，但它容易漏掉文件，也容易出现“文件下载了，却没人知道对应哪个提交”的情况。Apple 的说明也列出通过 Xcode 或 App Store Connect 下载产物的方式。

手动操作时，不要只看“构建成功”。展开构建动作，确认需要的日志、归档或测试结果确实存在，再下载。文件保存后，马上记录构建编号、工作流、提交标识、文件类型和下载时间。Xcode 报告支持按动作查看日志，产物种类则以当前构建实际提供的文件为准。

需要让团队其他成员按同一方式操作时，可把归档目录、命名规则和权限要求写进内部 runbook。技术支持渠道不应替代团队自己的归档记录；遇到服务使用问题时，再参考帮助与支持信息。

第一步：准备 API 认证与最小访问范围

App Store Connect API 请求需要 JWT 授权。Apple 的密钥文档区分团队密钥与个人密钥，并要求保护私钥；私钥下载后应存放在受控环境，不要提交到代码仓库、写进脚本仓库的配置文件，或打印到构建日志。给自动归档任务使用的密钥，应按职责分配合适权限，避免为了省事授予不必要的广泛访问。具体密钥管理要求可查阅 Apple 的 API 密钥说明。

生成 JWT 时，按 Apple 文档要求构造并签名，再作为 Bearer 凭据用于 API 请求。令牌有效期、作用范围和资源权限均应遵循官方要求；不要把 JWT 本身写入归档元数据，也不要在报错日志中输出完整请求头。令牌生成步骤以 Apple 的 JWT 请求认证文档 为准。

第二步：从构建动作定位 Xcode 构建产物

API 的定位顺序可以按资源关系理解：先确认目标 Xcode Cloud 产品和构建，再列出该构建执行的动作，然后读取目标动作的产物。Apple 将构建运行、构建动作和产物分别作为 API 资源；构建动作还能关联产物、问题和测试结果。这样做的好处是，归档记录能保留“哪个构建的哪个动作产生了这个文件”，而不是只剩一个无上下文的压缩包。可参照 Xcode Cloud 工作流与构建 API 资源说明 理解它们之间的关系。

Apple 提供了列出某个构建动作全部产物的接口；返回字段可以包含文件类型、文件名、大小和下载地址。团队应先按官方文档确认当下请求参数和返回字段，再将它们映射到自己的归档流程，不要把字段名称或接口行为凭记忆写死。列表请求的参数和返回内容见 列出构建动作全部产物的 API 文档。

可将 API 调用逻辑组织成下面的顺序。这里强调的是资源之间的查找关系，不是 Apple 保证提供的自动归档触发器：

确定目标产品与构建
→ 获取该构建的动作
→ 按动作列出产物
→ 读取产物详情
→ 下载文件并记录构建元数据

自动化的启动方式由团队自己的工作流决定。可以由现有调度器轮询，或由内部系统在获知构建完成后启动归档任务；不要误以为 Xcode Cloud 一定会在构建完成时向你的存储系统推送文件。API 文档说明可读取构建与产物数据，但并不等于 Apple 替团队定义了归档触发和存储责任。

第三步：拿到下载地址后立即下载，不保存为长期入口

产物详情中的 downloadUrl 是获取文件用的地址，不是团队自己的归档链接。Apple 明确说明，返回的下载地址只在有限时间内有效；因此流程应当在取得地址后尽快下载，并将文件写入团队控制的存储。不要把地址写进长期台账后，指望数周或数月后仍能直接打开。字段定义可查看 产物属性文档，单个产物详情接口也说明了下载地址的时效限制，见 读取 Xcode Cloud 产物信息的 API 文档。

推荐把“读取详情”和“下载文件”放在同一个归档任务里执行。下载失败时，记录产物 ID 与构建标识，重新查询产物信息后再试；不要盲目重复使用已保存的旧地址。下载成功后再写入归档索引，避免索引显示“已归档”，实际文件却未完整落盘。

第四步：核验文件，再宣布归档完成

API 返回文件名、类型和大小等描述信息，可用于建立基本校验。下载任务至少应检查请求是否成功、文件是否非空、文件大小是否与返回信息相符，并确认文件类型与本次动作预期一致。对归档包和测试结果包，还要在团队实际使用的工具中试开一次；“下载完成”不等于“之后一定能读取”。

• [ ] 归档目录能关联到产品、工作流、构建编号和提交标识。
• [ ] 文件名、类型和大小已与 API 返回的产物信息核对。
• [ ] 下载失败时任务会记录错误，并重新查询有效下载地址。
• [ ] 归档文件已实际打开或读取，确认不是空文件或错误类型。
• [ ] JWT、私钥与临时下载地址没有出现在普通日志或公开目录。
• [ ] 归档权限仅开放给负责发布、诊断或审计的人员。
• [ ] 清理责任人和团队自定的保留规则已写入文档。

如果团队需要在 macOS 上做归档后的项目验证、符号处理或其他后处理，应把这些步骤与“下载 Xcode Cloud 产物”分开验收。是否需要额外的 Mac 环境，取决于工具链是否必须在 macOS 执行；可先评估远程 Mac 是否能匹配实际工作流，而不是把 API 下载问题误归因于构建主机。

第五步：区分 Apple 的可访问期限与团队留存策略

Apple 文档说明，Xcode Cloud 的构建信息和产物从构建完成时起最多可访问 30 天。这只是云端可访问期限，不代表团队应保留 30 天，也不代表 Apple 云端期限可以替代内部备份。需要长期追溯的发布产物、诊断材料或测试证据，应在可访问期间下载，并按团队自己的发布、排障和合规要求制定保留与清理规则。

保留策略不宜用“全部永久存档”一刀切。可按用途区分：发布版本关联的归档与符号优先保留；失败复现所需日志按问题处理和审计需要保留；临时测试文件则依据团队规则定期清理。存储周期、容量和清理频率属于团队决策，不要把它们说成 Apple 的统一规定。

若归档后的后处理必须在 macOS 工具链中完成，可以根据实际依赖评估是否需要独立的 Mac 环境；只调用 API 并保存文件的流程则未必需要额外主机。确定有远程 Mac 使用需求后，再查看套餐与价格信息，并按真实工作流比较租赁、自购 Mac 和现有构建环境的维护成本。

常见问题

Xcode Cloud 的构建产物能保存多久？

Apple 文档说明，构建信息和产物从构建完成时起最多可访问 30 天。这个期限说的是 Xcode Cloud 中的可访问时间，不是团队自己的归档保留策略。需要长期追溯的文件，应在期限内下载到团队控制的存储中，并明确谁负责清理和权限复核。

如何通过 App Store Connect API 获取 Xcode Cloud 产物？

先用 API 找到目标产品和构建，再读取构建动作关联的产物列表，取得产物 ID、文件名、类型及下载地址。随后立即下载到自有存储，记录构建编号、提交和工作流，并检查文件是否完整、类型是否符合预期。API 请求需要有效 JWT，私钥应保存在受控的凭据存储中。

日志和测试证据应该怎样纳入归档？

低频构建可在 Xcode 报告或 App Store Connect 中查看并手动下载日志包、测试结果包和需要的归档文件。重复流程则可按构建动作获取相应产物，保存原始文件并关联提交、工作流与构建标识。测试截图或诊断日志可能包含内部信息，因此归档目录也要设置访问权限。

API 返回的产物下载地址可以长期复用吗？

不可以把它当长期链接。Apple 的 API 文档说明，返回的下载地址只在有限时间内有效；文档没有承诺它是长期存储地址。应在取得地址后尽快下载文件，持久化保存文件本身及构建元数据，地址失效后重新查询产物，而不是依赖旧链接。

对于只需偶尔下载和人工审核产物的团队，现有手动流程可能更简单；但它依赖人员及时操作，且容易漏记构建关联信息。若归档之后还要在 macOS 环境中执行项目验证或后处理，独立的 Mac 环境可以把下载后的验收步骤纳入自动化；反过来，如果流程只调用 API 并保存文件，就没有必要为此额外增加 Mac 主机。需要评估远程 Mac 工作流时，可以先对照团队的工具链、访问权限和运维责任，再决定是否租赁。

常见问题