gplay-release-flow

发布流程（Internal、Beta、Production）

需要将新构建版本发布到 Google Play Store 时，使用此技能。

前提条件

• 确保凭据已设置（gplay auth login 或 GPLAY_SERVICE_ACCOUNT 环境变量）。
• 构建产物必须为 AAB（App Bundle）或 APK。
• 版本代码必须高于之前发布的版本。
• 服务账号需要在 Play Console 中拥有“Release Manager”权限。

Android 发布

首选端到端命令

Internal 轨道（用于内部测试）：

gplay release \
  --package com.example.app \
  --track internal \
  --bundle app-release.aab

Beta 轨道（用于 Beta 测试人员）：

gplay release \
  --package com.example.app \
  --track beta \
  --bundle app-release.aab \
  --release-notes @release-notes.json

Production 并分阶段推出（逐步发布）：

gplay release \
  --package com.example.app \
  --track production \
  --bundle app-release.aab \
  --release-notes @release-notes.json \
  --rollout 0.1

试运行（预览发布，不实际执行）：

gplay release \
  --package com.example.app \
  --track production \
  --bundle app-release.aab \
  --dry-run

发布并附带元数据（商店详情和截图）

从目录中包含商店详情：

gplay release \
  --package com.example.app \
  --track production \
  --bundle app-release.aab \
  --listings-dir ./metadata \
  --screenshots-dir ./metadata

跳过元数据或截图：

# Upload bundle only, skip metadata sync
gplay release \
  --package com.example.app \
  --track production \
  --bundle app-release.aab \
  --skip-metadata

# Upload bundle and metadata, skip screenshots
gplay release \
  --package com.example.app \
  --track production \
  --bundle app-release.aab \
  --listings-dir ./metadata \
  --skip-screenshots

同时指定商店详情和截图目录：

gplay release \
  --package com.example.app \
  --track beta \
  --bundle app-release.aab \
  --listings-dir ./metadata/listings \
  --screenshots-dir ./metadata/images \
  --release-notes @release-notes.json

手动执行步骤（需要更多控制时）

1. 创建编辑会话：

   EDIT_ID=$(gplay edits create --package com.example.app | jq -r '.id')
   

2. 上传包：

   gplay bundles upload \
     --package com.example.app \
     --edit $EDIT_ID \
     --file app-release.aab
   

3. 更新轨道：

   gplay tracks update \
     --package com.example.app \
     --edit $EDIT_ID \
     --track production \
     --releases @releases.json
   

   --releases 接受一个包含轨道发布版本的 JSON 数组（或 @file）。

4. 验证编辑内容：

   gplay edits validate --package com.example.app --edit $EDIT_ID
   

5. 提交编辑（发布更改）：

   gplay edits commit --package com.example.app --edit $EDIT_ID
   

轨道晋级

将某个轨道上的发布版本晋级到另一个轨道：

# Promote from internal to beta
gplay promote \
  --package com.example.app \
  --from internal \
  --to beta

# Promote from beta to production with 25% rollout
gplay promote \
  --package com.example.app \
  --from beta \
  --to production \
  --rollout 0.25

分阶段推出管理

从 10% 的推出比例开始（比例 0.1）：

gplay release \
  --package com.example.app \
  --track production \
  --bundle app.aab \
  --rollout 0.1

提高到 50%（比例 0.5）：

gplay rollout update \
  --package com.example.app \
  --track production \
  --rollout 0.5

停止推出（暂停分发）：

gplay rollout halt --package com.example.app --track production

恢复推出：

gplay rollout resume --package com.example.app --track production

完成推出（向 100% 的用户发布）：

gplay rollout complete --package com.example.app --track production

发布说明格式

单个 --release-notes 标志接受三种格式：JSON 数组（多语言地区）、纯文本（自动分配给 en-US），或指向上述任一格式的 @file 路径。无需单独指定地区的标志。

JSON 数组格式（多语言地区）

release-notes.json — 包含 {language, text} 条目的 JSON 数组：

[
  { "language": "en-US", "text": "Bug fixes and performance improvements" },
  { "language": "es-ES", "text": "Correcciones de errores y mejoras de rendimiento" },
  { "language": "fr-FR", "text": "Corrections de bugs et améliorations des performances" }
]

使用 --release-notes @release-notes.json 传入。

纯文本格式（单一地区）

以纯文本形式提供发布说明 — 系统会自动将其分配给 en-US：

gplay release \
  --package com.example.app \
  --track beta \
  --bundle app.aab \
  --release-notes "Bug fixes and performance improvements"

也可以使用 @ 从文件中读取（纯文本或 JSON 数组）：

gplay release \
  --package com.example.app \
  --track beta \
  --bundle app.aab \
  --release-notes @release-notes.txt

发布标志参考

标志	说明
--package	应用包名称（必填）
--track	目标轨道（production、beta、alpha、internal；默认值：internal）
--bundle	AAB 文件路径（使用 --bundle 或 --apk，不可同时使用）
--apk	APK 文件路径（--bundle 的替代选项）
--release-notes	发布说明：纯文本（自动分配给 en-US）、包含 {language, text} 的 JSON 数组，或 @file
--rollout	分阶段推出比例（0.0-1.0；默认值：1.0，即全部推出）
--listings-dir	包含要同步的商店详情的目录
--screenshots-dir	包含要上传的截图的目录
--skip-metadata	发布期间跳过元数据/商店详情同步
--skip-screenshots	发布期间跳过截图上传
--dry-run	预览发布，不实际执行
--output	输出格式（json、table、markdown）

发布前检查清单

发布前，请确认：

• 版本代码已递增
• AAB/APK 已使用正确的密钥库签名
• ProGuard/R8 映射文件已上传（用于崩溃报告）
• 已为所有语言地区编写发布说明
• 已在 internal/beta 轨道完成测试
• 服务账号拥有正确权限
• 试运行通过：gplay release ... --dry-run

常见发布策略

策略 1：Internal -> Beta -> Production

# Week 1: Internal
gplay release --package com.example.app --track internal --bundle app.aab

# Week 2: Beta (after testing)
gplay promote --package com.example.app --from internal --to beta

# Week 3: Production with staged rollout
gplay promote --package com.example.app --from beta --to production --rollout 0.1
gplay rollout update --package com.example.app --track production --rollout 0.5  # Day 2
gplay rollout complete --package com.example.app --track production             # Day 7

策略 2：直接发布到 Production 并分阶段推出

# Day 1: 10%
gplay release --package com.example.app --track production --bundle app.aab --rollout 0.1

# Day 2: 25%
gplay rollout update --package com.example.app --track production --rollout 0.25

# Day 3: 50%
gplay rollout update --package com.example.app --track production --rollout 0.5

# Day 7: 100%
gplay rollout complete --package com.example.app --track production

策略 3：完整发布元数据并通过试运行验证

# 1. Dry run to verify everything
gplay release \
  --package com.example.app \
  --track production \
  --bundle app.aab \
  --listings-dir ./metadata \
  --screenshots-dir ./metadata \
  --release-notes @release-notes.json \
  --rollout 0.1 \
  --dry-run

# 2. Execute the release
gplay release \
  --package com.example.app \
  --track production \
  --bundle app.aab \
  --listings-dir ./metadata \
  --screenshots-dir ./metadata \
  --release-notes @release-notes.json \
  --rollout 0.1

备注

• 始终使用 --help 确认确切命令支持的标志。
• 使用 --output table 获取便于阅读的输出；默认格式为 JSON。
• 对于 CI/CD，请使用 GPLAY_SERVICE_ACCOUNT 环境变量。
• 每次发布后都要上传反混淆文件，以便对崩溃报告进行符号化处理。
• 在 CI 中使用 --dry-run，在实际部署前验证发布内容。