gpc-release-flow

GPC 发布流程

适用场景

在以下任务中使用此技能：

• 将 AAB/APK 文件上传到 Google Play
• 在任意轨道（internal、alpha、beta、production）上创建发布
• 在轨道之间提升发布
• 管理分阶段发布（提高比例、暂停、恢复、完成）
• 设置发布说明
• 使用 gpc publish 执行端到端发布工作流
• 使用 gpc validate 进行提交前验证
• 查看各轨道的发布状态
• 更新私有应用（通过 v0.9.56+ 中的 gpc enterprise publish 创建）——创建自定义应用后，后续所有操作都使用本技能中的标准命令，并指定分配的 packageName

不适用：

• 为 Managed Google Play 创建新的私有应用——请使用 gpc-enterprise（v0.9.56+）。创建后，返回此处进行版本上传和轨道管理。

所需输入

• AAB/APK 文件的路径
• 目标轨道（internal、alpha、beta、production 或自定义）
• 发布比例（用于分阶段发布）
• 发布说明（内联提供或从文件读取）
• 是否需要使用 --dry-run（预览但不执行）

流程

0) 发布前验证

上传前，运行发布前合规扫描器并验证软件包：

# Policy compliance scan (offline -- checks manifest, permissions, 64-bit, secrets)
gpc preflight app-release.aab --fail-on error
gpc preflight app-release.apk --fail-on error  # APK: manifest checks run on AABs only

# File format and track validation
gpc validate app-release.aab
gpc validate app-release.aab --track beta  # Validate for specific track

gpc preflight 会根据 Google Play 政策检查 AAB/APK（目标 SDK、权限、本机库等）。gpc validate 会检查文件格式、版本代码冲突和轨道兼容性。

1) 上传并发布

A) 快速发布（单条命令）

publish 命令会处理完整流程——上传、分配轨道、添加发布说明并提交：

gpc publish app-release.aab --track internal
gpc publish app-release.aab --track beta --notes "Bug fixes and improvements"
gpc publish app-release.aab --track production --rollout 10

# Set in-app update priority (0-5) so clients can prompt updates (v0.9.70+)
gpc publish app-release.aab --track production --rollout 10 --in-app-update-priority 5

# Retain older version codes alongside the new upload (v0.9.70+)
gpc publish app-release.aab --track production --retain-version-codes 42,43

# Validate only — run the full pipeline (upload, track assignment, validate) but stop
# before committing. Useful for CI dry-validation against the real API. (v0.9.68+)
gpc publish app-release.aab --track beta --validate-only

从目录读取多语言发布说明：

gpc publish app-release.aab --track beta --notes-dir ./release-notes/
# Falls back to default.txt when a locale-specific file is missing (v0.9.70+)

B) 分步发布

如需更多控制，请使用单独的命令：

# Upload AAB (creates edit, uploads, assigns to track)
gpc releases upload app-release.aab --track internal

# Upload APK (auto-detected, uses correct endpoint)
gpc releases upload app-release.apk --track internal

# Upload with staged rollout
gpc releases upload app-release.aab --track production --rollout 10

# Upload as draft (not visible to users until explicitly released)
gpc releases upload app-release.aab --track production --status draft

# Validate only — upload and validate but do not commit (v0.9.68+)
gpc releases upload app-release.aab --track beta --validate-only

# Set release notes
gpc releases notes set --track beta --lang en-US --notes "Bug fixes"
gpc releases notes set --track beta --file release-notes/  # From directory

v0.9.47 新增： 系统会自动检测 APK 文件，并通过正确的 edits.apks.upload 端点上传。使用 --status draft 可创建草稿发布，以便在 Play Console 中上线前进行人工审核。

npm 发布（v0.9.77+）： GPC 软件包通过 Trusted Publisher（OIDC）和 Staged Publishing 发布。CI 会自动暂存软件包；维护者通过 2FA 批准后，软件包才会在 npm 上正式发布。不会使用长期有效的 NPM_TOKEN。CI/CD 工作流详情请参阅 gpc-ci-integration。

其他上传标志（v0.9.51+）

# Upload native debug symbols (ProGuard mapping or native code symbols)
gpc releases upload app.aab --track internal --mapping-type proguard  # default
gpc releases upload app.aab --track internal --mapping-type nativeCode

# Target a specific device tier configuration
gpc releases upload app.aab --track production --device-tier-config 12345
gpc releases upload app.aab --track production --device-tier-config LATEST

# Skip sending changes for review (required for rejected apps)
gpc releases upload app.aab --track production --changes-not-sent-for-review

# Fail safely if there are changes already in review
gpc releases upload app.aab --track production --error-if-in-review

标志	值	说明
--mapping-type	proguard（默认）、nativeCode	指定与应用包一同上传的调试符号类型。发布原生（C/C++）库时使用 nativeCode
--device-tier-config	数字 ID 或 LATEST	应用设备层级定向配置，以便向不同设备类别提供不同的 APK。使用 gpc device-tiers create --file tiers.json 创建配置；当选择器指定了 Play 尚未编入目录的设备（例如刚发布的机型）时，添加 --allow-unknown-devices（v0.9.96+），否则 Play 会拒绝该配置
--changes-not-sent-for-review	布尔标志	提交此次编辑，但不将更改送审。如果之前的提交遭到拒绝，且你尚未准备好重新送审，则必须使用此标志
--error-if-in-review	布尔标志	如果已有更改正在审核中，则使命令以非零代码退出，而不是静默覆盖这些更改
--validate-only	布尔标志	运行完整的上传和验证流程，但在 edits.commit 前停止。验证后会删除此次编辑。适用于 CI 合并前检查（v0.9.68+）
--in-app-update-priority	0-5	设置此版本的应用内更新优先级。0 = 默认（无紧迫性），5 = 最高紧迫性。使用 Play Core 应用内更新 API 的客户端可读取此值，以决定显示灵活更新提示还是立即更新提示（v0.9.70+）
--retain-version-codes	逗号分隔	以逗号分隔的版本代码列表，这些版本代码将与新上传的版本一同保留。防止新版本发布停用较旧的 APK/AAB（v0.9.70+）

Fastlane 风格的更新日志回退机制（v0.9.70+）

使用 --notes-dir 时，如果某个语言区域没有对应的专属文件，GPC 会回退使用更新日志目录中的 default.txt。这符合 Fastlane 的惯例，可避免未列出语言区域的版本说明为空。

被拒的应用

当 Google Play 拒绝某次提交时，你的应用会进入“更改审核中”状态。除非明确处理此状态，否则后续上传或推广都会失败：

1. 如果你想推送更改，但不触发新一轮审核（例如，在修复被拒原因时更新元数据），请使用 --changes-not-sent-for-review。此标志会提交此次编辑，但不更改审核状态。
2. 如果你想防止意外覆盖正在审核中的更改（例如，CI 流水线不应覆盖待审核的提交），请使用 --error-if-in-review。如果当前有更改正在审核中，命令将以代码 4（API 错误）退出。
3. 如果你已准备好重新提交审核，请省略这两个标志并正常上传。Google Play 会用新提交替换待审核的提交。

这些标志适用于 gpc releases upload、gpc publish、gpc releases promote、gpc releases rollout、gpc listings push/update/delete、gpc listings images upload/delete、gpc testers add/remove/import、gpc tracks create/update 和 gpc apps update。

注意（v0.9.52+）： 设置 --changes-not-sent-for-review 后，GPC 会跳过服务端编辑验证（edits.validate），直接执行 edits.commit。这是因为 Google 的验证端点不接受 changesNotSentForReview 参数，并会拒绝包含被拒更新的应用的编辑。提交调用本身仍会验证你的更改。 阅读：

• references/upload-lifecycle.md

2）检查版本状态

# Full picture — releases, vitals, and reviews in one command
gpc status

# Releases only, all tracks
gpc releases status

# Specific track detail
gpc releases status --track production

# JSON for scripting
gpc status --output json | jq '.releases[] | select(.track == "production")'

3）在轨道之间推广

# Promote from internal to beta
gpc releases promote --from internal --to beta

# Promote from beta to production with staged rollout
gpc releases promote --from beta --to production --rollout 5

# Copy release notes from another track when promoting
gpc releases promote --from internal --to production --copy-notes-from internal

# Promote as draft (review in Play Console before going live)
gpc releases promote --from internal --to beta --status draft

注意： 从 v0.9.39 起，gpc releases promote 遇到 409 EDIT_CONFLICT（另一个编辑已开启）时会自动重试一次。

推广也支持审核控制标志（v0.9.51+）：

# Promote without sending for review (rejected app workflow)
gpc releases promote --from internal --to beta --changes-not-sent-for-review

# Fail if changes are already in review
gpc releases promote --from beta --to production --rollout 5 --error-if-in-review

3b）发布前预览

# Read-only preview of release state across all tracks
gpc diff

# Compare two specific tracks
gpc diff --from internal --to production

# Compare local metadata vs remote
gpc diff --metadata fastlane/metadata

3c) 发布生命周期可见性

# List releases on a track with lifecycle states (DRAFT, IN_REVIEW, PUBLISHED, etc.)
gpc releases list --track production
gpc releases list --track beta --json

v0.9.46 新增： releases.list 端点无需打开编辑会话即可提供发布生命周期状态。可用它检查发布是否仍在审核中、已发布或处于草稿状态——适用于需要以审核完成作为门槛的 CI 流水线。

3d) 发布统计信息和历史记录

# Release count per track with status breakdown
gpc releases count

# Show release history from GitHub
gpc changelog
gpc changelog --tag v0.9.47

# Generate GitHub Release notes from local commits (v0.9.61+)
gpc changelog generate                              # markdown for the next release
gpc changelog generate --format prompt | pbcopy     # paste into Claude/ChatGPT
gpc changelog generate | gh release create vX -F -  # one-command release
gpc changelog generate --strict                     # fail CI on linter warnings (jargon, scope leaks)

::: tip 两种不同的发布说明流程

• Play Store recentChanges[]（按语言区域区分，最多 500 个字符）：gpc changelog generate --target play-store --locales auto --ai --apply（v0.9.64+，端到端流程），或 gpc publish --notes-from-git --since vX
• GitHub Release 说明（规范的 Markdown 模板、智能聚类、LLM 提示词模式）：gpc changelog generate（v0.9.61+） :::

Play Store 多语言发布说明（v0.9.62+）

要为各语言区域设置 Play Store“新内容”文本，请传入 --target play-store 和 --locales：

# Translate via your own LLM key (BYO, v0.9.63+)
gpc changelog generate --target play-store --locales auto --ai

# Explicit locales, no AI — placeholder text for non-source locales
gpc changelog generate --target play-store --locales en-US,fr-FR,de-DE

# Auto-detect from your live Play listing (one API round-trip)
gpc changelog generate --target play-store --locales auto --app com.example.app

# Preview the prompt without spending tokens
gpc --dry-run changelog generate --target play-store --locales auto --ai

主要行为：

• en-US 源文本与 github 目标使用相同的项目符号列表；若超过 500 个 Unicode 码点，则截断至 500 个
• 使用 --ai 时（v0.9.63+）：非源语言区域会通过用户自己的 LLM 密钥进行翻译。按优先级自动检测环境变量：AI_GATEWAY_API_KEY → ANTHROPIC_API_KEY → OPENAI_API_KEY → GOOGLE_GENERATIVE_AI_API_KEY。非推理模型的默认值为（claude-sonnet-4-6、gpt-4o-mini、gemini-2.5-flash）。可通过 --provider / --model 覆盖。
• 不使用 --ai 时：非源语言区域会填入 [needs translation] 占位文本。使用 --format prompt 可生成适用于离线或无密钥工作流、可直接用于翻译的 LLM 提示词。
• 如果任何语言区域超过 500 个字符，或（使用 --ai 时）任何语言区域翻译失败，--strict 将以状态码 1 退出
• 延迟加载：不使用 --ai 运行时，不会导入任何 AI SDK 依赖项。保留冷启动预算。
• AI SDK v6（v0.9.82+）：底层 @ai-sdk/* 软件包已从 5.x 升级至 6.0。公开的 --ai 接口和所有模型提供方选项均未改变。用户无需执行迁移步骤。

将翻译后的说明写入草稿发布（v0.9.64+）

生成发布说明后（无论是否使用 --ai），可将其直接写入 Play Store 轨道上的最新草稿：

# Full pipeline: generate + translate + apply
gpc changelog generate --target play-store --locales auto --ai --apply

# Apply to a specific track (default: production)
gpc changelog generate --target play-store --locales auto --ai --apply --track beta

# Preview what would be written (no API call)
gpc changelog generate --target play-store --locales auto --ai --apply --dry-run

主要行为：

• --apply 要求使用 --target play-store（与 --format prompt 不兼容）
• 写入轨道上的最新草稿发布。如果不存在草稿，则以 RELEASE_NO_DRAFT 退出（状态码 1），并提示先创建草稿
• 使用 withRetryOnConflict 处理 409 编辑冲突
• --dry-run 会显示将要写入的说明，而不会调用 API

软件包上传竞态修复（v0.9.64+，v0.9.77 扩展）： 上传大型 AAB（65MB+）后，GPC 会采用斐波那契退避（2s、3s、5s、8s、13s、21s、34s——总计约 86s）轮询 bundles.list，然后再调用 edits.validate。这修复了间歇性出现的 INVALID_ARGUMENT: Some of the Android App Bundle uploads are not completed yet 错误，该错误影响所有 AAB 上传路径。GPC 是已知唯一能处理此类服务端处理延迟的 CLI；Google 的 API 文档未说明这一异步行为。

validate/commit 多次重试保护（v0.9.77）： 软件包处理完成后，edits.validate 和 edits.commit 各会重试最多 3 次，并逐步延长超时时间（15s、30s、45s）。这可处理短暂的服务端延迟：软件包已处理完成，但编辑暂时还无法提交。

完整演练请参阅 apps/docs/guide/multilingual-release-notes.md，其中包括 Vercel AI Gateway 路径（并报告每次运行的美元成本）。

4) 管理分阶段发布

# Increase rollout percentage
gpc releases rollout increase --track production --to 50

# Halt rollout (stops further distribution)
gpc releases rollout halt --track production

# Resume halted rollout
gpc releases rollout resume --track production

# Complete rollout (100%)
gpc releases rollout complete --track production

发布命令也支持审核控制标志（v0.9.51+）：

# Increase rollout without triggering review (rejected app workflow)
gpc releases rollout increase --track production --to 50 --changes-not-sent-for-review

# Complete rollout, but fail if there are changes in review
gpc releases rollout complete --track production --error-if-in-review

阅读：

• references/rollout-strategies.md

5) 轨道管理

gpc tracks list                    # List all tracks
gpc tracks get production          # Show track details + current releases

v0.9.87 新增： tracks list --json 现在会返回统一信封 { tracks, nextPageToken, meta.count }，与其他列表命令保持一致。表格输出未改变；仅 --json 的结构发生了变化。

将现有版本代码分配到其他轨道（v0.9.78+）

如果 AAB 已上传，你可以将其版本代码分配到其他轨道，而无需重新上传：

gpc releases assign 42 --track beta
gpc releases assign 42 --track production --rollout 10

当你想将版本代码从一个测试轨道移到另一个测试轨道，或 CI 构建已上传到内部测试轨道、而你想将其分配到 alpha 轨道以面向更多用户时，这会很有用。

创建自定义封闭式测试轨道（v0.9.79+）

除了内置的 internal、alpha、beta 和 production 轨道外，Google Play 还支持自定义封闭式测试轨道：

gpc tracks create --track-id my-custom-track --name "Partner Testing"

底层使用 edits.tracks.create。创建后，可在任何 --track 标志中使用自定义轨道 ID。

6）使用 dry-run 预览

所有写入操作都支持 --dry-run：

gpc releases upload app.aab --track beta --dry-run
gpc releases promote --from beta --to production --rollout 10 --dry-run
gpc releases rollout increase --track production --to 50 --dry-run

同时使用 --json 和 --dry-run 时，输出会包含 executed[] 和 skipped[] 数组，供 CI 流水线检查哪些步骤将会运行（v0.9.79+）：

{
  "dryRun": true,
  "executed": [],
  "skipped": ["upload", "validate", "commit"]
}

7）交互模式

如果未提供标志，GPC 会在检测到 TTY 时以交互方式提示：

gpc releases upload app.aab
# Prompts for: track, rollout percentage, release notes

使用 --no-interactive 或 GPC_NO_INTERACTIVE=1 禁用。

验证

• gpc status 会显示预期轨道上的版本，并显示正确的状态和分阶段发布情况
• gpc releases status 会确认版本代码与已上传的 AAB 相符
• 分阶段发布百分比正确
• 已设置预期语言的版本说明
• 发布后，gpc vitals crashes --dim versionCode 显示没有峰值（也可使用 gpc status 检查所有指标的运行状况）

故障模式 / 调试

症状	可能原因	修复方法
Version code already used	此轨道上已存在相同的版本代码	在构建中递增 versionCode
APK_NOT_SIGNED	缺少签名或签名无效	使用 Play App Signing 或检查密钥库
EDIT_CONFLICT	另一个编辑正在进行	等待后重试，或使用 Console UI 丢弃待处理的编辑
分阶段发布卡住	分阶段发布已暂停	gpc releases rollout resume --track <track>
轨道错误	已提升到错误的轨道	在正确的轨道上创建新版本
API_DECLARATION_REQUIRED	Play Console 的应用内容声明未完成（v0.9.94+）	在 Policy > App content 下完成声明。请阅读提示：GPC 会引用 Google 的消息，其中会指出具体需要完成的声明。这不是权限问题
API_INSUFFICIENT_PERMISSIONS，但你确信服务账号配置正确	在 v0.9.94 之前的 GPC 中，这通常是应用内容声明问题，但错误报告有误	升级，或在更改任何角色前检查 Policy > App content

提交被拒：reviewPending 和 nextStep（v0.9.79+）

当 Google Play 因变更必须经过审核而拒绝 edits.commit 调用时，GPC 会返回结构化结果，而不是普通错误：

{
  "reviewPending": true,
  "nextStep": "Your changes are under Google review. Check Play Console for status or use --changes-not-sent-for-review to bypass review for non-reviewed tracks."
}

reviewPending 字段始终为布尔值。nextStep 字符串提供人类可读的指引。CI 流水线可以根据 reviewPending === true 采取相应操作，例如轮询、发送通知或退出。

内部测试轨道无需审核（v0.9.79+）

内部测试轨道无需 Google 审核。提交到 internal 轨道时，GPC 会在结构化输出中设置 reviewSkipped: true，表示提交已立即完成，未进入审核队列。

阅读：

• references/troubleshooting.md
• references/pre-release-pipeline.md — 端到端流程：验证 → 上传 → 运行状况门禁 → 提升 → 分阶段发布

8）实时开发者通知（RTDN）

实时监控订阅和购买事件：

gpc rtdn status              # Check Pub/Sub topic configuration
gpc rtdn decode <payload>    # Decode base64 notification payload
gpc rtdn test                # Guidance for testing RTDN setup

之前已知的问题（已在 v0.9.78 中修复）

以下所有问题均已在 v0.9.78 中解决。此处列出仅供了解历史情况。

Bug	状态
tracks update 会悄无声息地清除轨道	已修复：versionCode 强制转换 + 支持嵌套 JSON
--changes-not-sent-for-review 标志无法传递到 API	已修复：validateAndCommit 在验证时自动补救（15 个以上命令）
无法将已上传的 versionCode 分配到新轨道，除非重新上传	已修复：gpc releases assign <versionCode> --track <track>

相关技能

• gpc-setup：身份验证和配置
• gpc-metadata-sync：商店详情和截图
• gpc-vitals-monitoring：发布后的崩溃监控
• gpc-ci-integration：在 CI/CD 中自动发布
• gpc-monetization：订阅、IAP、RTDN 通知
• gpc-enterprise：通过 Play Custom App Publishing API 向 Managed Google Play 发布私有应用（v0.9.56+）