原生兼容性

A Capgo live update 替换了您的应用 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 native-incompatible: Capgo 可能仍然能够正常工作，但在仍在运行旧版原生构建的设备上可能会崩溃或异常行为。

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

Note

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.

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

Capgo 可以将文件从您的生成的 Web 构建文件夹发送。如果更改仅影响 HTML、CSS、JavaScript、资产或纯 JavaScript 包装到该输出中的包，作为 live update 发送。

在更改更新时使用原生应用发布。 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	Cordova iOS 7+ / Android 13+ 应用
@capgo/electron-updater	Electron 桌面应用

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

为什么原生兼容性重要

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

• 第一层 原生二进制 用户从App Store/Play Store安装。它包含Capacitor、您的native插件和native配置。
• The JavaScript包 (您的web应用)可以通过Capgo进行无线更新。

A live update仅更新JavaScript层。如果新JavaScript调用native插件或API，而这些native插件或API未编译到已安装的二进制文件中，则调用会在运行时失败——这可能会导致应用崩溃或静默地破坏某个功能。简而言之：Capgo无法更新native code，因此运行旧native构建的设备无法安全地运行针对新native code构建的包。

如何Capgo检测兼容性

当您上传包或手动运行检查时，Capgo会将您的本地项目中的 原生包 在您的本地项目（您的Capacitor中Cordova插件及其版本）与捆绑包中记录的原生包进行比较 进行比较:

• 如果它们匹配，变化仅为JavaScript，并且 安全地通过无线电发送.
• 如果添加了、删除了或更改了插件版本，捆绑包 是本机不兼容的 — 只有当用户安装了新的本机二进制文件时，这些变化才会生效

从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 日志中交换表情符号（在 CI 日志中很方便），并 OK/FAIL 指向单元测试中正确的路径。 --package-json / --node-modules 获取机器可读的判决结果（CI）

获取机器可读的判决结果（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

在您的发布管道中设置门控：在它打印时发布一个 live update OTA, 并触发本地构建时打印 native.

不兼容的更新意味着什么

注意

默认情况下，检测不兼容性不 not 阻止上传 — 如果您上传一个不兼容的原生包并将其设置为渠道的活动构建，Capgo 分发到该频道上的设备。 (您可以将其转换为一个硬门控) — 见 --fail-on-incompatible 防止不兼容的分发 Section titled “What an incompatible update means for your users” below.)

On devices still running the older native binary, 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 automatic rollback can catch a JavaScript error thrown before notifyAppReady() 運行正常，但它并不是替代原生 code 兼容性的方法 —— 后期可能会因为不兼容而崩溃，或者在本地崩溃，可能会绕过它。

How to ship native changes safely

Publish a new native build (the real fix)

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

回滚如果已经发布的包不兼容

如果一个不兼容的包已经在一个频道上激活，恢复频道到最后一个兼容的构建，以便停止服务，直到本机构建发布。请参见 回滚.

防止不兼容的交付

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

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

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

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

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

提示

当您 故意 需要一个与渠道的live本机包（新插件，Capacitor升级等）不同的捆绑包时，忽略 --fail-on-incompatible 为该基线上传保留该标志。每日OTA CI保持标志： 本机+OTA渠道工作流.

通过本机版本控制门户交付 —— metadata + --auto-min-update-version

当您 do 将原生构建和捆绑包一起发送，设置渠道到 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

Caution

版本号规则类似 --disable-auto-update major are not 一个替代方案 — 它们只会阻止版本跳转，而不会检查本机code，因此在次要或补丁发布中发布的本机更改仍会发布。使用 --fail-on-incompatible 或 --auto-min-update-version检查您的本机包

查看 版本目标 查看完整的目标选项

相关

开发/生产通道，何时保留

，以及如何发布一个有意的本机基线 --fail-on-incompatible自动OTA或本机

自动OTA或本机

Wire bundle releaseType 将GitHub Actions 或 GitLab 中的live update 与 Capgo Build 进行比较。

版本目标

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

回滚

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

更新类型

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

CLI:捆绑包

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

继续原生兼容性

如果您正在使用 原生兼容 为了保持实时更新的安全，连接它 版本目标 根据Capgo的翻译指南，以下是翻译结果： “根据本机版本路由捆绑包，” Rollbacks 回滚 to recover when an incompatible bundle ships, 更新类型 Capgo CLI 包依赖 __CAPGO_KEEP_0__ __CAPGO_KEEP_1__