原生兼容性

A 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 检测原生兼容性，什么是不兼容的更新意味着您的用户，以及如何安全地将原生更改交付。

注意

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

TLDR: OTA 或原生?

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

使用原生应用程序发布时，更新 capacitor.config.ts,在 Capacitor 配置中存储的插件配置、原生插件或依赖项、 Capacitor 自身或 iOS/Android 项目文件。一个实用的检查：如果更改必须更新原生项目通过 npx cap sync 或 npx cap copy context

如果更改仅影响 HTML 文本片段，使用原生应用程序发布。	Ship with Capgo OTA?	使用 __CAPGO_KEEP_0__ 实时更新吗？
为什么	HTML、CSS、应用程序 JavaScript、图像、字体和其他 Web 构建资产	是的
__CAPGO_KEEP_0__	是	生成的 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 应用都有两个层次：

• The 原生二进制文件 用户从 App Store / Play Store 安装。它包含 Capacitor, 你的原生插件和原生配置。
• The JavaScript 包 (Capgo 可以通过无线更新)

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

如何 Capgo 检测兼容性

当你上传一个包 —— 或者手动运行检查 —— 时， Capgo 会比较 原生包 在你的本地项目中（你的 Capacitor/Cordova 插件和它们的版本）和包中记录的原生包 当前正在 Channel 上实时更新:

• 如果它们匹配，变化仅为 JavaScript-only 并且 安全通过无线电传输.
• 如果添加了、删除了或更改了插件版本，捆绑包是 native-incompatible ——那些变化只有在用户安装新 native 二进制文件后才会生效

从 CLI 中检查

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

CLI 打印一个表格，列出了每个 native 包及其本地版本、Channel 上的版本以及状态：

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）

获取机器可读的判决结果（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 — see 防止不兼容的交付 以下)

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

Capgo的 自动回滚 可以捕获在 notifyAppReady() 运行之前抛出的JavaScript错误，但它并不是替代品，用于交付兼容的本机code—一个不匹配的崩溃或崩溃本机，可能会绕过它。

安全地交付本机变化

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

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

回滚一个已经发布的不兼容包

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

防止不兼容的发布

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

在 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

当你 做 同时将原生构建和捆绑包一起发送， metadata 在策略中设置渠道并 --auto-min-update-version使用 . Capgo 在每次上传时运行兼容性检查，并在捆绑包需要新的原生 code 时，将更新阈值提升，以便设备尚未安装匹配的原生构建的设备不接收到它：

# 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 是 不是 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查看

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

本机 + OTA 工作流

，以及如何将意图的本机基线发送

Native + OTA Workflow --fail-on-incompatibleDev/production channels, when to keep

自动 OTA 或本机

Wire bundle releaseType 将 GitHub 动作或 GitLab 导入到 CI 中，CI 可以选择实时更新 vs Capgo 构建。

版本目标

context

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

回滚

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

更新类型

CLI: bundle

__CAPGO_KEEP_0__: 包

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

如果您正在使用 Native Compatibility 与 版本目标 页面/区域：Capgo解决方案营销页面。角色：部分或页面标题。见于：页面解决方案/版本目标.astro。消息键`解决方案版本目标标题` (Solutions Version Targeting Title)。|页面/区域：Capgo解决方案营销页面。角色：短UI标签或导航项。见于：页面解决方案/版本目标.astro。消息键`解决方案版本目标` (Solutions Version Targeting)。 以原生版本为路由 回滚 恢复当不兼容的捆绑包发布时 更新类型 Capgo CLI bundle reference __CAPGO_KEEP_0__ __CAPGO_KEEP_1__捆绑包参考