原生兼容性

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

This page explains how Capgo detects native compatibility, what an incompatible update means for your users, and how to ship native changes safely.

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

Live updates are limited to JavaScript bundle changes. If you need to update native code — adding or removing a plugin, upgrading Capacitor, or changing native project configuration — you’ll need to submit a new binary build through the usual app-store distribution process.

原生或 OTA？

Capgo can send files from your generated web build folder. If the change only affects HTML, CSS, JavaScript, assets, or pure-JavaScript packages bundled into that output, ship it as a live update.

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

变更	与CapgoOTA一起发布？	为什么
HTML、CSS、应用JavaScript、图像、字体和其他Web构建资产	是	它们在运行时从Web包中加载。
纯JavaScript包更改打包到您的Web输出中	是	The generated JavaScript is part of the web bundle.
capacitor.config.ts 更改	No	Capacitor 配置在构建时间读入到原生应用中。
添加、删除或升级 Capacitor/Cordova 插件	No	安装的原生二进制文件必须包含匹配的原生 code。
iOS 或 Android 项目文件更改	No	现有用户需要从商店获取新的二进制文件。

客户端插件按栈排列

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,您的原生插件和原生配置。
• The JavaScript 包 (您的 Web 应用) Capgo 可以通过无线电更新。

实时更新仅更换 JavaScript 层。如果该新 JavaScript 调用原生插件或 API，但未编译到已安装的二进制文件中，则在运行时会出现调用失败的情况 —— 这可能会导致应用程序崩溃或静默地破坏一个功能。简而言之： Capgo 无法更新原生 code,因此运行旧原生构建的设备无法安全地运行针对新原生 code 构建的包。

Capgo 如何检测兼容性

当您上传包或手动运行检查时，Capgo 将比较 本地项目中的原生包 (您的 Capacitor/Cordova 插件及其版本)与包 当前在渠道上记录的原生包:

• 如果它们匹配，则更改仅为 JavaScript-only safe to ship over the air.
• 如果一个插件被添加、删除或版本号改变， 不兼容原生 — 只有用户安装了新的原生二进制文件，这些变化才会生效。

从 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 默认情况下会检测不兼容性，但不会阻止上传 — 如果您上传一个不兼容的本机包并将其设置为渠道的活动构建，__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 防止不兼容的分发 防止不兼容的分发 防止不兼容的分发

在仍在运行的原生二进制文件的设备上，缺失的原生__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的方法 — 一旦出现原生崩溃或崩溃，后果就无法避免了。 安全地发布原生更新 安全地发布原生更新 notifyAppReady() runs, but it isn’t a substitute for shipping compatible native code — a mismatch that crashes later, or crashes natively, can slip past it.

发布一个新的原生构建（真正的修复）

安全地发布原生更新

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，它们会检查您的本地包。

参见 版本目标 了解所有目标选项的详细信息。

相关

自动 OTA 或本机

Wire bundle releaseType 将 GitHub Actions 或 GitLab 导入到 CI 中，以便 CI 检测实时更新 vs Capgo Build。

版本目标

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

回滚

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

更新类型

了解如何将应用时间、延迟条件和版本阻塞一起使用。

CLI: 包

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

继续从本机兼容性

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