原生兼容性

Capgo live update 会替换您应用的 JavaScript bundle ，但无法更改 原生 应用的一部分——Capacitor/Cordova 插件、原生依赖项以及编译到已安装二进制文件中的原生项目配置。当新 bundle 需要已安装二进制文件中没有的原生 code 时，该 bundle 将 与原生不兼容: Capgo 仍可推送该更新，但在仍运行旧版 Native Build 的设备上可能会崩溃或运行异常。

本页说明 Capgo 如何检测原生兼容性、不兼容更新对用户意味着什么，以及如何安全地发布原生变更。

注意

Live Updates 仅限于 JavaScript bundle 变更。如果你需要更新原生 code——添加或删除插件、升级 Capacitor，或更改原生项目配置——就需要通过常规的应用商店分发流程提交新的二进制构建。

TLDR：OTA 还是 Native Build？

Capgo 可以从你生成的 web build 文件夹发送文件。如果变更只影响 HTML、CSS、JavaScript、资源文件，或打包进该输出的纯 JavaScript 包，就把它作为 live update 发布。

当变更会更新以下内容时，请使用原生应用发布： capacitor.config.ts插件配置（存储在 Capacitor 配置中）、原生插件或依赖项、Capacitor 本身，或 iOS/Android 项目文件。一个实用的判断方法：如果变更必须通过以下方式更新原生项目 npx cap sync 或 npx cap copy 在已安装设备上可用之前，请将其视为原生代码。

变更	使用 Capgo OTA 发布？	原因
HTML、CSS、应用 JavaScript、图片、字体及其他 Web 构建资源	是	它们在运行时从 Web bundle 加载。
打包到 Web 输出中的纯 JavaScript 包变更	是	生成的 JavaScript 是 Web bundle 的一部分。
capacitor.config.ts 变更	否	在构建时，Capacitor 配置会被读取到原生应用中。
添加、移除或升级 Capacitor/Cordova 插件	否	已安装的原生二进制文件必须包含匹配的原生 code。
iOS 或 Android 项目文件变更	否	现有用户需要从应用商店获取新的二进制文件。

各技术栈的客户端插件

Capgo 为每种混合运行时提供专用的更新器客户端：

插件	适用场景
@capgo/capacitor-updater	Capacitor iOS/Android 应用
@capgo/cordova-updater	Cordova iOS 7+ / Android 13+ 应用
@capgo/electron-updater	Electron 桌面应用

无论使用哪个客户端插件，都会执行原生兼容性检查——它会比对 bundle 中记录的原生依赖与已安装的二进制文件。

为什么 Native 兼容性至关重要

每个 Capacitor 应用都包含两层：

• 本指南中介绍的 原生二进制文件 用户从 App Store / Play Store 安装。它包含 Capacitor、您的原生插件以及原生配置。
• 本指南中介绍的 JavaScript 包 （您的 Web 应用），Capgo 可以对其进行热更新。

live update 仅替换 JavaScript 层。如果新的 JavaScript 调用了未编译进已安装的二进制文件的原生插件或 API，调用会在运行时失败——这可能导致应用崩溃或功能静默失效。简单来说：Capgo 无法更新原生 code，因此运行旧版 Native Build 的设备无法安全运行针对新版原生 code 构建的 bundle。

Capgo 如何检测兼容性

当您上传 bundle 或手动运行检查时，Capgo 会将 原生包 （您本地项目中的 Capacitor/Cordova 插件及其版本）与为该 bundle 记录的原生包进行对比，该 bundle 当前在 Channel 上生效:

• 如果两者匹配，说明变更仅涉及 JavaScript， 可以安全地进行热更新.
• 如果添加、删除了插件或更改了版本，则该 bundle 与原生不兼容 — 这些更改只有在用户安装新的原生二进制文件后才会生效。

通过 CLI 进行检查

bunx @capgo/cli@latest bundle compatibility com.example.app --channel production

CLI 会打印一张表，列出每个原生包的本地版本、channel 上当前生效的版本以及状态：

Package              Local    Remote   Status
@capacitor/core      6.1.2    6.1.2    ✅
@capacitor/share     6.0.0    6.0.0    ✅
@capacitor/camera    6.1.0    —        ❌  not in the live bundle

提示

添加 --text 将表情符号替换为 OK/FAIL （在 CI logs 中很方便），并且 --package-json / --node-modules 以指向 monorepo 中的正确路径。

获取机器可读的判定结果 (CI)

对于 pipeline， bundle releaseType 将检查简化为一个单词：

bunx @capgo/cli@latest bundle releaseType com.example.app --channel production
# → OTA      safe to ship as a live update
# → native   needs a new app-store build

将此作为发布 pipeline 的门槛：当它输出 live update 时， OTA，当它输出 native.

不兼容的更新对用户意味着什么

注意

默认情况下，检测到不兼容会 不会 阻止上传 —— 如果你上传了与原生不兼容的 bundle，并将其设为某个 channel 的 active build，Capgo 会将其下发 到该 channel 下的设备。（你可以通过下面的设置把它变成硬性门禁 --fail-on-incompatible — 请参阅 防止下发不兼容的更新 ）。

在仍运行 旧版原生 binary 的设备上，缺失的原生 code 可能导致崩溃或功能异常 —— 即使更新已“成功”下载并应用。这就是为什么 live update 可能已经上线并下发，却仍会让现有用户的应用出问题，以及为什么 Capgo 能在不兼容的 bundle 上线时向你发出警告。

Capgo 的 自动回滚 可以捕获在 notifyAppReady() 之前抛出的 JavaScript 错误，但它不能替代发布兼容的原生 code —— 稍后导致崩溃或原生崩溃的不匹配可能会绕过它。

如何安全地发布 Native 变更

发布新的 Native Build（真正的修复）

当 bundle 需要新的原生 code 时，请构建并向 App Store / Play Store 提交新的二进制文件（或使用 Capgo Cloud Build 重新构建）。一旦用户更新了二进制文件，bundle 的原生依赖项就会匹配，live update 也能正常运行。

如果已上线不兼容的 Bundle，请回滚

如果某个 channel 上已激活不兼容的 bundle，请将该 channel 回滚到最后一个兼容的 build，以停止分发，直到新的 native build 发布。参见 回滚.

防止下发不兼容的更新

两个互补的保护机制，它们都会实际检查你的 native 包：

在 CI 中使上传失败 — --fail-on-incompatible

在你的 bundle upload 步骤中添加该标志。如果 bundle 的 native 包与 channel 当前在线版本不匹配，上传将 以非零退出码失败，且不会发布任何内容 —— 这样你的 pipeline 就能阻止你静默发布一个在用户安装 native build 之前无法生效的 OTA 更新：

bunx @capgo/cli@latest bundle upload --channel production --fail-on-incompatible

兼容的上传——以及无法执行检查的情况（新渠道或无远程元数据）——将原样通过。在交互式终端中，它会提供 Capgo Builder 原生构建流程；拒绝则失败。（不能与 --ignore-metadata-check.)

提示

当你 故意 需要一个与渠道实时原生包不同的 bundle（新插件、Capacitor 升级等），请省略 --fail-on-incompatible 用于该基线上传。日常 OTA CI 请保留此标志。完整渠道工作流： Native + OTA Channel 工作流.

按原生版本控制交付—— metadata + --auto-min-update-version

当你 执行 同时发布 Native Build 和 bundle，将 channel 设置为 metadata 策略，并使用 --auto-min-update-versionCapgo 会在每次上传时执行兼容性检查；当 bundle 需要新的原生 code 时，它会提高更新下限，这样尚未安装匹配原生 build 的设备就不会收到该更新：

# one-time: switch the channel to the metadata strategy
bunx @capgo/cli@latest channel set production com.example.app --disable-auto-update metadata

# from then on, Capgo sets the floor automatically on every upload
bunx @capgo/cli@latest bundle upload --channel production --auto-min-update-version

注意

版本号规则，例如 --disable-auto-update major 是 不会 这只是一个替代方案——它们只拦截版本跳跃，从不检查原生 code，因此随 minor 或 patch 版本发布的原生变更仍会推送出去。请使用 --fail-on-incompatible 或 --auto-min-update-version，它们会检查你的原生 package。

查看 版本定向 以获取完整的定向选项。

相关

Native + OTA 工作流

开发/生产渠道，何时保留 --fail-on-incompatible，以及如何发布有意为之的原生基线。

自动 OTA 或原生

集成 bundle releaseType 到 GitHub Actions 或 GitLab，以便 CI 选择 live update 或 Capgo Build。

版本定向

通过渠道、semver 规则和元数据策略，仅分发兼容的 bundle。

回滚

如果上线了不兼容的 bundle，可将 channel 回滚到上一个兼容的 build。

更新类型

应用时机、延迟条件和版本拦截如何协同工作。

CLI：bundle

关于 bundle 兼容性、releaseType 和上传选项的参考。

从 Native Compatibility 继续

如果你正在使用 原生兼容性 为确保 Live Update 安全，请将其与 版本定向 以根据原生版本路由 bundle， 回滚 以在发布不兼容 bundle 时进行恢复， 更新类型 以了解 channel 版本阻塞机制，以及 Capgo CLI bundle 引用 用于 compatibility 和 releaseType 命令。