原生兼容性

一个 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.

原生兼容性

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

使用原生应用发布时更改更新 capacitor.config.ts, plugin configuration stored in Capacitor config, native plugins or dependencies, Capacitor itself, or iOS/Android project files. A practical check: if the change must update the native project through npx cap sync 更新 npx cap copy 或

更新	使用Capgo进行在线更新？	更新
更新	更新	更新
更新	Yes	生成的 JavaScript 是作为 Web 包的一部分。
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 桌面应用

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

为什么 native 兼容性重要

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

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

A live update 只更新 JavaScript 层。如果新 JavaScript 调用 native 插件或 API，而这些插件或配置没有编译到已安装的二进制文件中，调用会在运行时失败 — 这可能会导致应用崩溃或静默地破坏某个功能。简单来说：Capgo 无法更新 native code, 所以运行旧 native 构建的设备无法安全地运行针对新 native code 构建的包。

如何 Capgo 检测兼容性

当你上传一个包 — 或者手动运行检查 — 时，Capgo 会将你的本地项目中的 原生包 在您的本地项目（您的 Capacitor/Cordova 插件及其版本）与 bundle 中记录的原生包进行比较 native packages:

• 如果它们匹配，改变仅为 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 用于在 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 防止不兼容的分发 不兼容的更新意味着什么 以下.)

仍在运行的设备上 较旧的本机二进制文件, 可能会导致缺失的本机 code 导致崩溃或功能损坏 — 即使更新已下载并应用“成功”。 这是为什么一个 live update 可以实时并交付，但仍然会破坏现有用户的应用，为什么 Capgo 可以在不兼容的捆绑包上线时警告你。

Capgo 的 自动回滚 可以捕获在 JavaScript 中抛出的错误 notifyAppReady() 運行，但它并不是替代原生 code 兼容的发布 —— 后期可能会因为不匹配而崩溃，或者原生崩溃，可能会绕过它。

标题：安全地发布本机变化

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

当一个包需要新的本机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 或本机

相关

Wire bundle releaseType 将数据 GitHub Actions 或 GitLab 中的 live update 与 Capgo Build

版本目标

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

回滚

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

更新类型

如何应用时间、延迟条件和版本阻塞一起工作

CLI:捆绑包

原生兼容性参考

继续原生兼容性

如果您正在使用 原生兼容性 为了保持实时更新的安全，连接它 版本目标 to route bundles by native version Rollbacks to recover when an incompatible bundle ships 更新类型 为了了解频道版本阻塞, 和 Capgo CLI for the compatibility and releaseType commands