capgo-release-management

Capgo 发布管理

通过命令行发布、提升、回滚和清理 Capgo OTA 包。

以下信息已根据 @capgo/cli 8.77（2026 年 10 月）核实。每条命令都接受 -a, --apikey。在 Capacitor 项目中，可以省略 appId。

适用场景

在以下情况触发：

• 用户上传、列出、删除或清理包，或询问某个渠道提供哪个版本。
• 用户创建或配置渠道、将预发布环境提升到生产环境、启动、暂停或回滚渐进式发布，或回滚有问题的发布。
• 用户询问某项更改是否适用于 OTA（bundle compatibility、bundle releaseType）。
• 用户设置包加密（key create、key save、--key-v2）。

以下情况不要使用：

• 工作涉及应用端的更新程序代码或配置（notifyAppReady、autoUpdate、setChannel）。请使用 capgo-live-updates。
• 需要原生二进制文件。请使用 capgo-native-builds。
• 用户管理组织、成员、2FA 或 API 密钥策略。请使用 capgo-organization-management。
• 用户需要端到端发布流水线设计。请使用 capgo-release-workflows。

命令索引

目标	命令
上传并关联	bundle upload [appId] --path ./dist --channel production（多个渠道用逗号分隔）
是否适用于 OTA？	bundle releaseType [appId] --channel production 输出 OTA 或 native
查看详细原生差异	bundle compatibility [appId] --channel production [--text]
查看当前发布内容	channel currentBundle production [appId] --quiet
提升	channel promote staging production [appId]
回滚	channel set production [appId] --bundle <previous-version>
渐进式发布	bundle upload ... --rollout 10，然后使用 channel set ... --rollout-percentage 50 / --rollout-promote / --rollout-rollback
创建渠道	channel add beta [appId] [--default] [--self-assign]
渠道策略	channel set <ch> --disable-auto-update major|minor|patch|metadata|none，并搭配 --ios/--android/--dev/--prod/--emulator/--device 开关
列出	bundle list [appId]、channel list [appId]
清理	bundle cleanup [appId] --bundle 1.0 --keep 3
删除	bundle delete <version> [appId]、channel delete <ch> [appId]
预览二维码	先运行一次 app set [appId] --preview，然后运行 get-qr [appId] --channel beta 或 bundle upload ... --qr-preview
加密密钥	key create、key save --key ./.capgo_key_v2.pub、key delete_old
自定义 zip / 外部资源	bundle zip [appId] --json、bundle encrypt <zip> <checksum>、bundle upload --external <url>

以上命令的格式均为 npx @capgo/cli@latest <command>。以下命令不存在（它们来自旧文档或其他工具）：channel create、bundle revert、upload --sign、key verify，以及不带 bundle 的顶层 capgo upload。

操作步骤

1. 先检查

npx @capgo/cli@latest channel list com.example.app
npx @capgo/cli@latest channel currentBundle production com.example.app --quiet
npx @capgo/cli@latest bundle releaseType com.example.app --channel production

在进行任何更改前，报告当前发布版本以及 OTA / native 判定。如果判定为 native，请停止操作，并转交给 capgo-native-builds（或用户的原生流水线）。

2. 上传

npm run build
npx @capgo/cli@latest bundle upload com.example.app --path ./dist --channel staging --comment "$(git rev-parse --short HEAD)"

• 除非传入 --bundle <semver>，否则版本号取自 package.json。版本号必须唯一、大于 0.0.0，且不能是此前已删除的版本。
• 对即时应用的应用使用 --delta。如果文件超过 10,000 个，CLI 会拒绝增量上传。此时请使用 --no-delta。
• 在 CI 中使用 --fail-on-incompatible。仅当 JS 代码会处理缺失插件时，才使用 --accept-incompatible。这两个标志不能与 --ignore-metadata-check 同时使用。

3. 推广和发布

• 推广：npx @capgo/cli@latest channel promote staging production com.example.app。它会运行与 channel set --bundle 相同的兼容性检查。
• 渐进式发布：使用 --rollout <pct> 上传，然后查看统计数据，再运行 --rollout-promote。
• 只有在用户明确要求切换生产流量时，才更改哪个频道是默认频道（channel set <ch> --state default，或 channel add --default）。

4. 回滚

npx @capgo/cli@latest bundle list com.example.app
npx @capgo/cli@latest channel set production com.example.app --bundle 1.4.2
# or, during a rollout:
npx @capgo/cli@latest channel set production com.example.app --rollout-rollback

设备会在下次检查更新时获取更改。

5. 加密（可选，适用于敏感应用）

npx @capgo/cli@latest key create        # writes .capgo_key_v2 (private) + .capgo_key_v2.pub, saves the public key to config
npx cap sync                             # the public key must ship in the native app
npx @capgo/cli@latest bundle upload com.example.app --key-v2 ./.capgo_key_v2 --channel production

在 CI 中，将私钥保存在 CI 密钥存储中，在作业中将其写入 ./.capgo_key_v2，并传入相同的 --key-v2 ./.capgo_key_v2。私钥不会离开运行器。将 .capgo_key_v2 添加到 .gitignore，且绝不要提交该文件。更换密钥需要新的原生构建：使用旧 publicKey 的设备会出现 key_id_mismatch。

注意事项

• 对于已配置发布比例的频道，直接运行 bundle upload --channel production 会设置发布目标，而稳定版本不会改变。请使用 channel set --bundle 显式替换稳定版本。
• bundle cleanup --ignore-channel 也会删除关联频道。未经询问，绝不要添加此参数。
• bundle delete 是永久操作，已删除的版本无法重复使用。回滚时，优先将较旧的 Bundle 重新关联。
• releaseType 只能读取原生软件包元数据，无法检测原始 ios/ 或 android/ 文件的更改。
• 上传时使用 --self-assign 会更改频道设置，而不只是更改此 Bundle 的设置。

验证

1. npx @capgo/cli@latest channel currentBundle production com.example.app --quiet 会输出预期版本。
2. npx @capgo/cli@latest probe --platform ios（在项目中运行）会报告是否会提供更新。
3. npx @capgo/cli@latest app debug com.example.app 会显示测试设备正在下载并设置 Bundle。
4. 对于加密上传，使用新原生构建的设备会应用更新，且不会出现 key_id_mismatch 错误。

错误处理

字符串	修复方法
❌ Version X already exists	升级 --bundle，使用 --auto-bump patch，或在 CI 重新运行时传入 --version-exists-ok
Cannot upload the same bundle content	该校验和已存在于此频道。重新构建并进行更改，或传入 --ignore-checksum-check
Bundle NOT compatible with <channel> channel	原生软件包不一致。先进行原生构建，或者在代码中有相应保护时使用 --accept-incompatible
notifyAppReady() is missing in the build folder (...)	修复应用入口点（参见 capgo-live-updates）
index.html is missing in the root folder of <dir>	--path 错误
Cannot find channel <name>	检查 channel list。名称区分大小写
Channel strategy <x> is not known	使用 major、minor、patch、metadata 或 none
No Capgo API key found. Run ... first, then retry this command.	运行 npx @capgo/cli@latest login、设置 CAPGO_TOKEN，或传入 -a
Insufficient permissions for <key>	API 密钥在此应用中的角色权限过低。请向管理员申请具有上传权限的密钥
Cannot upload bundle ( try again with --tus option)	使用 --tus 重试，并为较大的 Bundle 增加 --timeout

资源

• Bundle 参考：https://capgo.app/docs/cli/reference/bundle/
• 频道参考：https://capgo.app/docs/cli/reference/channel/
• 渐进式发布：https://capgo.app/docs/live-updates/progressive-rollouts/
• 加密：https://capgo.app/docs/live-updates/encryption/
• 兼容性：https://capgo.app/docs/live-updates/compatibility/