Capgo 环境最佳实践：用一个 Mobile App ID 做 Staging

团队通常会针对移动端环境选择以下三种方案之一：

两个 App ID（生产环境 + 预发布环境）
一个 App ID + 动态运行时环境切换
一个 App ID + Capgo channels

前两种方案可行，但会带来长期摩擦。在实际团队中，使用 Capgo channel 模型通常是最简洁的。

为什么重复的 App ID 会带来干扰

使用 com.myapp 和 com.myapp.beta 看似简单，但很快就会出现重复问题：

两套发布 pipeline
两套 push ID、deep links 和权限映射
两套 analytics 和崩溃日志标识
环境间的配置差异与行为不一致

最终你需要在应用商店控制台、团队协作和内部 QA 指令中管理两个产品。

为什么运行时切换配置通常很混乱

“单一 App ID + 运行时切换”模式通常意味着你的 App 在启动时读取环境变量或 flag，并动态重定向 API、密钥和 update 行为。

这种情况通常会导致：

由于配置状态过时，QA 开始绕过预定流程；
有人在生产环境中使用了错误的 endpoint；
环境差异导致难以复现的 bug；
你需要在用户设备上调试“这个二进制文件到底在使用哪个配置版本？”

随着每次发布，这种复杂性会不断增加，并导致团队开发效率下降。

使用 Capgo 的方式：一个 App ID，多个 Channel

Capgo 通过 Channel 实现显式的环境控制：

在 App Store / Play 中仅保留一个生产环境 App ID。
仅发布一个用于“壳”的 Native Build（除非原生代码变更需要重新构建）。
通过 Channel 来路由行为，而不是通过重复的 App 身份。

在实践中，这意味着：

production: 所有用户
staging: 内部 QA 与发布候选版本
beta: 受邀测试人员
hotfix: 紧急补丁通道

您的 TestFlight/Play 内部测试应用可以保持在 staging 当前版本。您可以通过 Capgo 在该版本中反复进行 JS/CSS/资源更新，而无需重新发布新的 Native Build。

实践中的推荐结构

1) Native 发布基线

您的最后一个 Native 二进制文件可以在多次 JS 迭代中保持不变：

bun run build
bunx cap sync
# generate Xcode/Android Studio archives as usual

只有在实际更改了 Native 层代码时，才需要重新构建 Native 二进制文件。

2) 为不同环境使用专用 Channel

通过 Channel 发布更新：

bun run build
bunx @capgo/cli deploy --channel staging

在 QA 环境测试，修复问题，然后进行发布：

bunx @capgo/cli promote vX.Y.Z --channel production

如果你更倾向于显式版本管理：

bunx @capgo/cli deploy vX.Y.Z --channel staging
bunx @capgo/cli promote vX.Y.Z --channel production

3) 让 TestFlight 始终保持“预发布”状态

在 iOS 工作流中，这意味着你的 TestFlight 构建版本可以始终关联预发布更新：

无需为每次 JS 变更频繁提交 Native Build。
QA 始终通过 staging channel 验证接近生产环境的 code。
生产环境用户仅接收从 production channel 发布的 bundle。

4) 仅在受控工作流中使用 channel 切换

对于进阶团队，可以为 QA/管理员用户提供受控的 channel 切换功能：

import { CapacitorUpdater } from '@capgo/capacitor-updater';

await CapacitorUpdater.setChannel({
  channel: 'staging',
  triggerAutoUpdate: true
});

这是可选的。大多数团队通过 dashboard 进行 channel 分配，仅为内部用户切换 channel，而非所有客户。

运维检查清单

仅使用一个 App ID（不要重复使用 production/staging ID）
单一的基础 Native Build 流水线
已记录的 Channel 映射 (staging, beta, production, hotfix)
CI/CD 中强制执行的发布路径
仅在原生代码变更时进行 Native rebuild
定期测试回滚机制

实际收益

这种方法消除了环境差异，减少了构建损耗，并加快了修复速度：

QA 可以获得真实的二进制文件（而非虚假的“测试版 App”身份），
你的 TestFlight 发布路径保持稳定，
你的团队避免了“双 App ID 债务”，
你可以通过 Capgo 快速推送大量仅限 JS 的修复。

最终结果是更简单的治理：更少的构建产物、更清晰的遥测数据，以及更少的发布运维意外。

延续 Capgo：环境最佳实践——使用单一 Mobile App ID 构建 Staging 环境

如果你正在使用 Capgo 环境最佳实践：用一个 Mobile App ID 做 Staging 要规划 channel 路由和分阶段发布，请将其与渠道实现细节见 Channels，渠道实现细节见 Channels，渠道实现细节见 Channels， Beta 测试解决方案用于 Beta 测试方案中的产品工作流，以及版本定向方案用于版本定向方案中的产品工作流。