周五下午，你发现了一个结算功能的回归 Bug。修复代码已在 Capacitor Web 层中就绪，但 App Store 的审核期还要持续三天。虽然 Android 用户可以更快收到新包，但为了一个仅涉及 JavaScript 的修复而强制所有用户重新安装 Native Build，依然非常低效。
这就是团队学习 CapacitorJS OTA 更新的实际原因。受控的 OTA 发布可以将已签名的 Web bundle 推送到符合条件的已安装二进制文件中，并在后台下载，下次启动时自动应用；而 Native 层的变更仍遵循应用商店流程。难点不在于上传文件，而在于如何在庞大的设备群中保持版本目标、签名、发布控制、可观测性和恢复机制的一致性。
目录
- 为什么 OTA 对 CapacitorJS 团队至关重要
- 准备工作与安装 Capgo Updater
- 安全发布你的首个 OTA Bundle
- 渠道管理、灰度发布与 CI/CD 自动化
- 测试策略与自动回滚
- 签名、安全机制以及 OTA 的局限性
- 每次发布前的运维检查清单
为什么 OTA 对 CapacitorJS 团队至关重要
一个 Capacitor 应用通常包含两个发布层面。原生二进制文件承载了平台壳层、权限、插件、图标、entitlements 以及其他经过应用商店审核的能力。Web 层则承载了 JavaScript、CSS、HTML、路由、文案和资源。OTA 更新针对的是第二个层面，因此只要变更保持在 Capacitor 指南所述的平台和商店政策范围内，团队就可以在无需重新构建原生壳层的情况下修复损坏的结账流程。 Capgo OTA 指南.
其带来的运维收益不仅限于速度。已安装的二进制文件并非同步更新。部分用户可能运行着旧的原生 build，而其他用户则在使用最新的商店版本，每个二进制文件能为 web bundle 提供的原生 API 也各不相同。如果 bundle 是针对不支持的原生 API 编译的，即使 JavaScript diff 有效也可能失败。这使得 OTA 成为了一个兼容性系统，而非绕过发布工程的捷径。
将更新器视为一条交付 pipeline
生产环境配置需要清晰的流程：
- 安装原生 bridge： 添加 updater package 并同步 Capacitor，以便 iOS 和 Android 识别。
- 对 bundle 进行签名： 将签名材料保存在代码库之外，并将验证环节纳入客户端路径。
- 指定一个 channel： 有针对性地划分 staging、beta、production 或特定客户的分组。
- 实现交付自动化： 仅在测试通过后，才允许 CI 进行 build、sign、upload 和 promote。
- 监控采用情况： 按 channel 和 binary 追踪 download、install、boot、crash 及健康状态信号。
- 快速回滚： 在服务端恢复已知的良好 bundle，并保留客户端的恢复保护机制。
Capgo 是该工作流的一种选择。其开源的 Capacitor updater 和云服务可将已签名的 web bundles 发布到目标 channels，并在下次启动时应用，同时提供版本和设备级的交付信息。评估可用性和发布韧性的团队还可以查看 Capacitor 应用的 app availability.
实用原则： 如果你无法确定某个 bundle 对应的 native binary，请勿将其 promote 到 production。
当 OTA 能在减少不必要的 store releases 的同时，又不模糊 web code 与 native code 之间的边界时，它才是成功的。问题不在于你的团队能否 push 一个 bundle，而在于你是否能解释谁收到了它、他们为何符合条件、启动后发生了什么，以及当 bundle 出现异常时你将如何恢复服务。
前提条件与安装 Capgo Updater
在打开终端之前，请确认项目和发布账号已准备就绪。你需要一个 Capacitor 5 或 6 应用，并具备 @capacitor/cli 已初始化，Node 18 或更高版本，目标二进制文件对应的 Apple Developer 和 Google Play Console 活跃账号，以及一个带有 Capgo 云端账号的 appId 和 API 密钥的 API 云端账号。
首次安装步骤非常精简：
npm install @capgo/capacitor-updater
npx cap sync
npx @capgo/cli initnpm install 添加 JavaScript 包和原生依赖。 npx cap sync 是很多人会跳过的步骤，而忽略这一步会导致原生桥接（bridge）未链接。JavaScript 层可能编译成功，但运行时会调用已安装二进制文件中不存在的桥接。安装后以及原生插件配置发生变化时，请务必运行同步。
初始化程序会使用 updater 设置、Web 端点和默认 channel 来修补你的 capacitor.config.ts 。不要盲目接受补丁。请打开文件并明确验证应用身份和更新合约：
const config: CapacitorConfig = {
appId: 'com.example.app',
appName: 'Example',
version: '1.0.0',
autoUpdate: true,
updateUrl: '',
capgo: {
channel: 'staging'
}
}生成的具体结构可能会因你的项目和 CLI 版本而异，但关键数值是一致的。 appId 必须与已安装的二进制文件匹配， version 必须描述 Native Build 的关联关系， autoUpdate 必须体现你的发布策略， updateUrl 必须指向你的二进制文件所信任的服务，且 capgo 该代码块必须指定初始 channel。
构建发布版本前先验证
打开 Xcode 或 Android Studio 前，先运行诊断命令：
npx @capgo/cli doctor结果正常时应确认 CLI 可用、项目配置可读、检测到 updater 包、必要的应用标识符存在，且认证能访问配置的账户。不应报告缺少 native sync、缺少应用身份或 updater 配置无效。
让第一个 Native Build 刻意保持简单。把它装到 iOS 和 Android 真机上，联网启动，关闭再重新打开，确认 updater 能在不影响正常启动路径的情况下完成检查。该 Capacitor updater 安装工作流 在需要对比项目配置与预期 plugin 设置时很有用。
安全发布你的首个 OTA Bundle
把第一个 bundle 当作发布路径测试，而不是功能上线。准备 artifact 前，先创建或轮换签名密钥：
npx @capgo/cli key create将私钥存放在 secrets manager 中。不要提交到代码库、存进项目归档，也不要在 CI 输出中暴露。原生信任链需要的是公开的验证材料。只有签名任务才能访问私钥。
修改 JavaScript 端的版本号，位于 package.json 或 Web 发布元数据中。对于仅限 Web 的修复，请保持 native version 字段不变。OTA bundle 无法添加 native code，也无法更改已安装二进制文件声明的能力，因此更改 native version 只会掩盖兼容性问题，而不会改善它。
将签名后的 artifact 上传至目标 channel：
npx @capgo/cli bundle upload --channel production上传成功仅代表服务器接受了请求。请阅读命令输出，并核实 bundle identifier、目标 native-version 约束、签名校验和以及 channel 分配。这些字段用于标识 artifact，并显示已安装的二进制文件是否符合接收条件。
把 Dashboard 当作发布闸门
Bundle 详情页应能回答四个发布问题：
- 最低 native version： 哪个最旧的二进制文件可以运行这个 bundle？
- 最高 native version： 哪些较新的二进制文件被有意排除在外？
- Channel： 哪些受众可以发现该 Artifact？
- 发布比例： 符合条件的受众中有多少比例可以接收？
生产环境曝光开始时间： 5%，然后定义扩大曝光所需的证据。检查下载和安装是否成功、冷启动是否正常、无崩溃会话，以及变更流程中的 JavaScript 错误。在 Capgo dashboard 中同时显示 Artifact 标识和交付控制项。
使用 debug build 验证设备路径。 getCurrent() 报告当前活跃的 bundle，并且 notifyAppReady() 确认新 bundle 已达到健康状态：
import { CapacitorUpdater } from '@capgo/capacitor-updater'
const current = await CapacitorUpdater.getCurrent()
console.log(current)
await CapacitorUpdater.notifyAppReady()仅在 App 初始化到足以通过健康检查后，才调用 readiness。如果 App 从未确认 readiness，自动恢复机制可能会在下次冷启动时将该 bundle 标记为失败。该保护机制能保护生产环境用户，但也可能让不完整的测试看起来像是交付问题。在扩大曝光范围之前，请记录每台测试设备的活跃 bundle 和启动结果。
Channels、Rollouts 与 CI/CD 自动化
Channels 是已发布 bundle 与已安装设备之间的路由层，也是你的发布门禁。Staging channel 应指向已知的原生二进制，Beta channel 应服务受控用户群，而 Production channel 只有在上一 channel 通过冒烟测试后才能推进。
使用明确的名称创建 staging 路径：
npx @capgo/cli channel create staging
npx @capgo/cli bundle assign <bundle-id> --channel staging将该 channel 固定到测试设备所使用的 Native Build 版本。测试人员应运行与生产环境一致的二进制文件，而不是带有额外 plugin 或不同配置的本地开发版本。一旦冒烟测试通过，请直接晋升（promote）已测试的 artifact，而不是上传第二个略有不同的 bundle。
您的 channel map 应存放在 capgo.config.json 并像应用 code 一样进行审查。保持 channel 名称稳定，明确预期的 Native 兼容范围，并将生产环境晋升设为明确的 CI 操作。对于在交付的同时还要管理功能曝光的团队，这些 feature flag 管理技巧 可以有效地将部署权限与面向用户的激活功能分离。
将晋升流程连接到 CI
一个实用的 GitHub Actions 设计包含两条路径：
- Pull requests： 构建 Web 层，使用受限的预览凭据进行签名，并发布到临时预览 channel。当 pull request 关闭时，销毁或使该 channel 过期。
- Tagged main releases： 运行单元测试，构建生产 bundle，验证其 Native 版本约束，执行 upload，并在测试任务成功退出后才进行晋升。
promotion 命令可能如下所示：
npx @capgo/cli bundle promote <bundle-id> \
--to-channel production \
--percent 5按计划分步扩大曝光，例如 25%、50% 和 100%，并在每一步之间设置 CI 审批或受监控的 job。百分比和命令只是控制手段，并非安全性的证明。构建通过只能说明 bundle 语法有效，并不能说明它在特定 native binary 上、存在持久化本地状态时、网络缓慢时，或设备从旧会话恢复时的表现如何。
发布边界： Web bundle 属于某个二进制兼容窗口。Channel 绝不能成为漏洞，用来下发引用了已安装 App 并不包含的 native API 的 code。
通过将每个 bundle 绑定到其构建时对应的确切 native 版本，保持 TestFlight 和 Android internal-track 构建的一致性。如果 native build 发生变化，请发布面向兼容性的新 bundle，或创建新的 channel 映射。 Capgo GitHub Actions 集成指南 可以帮助你将该策略转化为可重复的工作流步骤。
测试策略与自动回滚
OTA 发布即使通过了 CI，在激活后仍可能失败。失败原因可能取决于 bundle、native binary、设备上存储的状态或网络状况。模拟器能确认某个界面可以渲染，但无法覆盖所有已安装的 binary，也无法说明启动失败后能否顺利恢复。
使用三个测试层级：
- CI bundle 测试： 运行单元测试、类型检查、linting 以及生产环境 Web build。不仅要通过编译，还要覆盖变更后的结账、身份验证、导航和持久化路径。
- 私有设备 Channel： 在运行旧版 Native Build 的真机上预设一个私有 Channel。覆盖双平台、全新安装、覆盖安装以及具有代表性的存储状态。
- 生产环境 Canary： 从一小部分符合条件的受众开始，配合崩溃报告和 JavaScript 错误告警。将启动失败视为紧急事件，因为受影响的用户可能根本无法进入报告应用内错误的 code。
该 Capacitor OTA 测试指南 解释了测试机制。操作规则很简单：针对每个更新，都要针对其旨在保护的 Native Build 进行测试。
将服务端控制与客户端恢复分离
服务端回滚会停止新的下载：
npx @capgo/cli channel set production --bundle <previous-id>这会改变符合条件的设备下次发现的内容。它不会删除设备上已下载或正在运行的 bundle，因此客户端也需要具备恢复控制能力。请配置 updater 以保留一个已知的稳定版本，并在达到定义的启动失败条件后进行回滚。
可靠的恢复路径包括：
- 下载失败追踪： 区分网络连接问题与无效的 artifact。
- 安装失败追踪： 检测解包、校验及文件系统问题。
- 启动健康度追踪： 确认应用在激活后能进入可用状态。
- 自动回滚： 当启动反复失败时，恢复上一个已知的稳定 bundle。
- 手动升级处理： 保留设备和 bundle 标识符，以便进行技术支持和工程排查。
在海量设备规模下，即使是很小的失败率也会带来巨大的运维压力。A 99.95% 的 OTA 更新成功率，仍意味着每 100 万台设备中会有约 1,000 台更新失败，根据 IoT 设备集群的 OTA 测试基准。同一来源描述了包括 30 分钟内回滚、崩溃率低于 0.1% 以及 98% 的设备处于支持窗口内的防护机制。请将这些视为基准示例，而非通用的验收标准。应根据应用的风险和用户影响来设定错误预算。
签名、安全以及 OTA 无法更改的内容
未经签名的更新会使交付端点成为供应链攻击的风险点。TLS 虽然可以保护连接，但客户端还必须确认下载的产物来自授权的发布流程，且在传输过程中未被替换或篡改。
使用更新工具生成 Ed25519 密钥对。将私钥存储在 CI secret 中，并在应用 build 期间将公钥嵌入 native 二进制文件中。客户端应在激活前验证每个 bundle。按环境和权限范围限制 CLI token，保留 upload 和 promotion 日志，并对生产环境操作实施强身份验证。
请将密钥轮换视为一次兼容性迁移，而非单一的配置变更。首先生成替换密钥，发布一个同时信任当前密钥和替换密钥的 Native Build，随后使用新的私钥对版本进行签名。只有在兼容的 Native 二进制文件都已完成替换后，才能移除旧密钥。过早移除信任会导致旧版本无法接受有效的更新；而无限期信任已泄露的密钥则会让轮换失去意义。
在发布计划中明确界限
OTA 负责 Web 层面的变更。当变更依赖于当前已安装二进制文件中不存在的能力时，则需要进行 Native 发布：
| 类别 | 通过 OTA 发布 | 需要 Native 发布 |
|---|---|---|
| 应用行为 | JavaScript 逻辑、路由、校验及状态处理 | Native 插件实现 |
| 表现层 | CSS、HTML、文案、主题 Token 及兼容的图片资源 | App 图标与启动页资源 |
| 平台访问 | 现有 Capacitor Web 层对二进制中已有能力的调用 | 新的权限、entitlements 或原生 API |
| 配置 | 兼容的 Web 配置和远程内容规则 | Info.plist, AndroidManifest.xml，签名身份 |
| 应用商店元数据 | 不会更改经商店审核的行为或版本元数据 | 对商店政策敏感的元数据和版本号变更 |
该 Capacitor 更新程序 code 签名文档 说明了验证模型。请在实际操作中结合防篡改审计日志、证书验证、TLS、严格的访问控制，以及针对版本欺骗或密钥泄露的调查流程来落实。
兼容性目标设定仍然至关重要，因为已安装的 Native 用户群体是逐渐变化的。Apple 报告称 iOS 26 占所有活跃设备的 66% 和 过去四年内推出的设备中，iOS 26 占比达 74%，而另一份报告则显示 iOS 26 在 生命周期后期的设备占比为 79%，正如 移动端 OTA 密钥管理研究。这些数据涵盖了不同的时间点和设备群体。但得出的实际结论是一致的：即使是成熟的平台，也不会一次性更新所有设备。应根据 Native 版本和功能分配 bundle，而不是假设一个 OTA 产物能适配所有设备。
每次发布前的操作检查清单
将发布检查清单保持在一页以内，并与代码仓库或 Runbook 一起保存。每次发生故障后都要更新它。在真实故障后增加的控制措施通常能有效防止问题再次发生。
upload 前
- 确认兼容性： 验证 bundle 是否针对确切的 native binary，且未使用不可用的插件 API。
- 检查构建产物： 在干净的工作区执行 build，检查生成的文件，并确认预期的 web 版本。
- 保护签名： 确认 CI 已配置预期的 secret 和 key。检查 logs 不会泄露私密材料。
- 验证 Channel： 分配 bundle 前，先检查 staging、beta 和 production 的映射。
- 保留恢复能力： 记录上一个已知可用的 bundle，并验证 fallback 路径是否仍然有效。
- 进行真机冒烟测试： 在有代表性的设备上测试启动、登录、结账、导航、持久化和更新就绪情况。
推广期间
先向小部分用户发布，然后观察与用户影响相关的指标：
- 无崩溃会话数： 将结果与上一个 bundle 进行对比，并排查是否存在回归问题。
- JavaScript 错误率： 按 bundle、原生版本、平台和功能路径对错误进行分组。
- 冷启动行为： 检查激活后是否改变了启动流程，或是否导致用户停留在白屏界面。
- 功能覆盖率： 确认远程启用的功能与接收该功能的二进制文件一致。
- 采用率与失败率： 将尚未检查更新的符合条件设备，与已检查但失败的设备区分开来。
先将首次发布后的观察窗口保持为 30 分钟 后再扩大发布范围。如果关键路径中断，请将 production channel 回滚到上一个 bundle，保留 logs，并决定修复方案是放入另一个 OTA bundle 还是发布新的原生版本。
发布日规范： 只有当团队明确 fallback bundle 的 identifier、兼容范围及恢复命令时，它才能发挥作用。
将此清单视为共享的运维 code。Capgo 可提供已签名的 bundle 交付、channel 定向、发布控制、更新历史以及设备级可观测性。您的团队仍需负责兼容性策略及发布决策。
Capgo 为 CapacitorJS 团队提供了受控的路径，用于更新已签名的 JavaScript、CSS、配置和资源，并具备 channels、分阶段交付、回滚保护和发布可观测性。请在下次部署时应用此清单，针对 staging binary 进行测试，并评估 Capgo 其在生产工作流中的适用性。
