asc-release-flow

App Store 发布编排

使用此技能将发布从已批准的计划推进到 App Store 审核。Game Center 项目准备工作在此处进行；其他阻塞项诊断和审核恢复请使用 asc-submission-health。

职责边界

此技能负责：

• 准备元数据并关联构建版本；
• 发布 IPA 或在本地构建；
• 提交已准备好的版本；
• 组装包含多个项目的审核提交。

如需准备或关联 Game Center 项目，或处理相关阻塞项，请参阅准备部分。只有在 App 版本已完成暂存且已选择多项目流程后，才使用该参考文档中的组装和提交部分。遇到其他验证阻塞项、提交卡住、取消或重试决策时，请切换到 asc-submission-health。

在当前任务中切换技能，并保留已确定的目标、授权和已验证的进度。失败的关卡会阻止依赖它的变更操作，但不会阻止诊断或独立且已获授权的工作。继续执行已授权的修复，然后恢复此流程；只有当修复超出约定范围时，才请求新的授权。

前置条件

• 确定 APP_ID、版本字符串，以及在需要时确定 VERSION_ID 和已存在构建版本的 BUILD_ID。
• 使用 asc auth login 或 ASC_* 环境变量配置身份验证。
• 确认目标平台。除非 App 面向其他平台，否则使用 IOS。
• 当工作流需要应用元数据时，将规范元数据保存在 ./metadata 中。
• 执行会产生变更的高级命令前，必须先进行试运行；提交时必须使用 --confirm。

选择发布流程

意图	命令
准备元数据并关联已有构建版本，但不提交	asc release stage
提交已准备好的版本	asc review submit
上传 IPA 或在本地构建，然后可选择提交	asc publish appstore
提交包含 IAP、订阅或 Game Center 版本项目的 App 版本	较低层级的 asc review 提交命令

如果某个流程已创建审核提交，请勿混用其他流程。先检查现有提交，再使用匹配的较低层级命令继续。

运行就绪检查

对已关联预期构建版本的版本运行此检查。对于暂存流程，先完成暂存已有构建版本；asc release stage 会关联构建版本并运行验证，之后即可进行此检查。不要将预期中暂存前出现的“未关联构建版本”结果转交给 asc-submission-health。

提交前先进行验证：

asc validate --app "APP_ID" --version "1.2.3" --platform IOS --output table

当警告也必须阻止自动化时，使用严格模式：

asc validate --app "APP_ID" --version "1.2.3" --platform IOS --strict --output table

数字商品是硬性关卡。如果发布包含 IAP 或订阅，请停止并在 asc-submission-health 中运行相关产品检查。只有在这些检查没有阻塞问题，且预期的产品版本已准备就绪后，才恢复此流程。

对于 Game Center 项目，只完成准备每个项目，然后返回此流程。就绪检查期间，不要组装或提交多项目审核提交。

如果 App 验证报告了 Game Center 项目阻塞项，请停止并使用该准备部分。如果唯一的阻塞项是暂存流程中尚未关联的构建版本，请继续执行暂存部分。对于其他所有阻塞项，请暂停依赖这些项的发布操作，并使用 asc-submission-health；在已授权的修复通过验证后恢复流程。

暂存现有构建

使用 asc release stage，在更改版本前验证所选构建属于该 App，应用或复制元数据、附加构建，并运行验证，而不创建审核提交。

预览由元数据驱动的暂存计划：

asc release stage \
  --app "APP_ID" \
  --version "1.2.3" \
  --build-id "BUILD_ID" \
  --metadata-dir "./metadata" \
  --dry-run \
  --output table

应用审核后的计划：

asc release stage \
  --app "APP_ID" \
  --version "1.2.3" \
  --build-id "BUILD_ID" \
  --metadata-dir "./metadata" \
  --confirm

--metadata-dir 接受规范元数据根目录，其中包含 app-info/ 和 version/<version>/，布局与 asc metadata push --dir 相同。需要沿用本地化元数据时，请使用 --copy-metadata-from "1.2.2"，而非 --metadata-dir。如果希望警告导致暂存失败，请添加 --strict-validate。

如果元数据计划包含删除操作，试运行和确认后的运行都需要 --allow-deletes。请先审核这些删除操作；当本地缺少某个区域设置时，此标志也会禁用回退到现有区域设置的功能。

如果此次发布包含路由 App 覆盖范围，请使用 --routing-coverage-file "./coverage.geojson"。此实验性步骤会在修改前验证 GeoJSON，并在就绪检查前暂存该文件。

结构化输出会在 steps[] 开头包含一个 validate_build 步骤。请按名称而非数组位置匹配步骤。

提交已准备好的版本

在元数据、审核详情、可用性、构建处理和产品就绪状态均已解决后，使用 asc review submit。

asc review submit --app "APP_ID" --version "1.2.3" --build-id "BUILD_ID" --dry-run --output table
asc review submit --app "APP_ID" --version "1.2.3" --build-id "BUILD_ID" --confirm

如果已知确切的版本 ID，请使用 --version-id "VERSION_ID"，而非 --version。使用 --build-id 选择构建；或者使用 --build-number "45" 跳过构建 ID 查询，此选项仅匹配该 App、版本字符串和平台对应的构建。上传后应优先使用 --build-number，而非 --latest，因为后者仍可能选中上一次上传的构建。添加 --wait，可在附加前等待处理完成。

上传或构建，然后发布

如果发布从 IPA 或本地 Xcode 项目/工作区开始，请使用 asc publish appstore。

预览 IPA 上传和提交：

asc publish appstore \
  --app "APP_ID" \
  --ipa "./App.ipa" \
  --version "1.2.3" \
  --submit \
  --dry-run \
  --output table

审核计划后运行：

asc publish appstore \
  --app "APP_ID" \
  --ipa "./App.ipa" \
  --version "1.2.3" \
  --submit \
  --wait \
  --confirm

对于本地构建模式，请提供 --workspace 或 --project，并搭配 --scheme，而非使用 --ipa。如果发布命令应在确保版本存在后应用规范版本元数据，请使用 --metadata-dir。

如果用户只想上传并附加构建，请省略 --submit。

提交多个审核项目

如果 App 版本必须与版本化 IAP、订阅、订阅组或 Game Center 项目一同发布，请阅读 references/multi-item-submissions.md。只添加用户已解决并检查过的项目。

提交后的交接

报告：

• App、版本、平台、构建和提交 ID；
• 运行了哪个通道，以及是否已完成；
• 在用户授权下执行了哪些修改；
• 用于监控生成的提交的确切命令。

使用 asc-submission-health 进行监控、取消、诊断拒绝原因或决定是否重试。

防护措施

• 不要使用已移除的 submit-preflight、submit-create 或 release-run 快捷命令。
• 只有在试运行计划符合所请求的发布内容后，才添加 --confirm。
• 如果该版本已有审核提交，请勿再创建第二个。
• 不要将验证失败转变为部分发布；请在失败的关卡处停止。
• 在自动化脚本中封装命令时，将数据保留在 stdout，将诊断信息保留在 stderr。