原生兼容性

一个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 原生不兼容: Capgo 可以仍然提供它，但在仍在运行旧版原生构建的设备上，它可能会崩溃或不正常工作。

本页解释了 Capgo 如何检测原生兼容性，什么是不兼容的更新意味着对用户的影响，以及如何安全地将原生变化交付给用户。

注意

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

TLDR: OTA 或原生?

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

在应用程序更新时使用原生应用程序发布 capacitor.config.tsCapacitor配置中的插件配置、原生插件或依赖项、Capacitor自身或iOS/Android项目文件。一个实际的检查：如果更改必须通过 npx cap sync 或 npx cap copy 更新原生项目，才能让已安装的设备使用它，则将其视为原生。

Change	Capgo OTA一起发布吗？	为什么
HTML、CSS、应用程序JavaScript、图像、字体和其他Web构建资产	是的	它们是在运行时从Web包中加载的。
纯JavaScript包更改打包到您的Web输出中	是的	The generated JavaScript is part of the 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 桌面应用

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

为什么原生兼容性重要

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

• 本地二进制 本地二进制 用户从 App Store / Play Store 安装。它包含 Capacitor,您的原生插件和原生配置。
• javascript 包 (您的 web 应用) __CAPGO_KEEP_0__ 可以通过无线电更新。 实时更新仅更换javascript层。如果新javascript调用一个原生插件或 Capgo，而安装的二进制文件中没有编译该原生插件或 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 如何检测兼容性

When you upload a bundle — or run the check manually — Capgo compares the (您的 __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:

• 本地项目中的原生包 安全可通过无线网络传输.
• 如果插件被添加、删除或版本号发生变化，捆绑包将 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 用于交换表情符号的 OK/FAIL (在CI日志中很方便)，并 --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__ 将其 block the upload — if you upload a native-incompatible bundle and set it as a channel’s active build, Capgo — 见 防止不兼容的分发 --fail-on-incompatible 下面。) 防止不兼容的分发 下面

On __CAPGO_KEEP_0__ 设备上，仍在运行的原生二进制文件中，缺失的原生 __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 运行之前抛出的 JavaScript 错误，但这并不是代替发布兼容的原生 Capgo 的方法 — 一旦出现不兼容的原生 Capgo，后果可能会更严重，甚至会导致程序崩溃。 安全发布原生更新 安全发布原生更新 notifyAppReady() 当一个包需要新的原生 code 时，需要在 App Store / Play Store (或使用 __CAPGO_KEEP_1__ Cloud Build 重建) 上发布一个新的二进制文件。一旦用户更新了二进制文件，包的原生依赖项就会正确对齐，实时更新就可以正常运行了。

安全发布原生更新

当一个包需要新的原生 __CAPGO_KEEP_0__ 时，需要在 App Store / Play Store (或使用 __CAPGO_KEEP_1__ Cloud Build 重建) 上发布一个新的二进制文件。一旦用户更新了二进制文件，包的原生依赖项就会正确对齐，实时更新就可以正常运行了。

When a bundle needs new native code, build and submit a new binary to the App Store / Play Store (or rebuild with Capgo Cloud Build). Once users update the binary, the bundle’s native dependencies line up and the live update runs correctly.

如果已经发布了不兼容的包，回滚到上一个兼容版本

如果一个频道上已经有一个不兼容的包，回滚到上一个兼容版本，直到用户安装一个本机包。请参阅 回滚.

防止不兼容的发布

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

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

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

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

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

Gate 原生版本分发 — metadata + --auto-min-update-version

当您 将原生构建和捆绑包一起发送时，请将频道放在 策略上并上传 metadata 。 __CAPGO_KEEP_0__ 在每次上传时运行兼容性检查，并在捆绑包需要新的原生 __CAPGO_KEEP_1__ 时，提高更新阈值以便设备尚未安装匹配的原生构建的设备不接收它： --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，它们会检查您的本地包。

参见 版本目标 以获取完整的目标选项列表。

相关

目标版本

通过频道、语义版本规则和元数据策略，仅传递兼容的捆绑包。

回滚

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

更新类型

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

CLI:捆绑包

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

从原生兼容性继续

原生兼容性 原生兼容性 为了安全地保持实时更新，连接它 版本目标 为了根据本机版本路由捆绑包， 回滚 当不兼容的捆绑包发布时恢复， 更新类型 了解通道版本阻塞和 Capgo CLI捆绑包引用 兼容性和发布类型命令