原生兼容性

一个 Capgo 实时更新会立即替换您的应用程序的 JavaScript 捆绑包 但是它不能改变 part of your app — the Capacitor/Cordova plugins, native dependencies, and native project configuration that are compiled into the installed binary. When a new bundle expects native code that the installed binary doesn’t have, the bundle is 应用程序的一部分 — Cordova 插件、原生依赖项和原生项目配置，编译到已安装的二进制文件中。当一个新捆绑包期望原生 __CAPGO_KEEP_1__，而已安装的二进制文件没有时，该捆绑包是: Capgo 可能仍然能够正常运行，但在仍在运行旧版原生构建的设备上可能会崩溃或异常行为。

This page explains how Capgo 检测原生兼容性，什么是不兼容的更新意味着对用户的影响，以及如何安全地将原生更改部署。

注意

实时更新仅限于 JavaScript 包(bundle)更改。如果您需要更新原生 code — 添加或删除插件，升级 Capacitor，或更改原生项目配置 — 您将需要通过通常的应用商店分发过程提交一个新的二进制构建。

TLDR: OTA 或原生？

Capgo 可以从您的生成的 Web 构建文件夹中发送文件。如果更改仅影响 HTML、CSS、JavaScript、资产或纯 JavaScript 包，打包到输出中的，那么您可以将其作为实时更新。

使用原生应用发布时，一个更改更新 capacitor.config.ts,Capacitor 配置中的插件配置、原生插件或依赖项、Capacitor 本身，或者 iOS/Android 项目文件。一个实用的检查：如果更改必须更新原生项目通过 npx cap sync 或 npx cap copy 在安装设备上使用它之前，视为原生。

更改	是否使用Capgo OTA?	为什么
HTML、CSS、应用程序JavaScript、图像、字体和其他Web构建资产	是	它们是在运行时从Web包中加载的。
纯JavaScript包更改打包到您的Web输出中	是	生成的JavaScript是Web包的一部分。
capacitor.config.ts 更改	否	Capacitor配置在构建时读入原生应用。
添加、删除或升级 Capacitor/Cordova 插件	否	已安装的本机二进制文件必须包含匹配的本机 code。
iOS 或 Android 项目文件更改	否	现有用户需要从商店获取新的二进制文件。

客户端插件按栈排列

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

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

无论客户端插件如何，native 兼容性检查都适用 — 它们将bundle的记录native依赖项与安装的二进制文件进行比较。

native 兼容性为什么重要

每个 Capacitor 应用都有两个层次：

• The native 二进制文件 用户从 App Store / Play Store 安装的。它包含 Capacitor、您的native插件和native配置。
• The JavaScript 包 （您的web应用）Capgo 可以通过无线电更新。

A live update only swaps the JavaScript layer. If the new JavaScript calls a native plugin or API that isn’t compiled into the installed binary, the call fails at runtime — which can crash the app or silently break a feature. In short, Capgo cannot update native code, so a device running the old native build can’t safely run a bundle that was built against new native code.

Capgo如何检测兼容性

当您上传一个包装文件 — 或者手动运行检查 — 时，Capgo会将 本地项目中的原生包（您的__CAPGO_KEEP_0__/Cordova插件及其版本）与包装文件 in your local project (your Capacitor/Cordova plugins and their versions) against the native packages recorded for the bundle 进行比较:

• 如果它们匹配，改变仅为JavaScript-only， 安全地通过无线电发送.
• 如果添加了、删除了或更改了插件版本，包装文件是 原生不兼容 — 这些更改只在用户安装新原生二进制文件后才会生效。

检查从 CLI

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

CLI 打印每个本地包的表格，包括其本地版本、该版本在渠道中的版本和状态：

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 用于交换表情符号（在CI日志中很有用），并 OK/FAIL 用于指向多包仓库中的正确路径。 --package-json / --node-modules 添加

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

对于管道来说， 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

在此门控您的发布管道：在它打印时发送一个实时更新， OTA当它打印时触发一个原生构建 native.

不兼容的更新意味着什么

注意

默认情况下，检测不兼容性不会阻止上传 — 如果您上传一个本机不兼容的捆绑包并将其设置为渠道的活动构建，__CAPGO_KEEP_0__将将其交付给该渠道上的设备。 (您可以将其转换为硬门控 — 见下面的“防止不兼容的交付”。) 不 在仍在运行旧本机二进制文件的设备上，缺失的本机Capgo可能会导致崩溃或功能损坏 — 即使更新下载并应用“成功”。这就是为什么一个实时更新可以是实时的并交付给用户，但仍然会破坏现有用户的应用，以及为什么__CAPGO_KEEP_1__可以在不兼容捆绑包上线时警告您。 __CAPGO_KEEP_0__’s 在上线不兼容捆绑包时，__CAPGO_KEEP_1__将向您发出警告。 --fail-on-incompatible 如果您在上线不兼容捆绑包时启用了__CAPGO_KEEP_1__，Capgo将向您发出警告。 如果您在上线不兼容捆绑包时启用了__CAPGO_KEEP_1__，Capgo将向您发出警告。 如果您在上线不兼容捆绑包时启用了__CAPGO_KEEP_1__，Capgo将向您发出警告。

如果您在上线不兼容捆绑包时启用了__CAPGO_KEEP_1__，Capgo将向您发出警告。 如果您在上线不兼容捆绑包时启用了__CAPGO_KEEP_1__，Capgo将向您发出警告。, the missing native code can cause crashes or broken features — even though the update downloaded and applied “successfully.” This is why a live update can be live and delivered yet still break the app for existing users, and why Capgo can warn you when an incompatible bundle goes live.

Capgo’s 自动回滚 可以捕获在 JavaScript 之前抛出的错误 notifyAppReady() 运行，但这并不是发布兼容的本机 code 的替代品 —— 一种不匹配导致后期崩溃，或本机崩溃，可能会绕过它

如何安全地发布本机更改

发布一个新的本机构建（真正的修复）

当一个捆绑包需要新的本机 code 时，构建并提交一个新的二进制文件到 App Store / Play Store（或重建使用 Capgo Cloud Build）。一旦用户更新了二进制文件，捆绑包的本机依赖项就会对齐，live 更新就能正确运行

如果有一个不兼容的捆绑包已经发布

回滚 回滚.

防止不兼容的交付

两个互补的守卫，实际上都检查了你的原生包：

CI 中的上传失败 — --fail-on-incompatible

将标志添加到你的 bundle upload 步骤。如果包的原生包不匹配通道的当前活跃版本，上传 将以非零退出码失败，并且不会发布任何内容 — 因此，管道会阻止你静默发布一个OTA更新，它直到用户安装原生包才能生效：

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

兼容的上传 — 以及无法运行检查的案例（新通道或无远程元数据） — 将保持不变。在交互式终端中，它提供了Capgo Builder 原生构建流程；拒绝将导致失败。 (无法与 --ignore-metadata-check.)

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

当您 做 将原生构建和捆绑包一起发送，设置 metadata 策略并上传 --auto-min-update-version. Capgo runs the compatibility check on every upload and, when a bundle needs new native code, raises the update floor so devices that haven’t installed the matching native build don’t receive it:

# 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, 因此在一个小版本或补丁版本中发布的本地更改仍然会被发布。使用 --fail-on-incompatible 或 --auto-min-update-version，它会检查您的本地包。

查看 版本目标 以获取完整的目标选项。

相关

版本目标

仅使用通道、semver规则和元数据策略来分发兼容的包。

回滚

如果不兼容的包已发布，则将一个通道恢复到最后一个兼容的构建。

更新类型

如何应用时间、延迟条件和版本阻塞相互协作的方式。

CLI: bundle

bundle兼容性、发布类型和上传选项的参考指南。

从原生兼容性继续

如果您正在使用 原生兼容性 来保持实时更新的安全性， 将其与 版本目标 相连，以便通过原生版本来路由捆绑包， 当不兼容的捆绑包发布时， 更新类型 了解频道版本阻塞，和 Capgo CLI捆绑包引用 兼容性和发布类型命令