如何正确 OTA 更新 CapacitorJS 应用

周末下午你发现了一个checkout回归问题。修复已经在你的Capacitor web层中，但是App Store的审批窗口不会在三天内关闭。Android用户可以在三天内接收到新的包，但是强制每个客户重新安装一个本地构建来修复一个JavaScript-only问题仍然是浪费的。

CapacitorJS应用程序的OTA更新是团队学习的实际原因。通过控制OTA发布，可以将签名的web包传递给符合条件的已安装二进制文件，下载它并在下一次启动时应用它，而native变化仍然遵循商店流程。难点不在于上传文件，而在于在livefleet中保持版本目标、签名、发布控制、可观察性和恢复的对齐。

CapacitorJS团队为什么需要OTA
- 将更新器视为交付管道
前提和安装Capgo更新器
- 在构建发布之前验证
安全地将首个OTA包交付
- 阅读仪表板作为发布门户
频道、发布和CI/CD自动化
- 将推广与CI/CD连接
测试策略和自动回滚
- 分离服务器控制和客户端恢复
签名、安全性和OTA无法改变的内容
- 在发布计划中划定界限
每次发布前的操作检查表
- 上传前
- 推广期间

CapacitorJS团队为什么需要OTA

一个Capacitor应用通常包含两个发布面板。原生二进制文件包含平台外壳、权限、插件、图标、特权和其他经过商店审查的功能。Web层包含JavaScript、CSS、HTML、路由、文本和资产。OTA更新只更新第二个面板，因此团队可以修复一个破损的收款流程而不必重建原生外壳，假如更改仅限于平台和商店政策边界， Capgo OTA指南.

一个图表，展示了OTA更新的重要性，通过比较商店延迟和即时修复

操作效益不仅仅是速度。安装的二进制文件不会同步移动。一些客户使用较旧的原生构建，而其他人使用最新的商店版本，每个二进制文件都可以使用不同的原生API访问Web包。一个编译在不支持的原生API上的包，即使JavaScript的差异是有效的，也可能会失败。这使OTA成为兼容性系统，而不是发布工程的捷径

以更新器为运输管道

生产环境需要清晰的顺序:

安装本机桥接: 添加更新器包并同步Capacitor使iOS和Android知道它。
签署捆绑包: 将签名材料放在仓库外并将验证作为客户端路径的一部分。
目标一个频道: 有意路由测试、beta、生产或客户特定的小组。
自动交付: 让CI在测试通过后构建、签名、上传和推广。
观察采用: 通过频道和二进制跟踪下载、安装、启动、崩溃和健康信号。
快速回滚： 恢复一个已知的良好包服务器端并保留客户端恢复保护。

Capgo 是此工作流程的一个选项。其开源 Capacitor 更新器和云服务发布签名的 Web 包到目标通道，应用它们在下一次启动，并暴露版本和设备级别的交付信息。评估可用性和发布韧性的团队还可以查看 Capacitor 应用程序的可用性.

实践规则： 如果您无法确定哪个本机二进制文件一个包目标，不要将该包推送到生产环境。

OTA 成功时，它减少了不必要的存储发布，而不隐藏 Web code 和本机 code 之间的界限。问题不是您的团队是否可以推送一个包。问题是您是否可以解释谁接收了它，为什么他们被资格，什么发生在启动后，以及当包不正常工作时，您将如何恢复服务。

前提和安装 Capgo 更新器

在打开终端之前，确认项目和发布账户已经准备好。您需要一个 Capacitor 5 或 6 应用程序，具有 @capacitor/cli 初始化的 Node 18 或更高版本，目标二进制文件的活跃 Apple Developer 和 Google Play Console 账户，以及一个 Capgo 云账户，具有一个 appId 和 API 密钥。

第一次安装故意小：

npm install @capgo/capacitor-updater
npx cap sync
npx @capgo/cli init

npm install 添加 JavaScript 包和原生依赖。 npx cap sync 这是人们常忽略的步骤，忽略这一步会导致原生桥接未连接。JavaScript层可能会编译，而后台运行时会调用一个在安装的二进制中不存在的桥接。安装后运行同步，另外当原生插件配置发生变化时再次运行同步。

初始化器会修补你的 capacitor.config.ts 将更新器设置、Web端点和默认频道应用到上述文件中。不要盲目接受修补。打开文件并明确验证应用身份和更新协议：

const config: CapacitorConfig = {
  appId: 'com.example.app',
  appName: 'Example',
  version: '1.0.0',
  autoUpdate: true,
  updateUrl: '',
  capgo: {
    channel: 'staging'
  }
}

生成的具体结构可能会根据你的项目和CLI版本而有所不同，但重要的值是相同的。 appId 必须与安装的二进制匹配。 version 必须描述原生构建关系。 autoUpdate 必须反映你的启动策略。 updateUrl 必须指向你的二进制所信任的服务， capgo 块必须标识初始频道。

在构建发布版本之前验证

在打开Xcode或Android Studio之前运行诊断命令：

npx @capgo/cli doctor

A clean result should confirm that the CLI is available, the project configuration is readable, the updater package is detected, required application identifiers exist, and authentication can reach the configured account. It should not report a missing native sync, absent app identity, or invalid updater configuration.

截图来自https://capgo.app/docs/img/cli-doctor.png

首先让native build变得乏味。将其安装在物理iOS设备和Android设备上，启动它并确保有网络访问，关闭并重新打开它，确认更新器可以检查而不会影响正常启动路径。 Capacitor updater installation workflow 在需要比较项目配置与预期插件设置时，__CAPGO_KEEP_0__更新器安装流程是有用的。

安全地将第一个OTA包发送

将第一个包视为发布路径测试，而不是功能发布。创建或旋转签名密钥之前准备 artifact:

npx @capgo/cli key create

将私钥放入密钥管理器中。不要将其提交，存储在项目存档中或在CI输出中暴露。native信任路径需要公共验证材料。只有签名任务才能访问私钥。

在 package.json or your web release metadata. Keep native version fields unchanged for a web-only fix. An OTA bundle cannot add native code or alter the capabilities declared by the installed binary, so a native version change would obscure compatibility rather than improve it.

将签名的artifact上传到预期的渠道：

npx @capgo/cli bundle upload --channel production

A successful upload only confirms that the server accepted a request. Read the command output and verify the bundle identifier, target native-version constraint, signed checksum, and channel assignment. Those fields identify the artifact and show whether installed binaries are eligible to receive it.

阅读命令输出并验证包标识符、目标本机版本约束、签名校验和渠道 assignments。

Read the dashboard as a release gate

查看仪表板作为发布门户 哪个最旧的二进制文件可以运行这个捆绑包？
包详细视图应解决四个发布问题： Minimum native version:
最低本机版本： Which oldest binary can run this bundle?
哪个最旧的二进制文件可以运行此包？ Maximum native version:

最大本机版本： 5%然后定义扩展所需的证据。检查下载和安装成功、正常冷启动、无故障会话和 JavaScript 错误在更改流程中。保留 artifact 身份和交付控制在 Capgo 面板中可见。

使用调试构建来演练设备路径。 getCurrent() 报告当前 bundle， notifyAppReady() 确认新 bundle 达到健康状态：

import { CapacitorUpdater } from '@capgo/capacitor-updater'

const current = await CapacitorUpdater.getCurrent()
console.log(current)

await CapacitorUpdater.notifyAppReady()

在应用初始化到足够通过健康检查后，才调用就绪性。如果它永远无法确认就绪性，自动恢复可能会在下一次冷启动时将 bundle 标记为失败。这个保护措施保护生产用户，但也可能使一个不完整的测试看起来像是一个交付问题。记录每个测试设备的活动 bundle 和启动结果之前扩大暴露。

频道、发布和 CI/CD 自动化

频道是发布的 bundle 和安装的设备之间的路由层。它们也是您的发布门户。一个 staging 频道应该指向一个已知的本机二进制文件，一個 beta 频道应该服务于一个受控的队伍，生产应该在早期频道通过 smoke 测试后才移动。

创建一个明确命名的 staging 路径：

npx @capgo/cli channel create staging
npx @capgo/cli bundle assign <bundle-id> --channel staging

将该频道固定到测试设备使用的原生版本。测试者应运行与生产支持相同的二进制文件，而不是使用额外插件或不同配置的本地开发构建。一旦烟雾测试套件通过，应推广测试的工件，而不是上传第二个略有不同的包。

您的频道映射应存放在 capgo.config.json 并像应用程序一样进行审查 code。保持频道名称稳定，确定预期的原生兼容性范围，并将生产推广作为显式CI操作。对于管理特性暴露和交付暴露的团队，这些特性旗帜治理提示提供了一个有用的方法来分离部署权限和用户面向的激活。

将推广连接到CI

一个实用的 GitHub Actions 设计有两个路径：

拉取请求： 构建 web 层，使用受限预览凭证签名并发布到临时预览频道。关闭拉取请求时销毁或过期该频道。
标记主版本： 运行单元测试，构建生产包，验证其原生版本约束，上传并推广仅当测试任务成功退出时。

推广命令可以像这样看起来：

npx @capgo/cli bundle promote <bundle-id> \
  --to-channel production \
  --percent 5

逐步增加曝光度，如 25%、50%和100%每个步骤之间都需要CI审批或监控的工作。百分比和命令是控制，不是安全性的证据。通过构建成功可以知道包是语法正确的，但这并不意味着它在特定native二进制上、持久的本地状态、慢速连接或从旧会话恢复的设备上是安全的。

发布边界： 一个Web包属于一个二进制兼容窗口。一个频道绝不能成为一个 loophole，服务code，它引用native API，安装的应用程序中没有。

保持TestFlight和Android内部跟踪构建的一致性，通过将每个包与它构建的exact native版本绑定。如果native构建发生变化，发布一个新的兼容性目标包或创建一个新的频道映射。 Capgo GitHub Actions集成指南可以帮助将该政策转换为可重复的工作流程步骤。

一个图表，展示了软件频道和自动化的三个步骤：Staging Channel、Pin Binary和CI/CD Auto-Deploy。

测试策略和自动回滚

OTA发布可以通过CI通过，但在激活后仍然失败。失败可能取决于包、native二进制、存储的设备状态或网络条件。模拟器可以确认屏幕渲染，但无法覆盖每个安装的二进制或显示是否失败的启动是否清洁恢复。

使用三个测试等级：

CI 包测试: 运行单元测试、类型检查、代码检查和生产 Web 构建。测试更改的检出、身份验证、导航和持久性路径，而不是在编译时停止。
私有设备频道: 使用物理设备运行上一个本机二进制文件来种植私有频道。覆盖两种平台、清洁安装、升级安装和代表性存储状态。
生产 Canary: 从小的合格队伍开始，连接崩溃报告和 JavaScript 错误警报。将启动失败视为紧急，因为受影响的用户可能永远不会到达报告应用内错误的code。

The Capacitor OTA 测试指南解释了测试机制。操作规则是简单的：测试每个更新都要保护的本机二进制文件。

分离服务器控制和客户端恢复

服务器端回滚停止新下载:

npx @capgo/cli channel set production --bundle <previous-id>

这改变了什么设备可以发现的下一个内容。它不会擦除已经下载或在每个设备上激活的包，所以客户端也需要恢复控制。配置更新器来保留一个已知的好包并在定义的启动失败条件后恢复。

A可靠的恢复路径包括：

下载失败跟踪： 区分网络问题和无效的包。
安装失败跟踪： 检测解压缩、验证和文件系统问题。
启动健康跟踪： 确认应用程序在激活后达到可用状态。
自动fallback： 在启动反复失败时恢复到之前的已知良好包。
手动升级： 保留设备和包标识符以供支持和工程。

在规模化的车队中，一个小的失败率仍然会创建一个显著的支持负载。 99.95% 的 OTA 更新成功率仍然意味着每 1,000,000 台设备中约有 1,000 次失败根据物联网设备集群的 OTA 测试benchmark. 同一来源描述了包括回滚在 30 分钟内、崩溃率低于 0.1% 和 98% 设备在支持窗口内的保护栏。将这些作为benchmark 示例，而不是普遍的接受标准。根据应用程序的风险和用户影响来设置错误预算。

签名、安全性和 OTA 无法改变的内容

未签名的更新使交付端点成为供应链攻击面。TLS 保护连接，但客户端也必须确认下载的 artifact 来自授权的发布过程，并且在传输过程中未被替换或修改。

使用更新工具生成一个 Ed25519 密钥对。将私钥存储在 CI 秘密中，将公钥嵌入到原生二进制文件中。客户端应在激活之前验证每个包。限制 CLI 令牌根据环境和权限范围，保留上传和推广日志，并要求生产操作的强身份验证。

以兼容性迁移方式处理密钥轮换，而不是单独的配置更改。生成一个替换密钥，发送一个本机构建，信任当前和替换公钥，然后使用新私钥签署发布。只有兼容的本机二进制文件采用替换后，才移除旧密钥。过早移除信任会阻止旧版本的二进制文件接受有效更新。留下被破坏的密钥信任不受限制会破坏轮换。

在发布计划中画出界限

OTA 处理 web 层的变化。需要本机发布的变化依赖于安装的二进制文件中缺失的能力：

类别	通过 OTA 发送	需要本机发布
应用行为	JavaScript 逻辑、路由、验证和状态处理	本机插件实现
呈现	CSS、HTML、副本、主题令牌和兼容图像资源	应用图标和启动屏资源
平台访问	现有Capacitor web层调用到已在二进制中的功能	新权限、特权或本机API
配置	兼容的web配置和远程内容规则	`Info.plist`, `AndroidManifest.xml`,签名身份
商店元数据	不改变商店审查行为或版本元数据	商店政策敏感的元数据和版本号变化

该 Capacitor 升级器code-签名文档解释了验证模型。运用它操作性地与可篡改的审计日志、证书验证、TLS、严格访问控制和版本伪造或密钥丢失的调查过程。

因为安装的原生人口会逐渐变化，兼容性目标仍然很重要。苹果报告 66% 的所有活跃设备在 iOS 26 和 74% 的设备在 iOS 26 的最后四年中引入, 而另一个报告将 iOS 26 置于 79% 的所有设备在周期的后期, 如《移动 OTA 密钥管理研究》中所总结的那样。这些数字涵盖了不同的时间点和设备人口。实践的结论是：即使成熟的平台也不会一次性更新所有设备。根据原生版本和能力分配包裹，而不是假设一个 OTA artifact 适用于整个舰队。发布操作清单将发布清单限制在一页，存储在仓库或运行书中。每次事件发生后都更新它。添加的控制通常可以防止下一次故障的发生。

上传前

__CAPGO_KEEP_0__

__CAPGO_KEEP_1__

确认兼容性： 确认该包针对特定的原生二进制文件并且不使用不可用的插件API。
检查 artifact： 从一个干净的工作空间中构建，检查生成的文件并确认预期的 web 版本。
保护签名： 确认 CI 有预期的密钥和秘钥。检查日志不能泄露私密信息。
验证渠道： 在分配包之前，查看 staging、beta 和生产映射。
保存恢复： 记录上一个已知的良好包并确认回退路径仍然有效。
运行物理烟雾测试： 在代表性设备上测试启动、登录、查看、导航、持久性和更新准备。

推广期间

首先将更新发布到受限的试验组，然后监测与用户影响相关的信号：

无故障的会话： 将结果与前一个版本进行比较，并调查回归问题。
JavaScript 错误率： 按版本、原生版本、平台和功能路径分组错误：
冷启动行为： 检查激活是否改变了启动时间或将用户留在空白屏幕上：
功能覆盖： 确认远程启用的功能与接收的二进制文件匹配：
采用和失败： 将符合条件的设备（未检查更新）与检查更新但失败的设备分开：

保持首个推广观察窗口30分钟 30分钟 在扩大曝光之前

如果关键路径出现问题，恢复生产通道到上一个捆绑包，保留日志，并决定修复是否应该放入另一个OTA捆绑包还是新本机发布。 运作日程表：

Treat this checklist as shared operational code. Capgo can provide signed bundle delivery, channel targeting, rollout controls, update history, and device-level observability. Your team still owns compatibility policy and the decision to promote.

将此清单视为共享的运作Capgo。__CAPGO_KEEP_1__可以提供签名捆绑包交付、通道目标、滚动控制、更新历史和设备级观察性。您的团队仍然拥有兼容性政策和推广决策。 Capgo __CAPGO_KEEP_0__

正确的方式 OTA 更新 CapacitorJS 应用

目录