原生兼容性

一个 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 插件、native 依赖项和native 项目配置，编译到已安装的二进制文件中。当一个新包期望的native __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 可以仍然交付它，但它可能会在仍在运行旧native 构建的设备上崩溃或不正常工作。

注意：

仅限于 JavaScript 包的更改。若需更新原生 code — 添加或移除插件、升级 Capacitor 或更改原生项目配置 — 则需通过通常的应用商店分发流程提交新的二进制构建。

原生兼容性为何重要

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

• The 原生二进制 用户从 App Store / Play Store 安装的内容。它包含 Capacitor、您的原生插件和原生配置。
• JavaScript 包 (您的 Web 应用程序) __CAPGO_KEEP_0__ 可以通过无线电更新。 实时更新仅更换 JavaScript 层。如果该新 JavaScript 调用原生插件或 Capgo，而这些并未编译到已安装的二进制文件中，则在运行时会出现调用失败的情况 — 这可能会导致应用程序崩溃或静默地破坏某个功能。简而言之： __CAPGO_KEEP_1__ 无法更新原生 __CAPGO_KEEP_2__，因此运行旧原生构建的设备无法安全地运行针对新原生 __CAPGO_KEEP_3__ 构建的包。

A live update swaps only the JavaScript layer. If that 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. Put simply: 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会将 本机包 in your local project (your Capacitor/Cordova plugins and their versions) against the native packages recorded for the bundle 当前在线的频道:

• 如果它们匹配， 该更改仅为JavaScript-only，.
• 安全通过无线电发送 如果添加了、删除了或更改了插件版本， 捆绑包是

Check from the CLI

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

The 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）

Get a machine-readable verdict (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__ block the upload — if you upload a native-incompatible bundle and set it as a channel’s active build, Capgo 送达 到该渠道的设备上。 (您可以将其转换为硬门控 — 见 --fail-on-incompatible Prevent incompatible deliveries 下文。) 在仍在运行旧版原生二进制文件的设备上，缺失的原生__CAPGO_KEEP_0__可能会导致崩溃或功能损坏 — 即使更新下载并应用“成功”。这是为什么实时更新可以实时且已投递，但仍会破坏现有用户的应用，以及为什么__CAPGO_KEEP_1__可以在不兼容的包投放时警告您。

__CAPGO_KEEP_0__的 自动回滚, 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 On devices still running the older native binary, the missing native __CAPGO_KEEP_0__ 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_KEEP_1__ can warn you when an incompatible bundle goes live. 可以捕获在运行之前抛出的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

当你 一起打包native build和bundle,将channel设置为 策略并上传 metadata __CAPGO_KEEP_0__在每次上传时都会运行兼容性检查，如果bundle需要新的native __CAPGO_KEEP_1__,会提高更新阈值以防止设备未安装匹配的native build接收更新： --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 版本跳跃的替代品——它们只会阻止版本号跳跃，而不会检查native __CAPGO_KEEP_0__,因此在小版本或修复版本中发布的native变化仍会被推送。使用 use 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 规则和元数据策略来分发兼容的包。

回滚

如果不兼容的包发布了，恢复到最后一个兼容的构建。

更新类型

How __CAPGO_KEEP_0__: bundle timing, delay conditions, and version blocking work together.

CLI:

关于__CAPGO_KEEP_0__: 兼容性、发布类型和上传选项的参考。

从原生兼容性继续

如果您正在使用 原生兼容性 来保持实时更新的安全性，连接它与 版本目标 来根据原生版本路由__CAPGO_KEEP_0__: 回滚 来恢复当不兼容的__CAPGO_KEEP_0__: 发布时 更新类型 为了了解频道版本阻塞以及 Capgo CLI 打包引用 兼容性和发布类型命令。