Native + OTA Channel 工作流

常见的 Capgo 配置使用 开发 通道和 生产环境 通道。CI 会将每个 OTA bundle 上传至 dev，然后在您准备好时将其晋升至 production 。团队通常会添加 --fail-on-incompatible 以防止 CI 意外发布需要新 Native Build code 的 live update。

本页将回答以下后续问题： 当你需要 刻意 使用与当前 channel 原生包不兼容的 bundle 时，该怎么办？

如果你想了解 Capgo 为什么要对比原生包，请先阅读 原生兼容性。关于如何通过完整的 CI 分支自动选择 OTA 或 Capgo Build，请参阅 自动 OTA 或原生.

推荐的 channel 布局

本指南假设 dev 以及 production channel 已存在。如果需要，请先创建它们：

npx @capgo/cli@latest channel add production com.example.app
npx @capgo/cli@latest channel add dev com.example.app

渠道	受众群体	常规上传
dev	内部 / QA 版本	每次 JS 推送 (及有意的 Native 基线更新)
production	应用商店用户	仅在发布就绪时进行推广或上传

--fail-on-incompatible 是两个渠道的理想默认设置，适用于 日常 OTA 上传。它会将你正在上传的 bundle 中的 native 包与该 bundle 进行对比 当前在该 channel 上生效。如果两者不一致，upload 会以非零状态退出，且不会发布任何内容。

日常 OTA（保留该 flag）

当改动仅涉及 JavaScript，且 native packages 与 channel 匹配时：

npx @capgo/cli@latest bundle upload com.example.app \
  --channel production \
  --fail-on-incompatible \
  --auto-min-update-version

--fail-on-incompatible 阻止意外的 native drift。 --auto-min-update-version 每次 upload 都需要，一旦 channel 使用 metadata 策略（见下文推荐）。如果 channel 尚未启用 metadata ，你可以省略 --auto-min-update-version 直到切换。

上传前的可选 CI 门禁：

npx @capgo/cli@latest bundle releaseType com.example.app --channel production
# → OTA      safe to upload with --fail-on-incompatible
# → native   stop; ship a native binary first (see below)

有意进行的 Native 升级（仅需取消一次标记）

您 无法 在保持现有状态的同时，上传需要新 Native code 的 bundle --fail-on-incompatible。该标记的存在正是为了拦截这种情况。当插件、Capacitor 版本或其他 Native 依赖项发生有意变更时：

1. 发布匹配的 Native 二进制文件 (App Store / Play Store，或 Capgo 构建).
2. 上传匹配的 JS bundle 无需 --fail-on-incompatible.
3. 优先使用 --auto-min-update-version 并将 channel 设为 metadata strategy，这样仍在使用旧版 binary 的设备在安装新 App 前不会收到新 bundle。
4. 完成该基线上传后，将 --fail-on-incompatible 恢复正常的 OTA CI（并保持 --auto-min-update-version 同时 channel 保持在 metadata).

1. 每个 channel 仅限一次：启用 metadata gating

   npx @capgo/cli@latest channel set production com.example.app --disable-auto-update metadata

   重复以下步骤 dev 如果该 channel 也会接收主动的 Native Build 基线。切换后，每次上传到该 channel 的内容都必须包含 --auto-min-update-version 或 --min-update-version.

2. 发布 Native 二进制文件

   构建并提交包含新 plugin 或 Native 变更的 iOS/Android 应用。在用户安装该二进制文件之前，他们无法安全地运行依赖这些 Native 包的 bundle。

3. 上传匹配的 OTA 基线（不 --fail-on-incompatible)

   npx @capgo/cli@latest bundle upload com.example.app \
     --channel production \
     --auto-min-update-version

   这会记录该 channel 上新的 Native 包。随后 bundle releaseType / --fail-on-incompatible 会使用该基线进行检查。

4. 恢复受保护的 OTA 上传

   后续仅限 JS 的发布将再次使用这两个标志：

   npx @capgo/cli@latest bundle upload com.example.app \
     --channel production \
     --fail-on-incompatible \
     --auto-min-update-version

提示

请将 native-baseline 上传视为一个 专用的 CI 任务 (或手动发布步骤)，而不是在默认 OTA 任务中随机添加的例外。默认任务应始终保持 --fail-on-incompatible，并且在 metadata 频道上它也应保持 --auto-min-update-version.

常见问题

我可以保留 --fail-on-incompatible 却仍然推送了与原生不兼容的 bundle？

不行。如果上传的 native packages 与该 channel 的 live bundle 不同，该标志会故意使命令失败。如果需要有意进行 native 升级，请在单次 upload 时省略该标志（并在 --auto-min-update-version 可以的情况下使用）。

不带标志进行一次性 upload 是正确的做法吗？

是的。在发布新 binary 后，这是推进 channel 的 native baseline 的官方支持方式。在其他所有 OTA upload 中请务必保留该标志，以确保意外的 native drift 仍能触发 CI 失败。

我是先 upload 到 dev 然后再 production?

是的，如果这符合你的流程。运行相同的规则 针对每个 channel: 兼容性检查是针对目标 channel 上当前运行的版本。请通过 Promote 或重新 upload 至 production 仅在...之后 dev 看起来没问题，并使用 native-baseline upload（不 --fail-on-incompatible) 到每个需要记录新 native packages 的 channel 上。

如果我开启着 flag 的情况下 upload 新的 native bundle 会怎样？

CI 会失败，且 Capgo 不会发布该 upload。这是预期结果。要么是操作失误（修复 native packages 并尝试以 OTA 方式重试），要么是刻意为之（请使用上述 native 路径）。

哪个 flag 对应哪个 job？

路径	当	上传标记
OTA	仅限 JS；原生包需与 channel 匹配	--fail-on-incompatible + --auto-min-update-version (若 channel 处于以下状态则必填) metadata)
Native 基线	新的 Native binary + 匹配的 JS bundle	否 --fail-on-incompatible; 保留 --auto-min-update-version

相关

原生兼容性

Capgo 如何检测原生包漂移，以及“不兼容”对设备意味着什么。

自动 OTA 或原生

接入 bundle releaseType GitHub Actions 或 GitLab，让 CI 自动选择正确路径。

版本定向

Channels、semver 规则以及用于分发层级的元数据策略。

CLI: bundle

关于 upload、compatibility、releaseType 及相关 flag 的参考。

继续阅读 Native + OTA Channel Workflow

如果你正在使用 Native + OTA Channel 工作流 以确保 Live Update 在 Native release 期间的安全，将其与 原生兼容性 用于包比较规则， 自动 OTA 或原生 用于 CI 分支， 版本定向 用于元数据下限，以及 Capgo CLI bundle 引用 用于上传标志。