本机兼容性

一个 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 can still deliver it, but it may crash or misbehave on devices that are still running the older native build.

本页解释了如何Capgo检测原生兼容性、不兼容更新意味着什么以及如何安全地部署原生更改。

注意

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

为什么原生兼容性很重要

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

• 原生二进制文件 用户从App Store/Play Store安装的。它包含__CAPGO_KEEP_0__、您的原生插件和原生配置。 users install from the App Store / Play Store. It contains Capacitor, your native plugins, and native configuration.
• __CAPGO_KEEP_0__ __CAPGO_KEEP_1__ (您的 Web 应用) 可以通过 Capgo 远程更新.

live update 只更新 JavaScript层。如果新 JavaScript 调用一个本机插件或 API，而这个本机插件或 API 没有编译到已安装的二进制文件中，调用会在运行时失败 — 这可能会导致应用程序崩溃或静默地破坏一个功能。简而言之： Capgo 无法更新本机 code，所以运行旧本机构建的设备无法安全地运行一个构建在新本机 code 上的捆绑包。

Capgo 如何检测兼容性

当您上传一个捆绑包 — 或者手动运行检查时，Capgo 将比较 本机包 在您的本地项目（您的 Capacitor/Cordova 插件及其版本）与捆绑包 当前在渠道上记录的本机包:

• 如果它们匹配，改变是 JavaScript-only 的， 安全地可以通过 air 远程更新.
• 如果添加了、删除了或改变了插件版本，捆绑包是 native-incompatible — 只有当用户安装了新的本机二进制文件时，这些更改才会生效。

从 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 (handy in CI logs), and --package-json / --node-modules 为 monorepo 指定正确的路径。

获取机器可读的判决结果 (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_KEEP_0__可能会导致崩溃或功能损坏 — 即使更新下载并应用“成功”。这就是为什么一个实时更新可以是实时的并交付给用户，但仍然会破坏现有用户的应用程序，而为什么__CAPGO_KEEP_1__可以警告您当一个不兼容的捆绑包上线时。 block the upload — if you upload a native-incompatible bundle and set it as a channel’s active build, Capgo will deliver it to devices on that channel. (You can turn this into a hard gate with --fail-on-incompatible — see Prevent incompatible deliveries below.)

防止不兼容的交付 Prevent incompatible deliveries, 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 自动回滚 可以捕获在__CAPGO_KEEP_0__运行之前抛出的JavaScript错误 notifyAppReady() 但是它并不是发布兼容的本机code的替代品——一个不兼容的本机code，可能会在后面崩溃，或者本机崩溃，可能会绕过它

如何安全地发布本机更改

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

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

如果一个不兼容的捆绑包已经在一个频道上活跃，回滚到最后一个兼容的构建，停止在本机__CAPGO_KEEP_0__发布之前继续服务它

如果一个频道上已经活跃的捆绑包不兼容，回滚到最后一个兼容的构建，停止在本机__CAPGO_KEEP_0__发布之前继续服务它 回滚.

防止不兼容的交付

两个互补的守卫，实际上都检查了您的本机包：

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 在每次上传时都会运行兼容性检查，如果捆绑包需要新的原生 code，就会提高更新阈值，以便设备尚未安装匹配的原生构建的设备不会接收到它：

# 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 是 不作为替代品 — 它们只会阻止版本跳转，并且不会检查本地__CAPGO_KEEP_0__，所以在一个小版本或补丁版本中发布的本地更改仍会被发布。使用 a substitute — they only block version jumps and never inspect native code, so a native change shipped in a minor or patch release still goes out. Use --fail-on-incompatible ，它会检查您的本地包。 --auto-min-update-version查看

版本目标 为目标选项的完整集合查看。 相关

标题为“相关”的部分

仅使用通道、semver规则和元数据策略来交付兼容的捆绑包。

回滚

Rollbacks

如果一个不兼容的捆绑包上线，恢复一个通道到最后一个兼容的构建。

更新类型

了解如何应用延迟条件、延迟和版本阻塞之间的协作方式。

CLI:捆绑包

捆绑包兼容性、发布类型和上传选项的参考。

从原生兼容性继续

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