如何正确使用ota更新capacitorjs应用

您发现周五下午的结账回归问题。修复已经在您的 Capacitor 网络层中，但 App Store 审核窗口不会在三天内关闭。Android 用户可以在三天内接收新包，但强制每个客户重新安装本机构建以修复 JavaScript-only 修复仍然是浪费的。

这就是团队学习如何 OTA更新 CapacitorJS 应用程序的实际原因。可以控制的 OTA发布可以将签名的 Web 包传递给符合条件的安装的二进制文件，下载它并在下一次启动时应用它，而本机更改仍然遵循商店流程。难点不是上传文件。它是保持版本目标、签名、发布控制、可观察性和恢复在实时舰队中一致的。

为什么 OTA 对 CapacitorJS 团队来说很重要
- 将更新器视为交付管道
前提和安装 Capgo 更新器
- 在构建发布之前验证
安全地将首个OTA包交付给客户
- 阅读仪表板作为发布门户
频道、发布、CI/CD自动化
- 将促销与CI集成
测试策略和自动回滚
- 将服务器控制与客户端恢复分开
签名、安全性和OTA无法改变的
- 在发布计划中画出界限
每次发布前的操作清单
- 上传前
- 促销期间

为什么OTA对CapacitorJS团队来说很重要

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

实时更新的重要性图表，展示了与即时修复相比，商店延迟的对比。

The operational benefit is more than speed. Installed binaries don’t move in lockstep. Some customers launch an older native build, others use a recent store version, and each binary can have different native APIs available to the web bundle. A bundle compiled against an unsupported native API can fail even when the JavaScript diff is valid. That makes OTA a compatibility system, not a shortcut around release engineering.

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

安装原生桥接:

添加更新器包并同步__CAPGO_KEEP_0__，使iOS和Android知道它。 添加更新包并同步Capacitor以便iOS和Android知道。
将签名材料保留在外部仓库中，并将验证作为客户端路径的一部分。 目标一个频道:
有意路由到测试、beta、生产或客户特定小组。 __CAPGO_KEEP_0__ OTA 指南
自动化发布： 让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

一个干净的结果应该确认 CLI 可用，项目配置可读，更新包检测到，所需应用程序标识符存在，且可以访问配置的帐户。它不应报告缺失的本机同步，缺失的应用程序身份或无效的更新配置。

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

保持第一个本机构建故意简单。将其安装在物理 iOS 设备和 Android 设备上，使用网络访问启动它，关闭并重新打开它，并确认更新器可以检查而不影响正常启动路径。 Capacitor 更新器安装流程在需要将项目配置与预期插件设置进行比较时，很有用。

安全地将第一个 OTA 包发送

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

npx @capgo/cli key create

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

修改 JavaScript 端的版本在 package.json 或您的 Web 发布元数据。保持原生版本字段不变以修复 Web-only。OTA 包不能添加原生 code 或更改已安装二进制文件声明的能力，因此原生版本更改将掩盖兼容性而不是改善它。

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

npx @capgo/cli bundle upload --channel production

成功上传只确认服务器接受了请求。阅读命令输出并验证包标识符、目标原生版本约束、签名校验和渠道 assignments。这些字段标识 artifact 并显示是否安装的二进制文件有资格接收它。

读取仪表板作为发布门户

包详细视图应解决四个发布问题：

最低原生版本： 哪个最古老的二进制文件可以运行此包？
最高原生版本： 哪些新二进制文件故意被排除在外？
渠道： 哪个受众可以发现 artifact？
发布比例： 该可接收人群中有多少人可以接收到它？

开始在生产环境中暴露于 5%,然后定义扩展所需的证据。检查下载和安装成功、正常冷启动、无故障会话和在更改流程中的 JavaScript 错误。保持 artifact 身份和交付控制在一起，在 Capgo 面板中可见。

截图来自 https://capgo.app/docs/img/bundle-detail.png

使用调试构建来测试设备路径。 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 和安装的设备之间的路由层。它们也是您的发布门户。一个测试频道应该指向一个已知的本机二进制文件，一个 beta 频道应该服务于一个受控的群体，生产环境应该在早期频道通过 smoke 测试后才移动。

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

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捆绑属于二进制兼容窗口。一个频道绝不能成为服务code的漏洞，这些code引用了安装的app中不存在的native API。

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

一个图表，展示了软件频道和自动化的三个步骤：预发布频道、固定二进制和CI/CD自动部署。

测试策略和自动回滚

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

使用三个测试等级：

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

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

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

服务器回滚停止新下载:

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

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

可靠的恢复路径包括:

下载失败跟踪: 区分连接问题和无效的文件包。
安装失败跟踪: 检测解压缩、验证和文件系统问题。
启动健康跟踪: 确认应用程序在激活后达到可用状态。
自动回退: 在启动多次失败时恢复上一个已知良好的包。
手动升级: 保留设备和包标识符以便支持和工程。

在大规模的车队中，一个小的失败率仍然会创建一个显著的支持负载。 99.95% 的 OTA 更新成功率仍然意味着每 1,000,000 台设备中约有 1,000 次失败根据 OTA 测试benchmark 对 IoT 设备的fleet. 同一来源描述了包括回滚在 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、严格访问控制和版本伪造或密钥泄露的调查过程。

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

上传前

targetLanguage

pagePath

确认兼容性： 确认该包针对的原生二进制文件是准确的，并且不使用不可用的插件API。
检查 artifact： 从一个干净的工作空间中构建，检查生成的文件，并确认预期的Web版本。
保护签名： 确认CI有预期的密钥和密钥。检查日志不能泄露私密信息。
验证通道： 在分配包之前，审查测试、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 应用程序

目录