原生兼容性

一个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.ts,Capacitor 配置中的插件配置、原生插件或依赖项、Capacitor 本身或 iOS/Android 项目文件。一个实用的检查：如果更改必须更新原生项目通过 npx cap sync 或 npx cap copy context

当更改更新	Ship with Capgo OTA?	context
__CAPGO_KEEP_0__	Ship with __CAPGO_KEEP_0__ OTA？	为什么？
__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包 （您的Web应用）Capgo可以通过无线更新。

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

如何Capgo检测兼容性

当您上传包或手动运行检查时，Capgo会将您的本地项目（您的Capgo/Cordova插件及其版本）中的原生包 原生包 in your local project (your Capacitor/Cordova plugins and their versions) against the native packages recorded for the bundle 当前正在 Channel 上实时更新:

• 如果它们匹配，变化仅为 JavaScript-only 并且 安全通过无线电传输.
• 如果添加、删除或更改了插件版本， 则 Bundle 为 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 日志中交换表情符号（在 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 __CAPGO_KEEP_0__ 防止不兼容的交付 以下)

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

Capgo的 自动回滚 可以捕获在__CAPGO_KEEP_0__运行之前抛出的JavaScript错误，但它并不是替代品，用于交付兼容的本机__CAPGO_KEEP_0__—一个不匹配的崩溃或崩溃本机，可能会绕过它 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.

标题：安全地交付本机更改

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

当一个包需要新的本机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-versionCapgo 在每次上传时运行兼容性检查，并在捆绑包需要新的原生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 是 不是 替代品 — 仅阻止版本跳转并且不检查本地 code, 因此在次要或修补版本中发布的本地更改仍会发布。使用 --fail-on-incompatible 或 --auto-min-update-version查看

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

相关

本地 + OTA 工作流

开发/生产通道，何时保留 --fail-on-incompatible,以及如何发布一个有意的本地基线。

自动OTA或本机

Wire bundle releaseType 将GitHub Actions或GitLab导入CI，选择实时更新或Capgo Build。

版本目标

context:Capgo解决方案营销页面。角色:部分或页面标题。见于：页面解决方案/版本目标.astro。消息键`solutions_version_targeting_title`（解决方案版本目标标题）。|Capgo解决方案营销页面。角色:短UI标签或导航项。见于：页面解决方案/版本目标.astro。消息键`solutions_version_targeting`（解决方案版本目标）。

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

回滚

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

更新类型

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__捆绑包参考