如何让 Capgo 更新更轻量、更快速

最好的 live update，就是用户几乎察觉不到的那个。

这通常意味着三点：

下载包体积小。
发布过程可控。
一旦出问题，恢复是即时的。

在 React Native 领域通用的“保持 OTA 轻量化”建议同样适用于 Capgo。不同之处在于，Capgo 为 Capacitor 团队提供了几个额外的手段：增量更新, 频道, 自动回滚, 版本定向，以及可选的端到端加密.

把这些手段结合起来用，就能得到更小的 payload、更快的安装速度，运维上的麻烦也少得多。

即使 MAU 不变，轻量依然重要

一个关于 Capgo 的实用细节：Capgo MAU 实际上是指在过去 30 天内访问过更新服务的月活跃设备数。

所以精简 bundle 主要不是为了在 MAU 统计上做文章。它的价值在于改善用户和团队真正能感受到的部分：

在蜂窝网络或弱 Wi-Fi 下下载更快
更佳体验，来自直接更新
减少因发布失败或回滚导致的带宽浪费
在测试或预发布阶段，缩小影响范围

精简更新的核心在于速度、安全性和运维规范。

1. 默认使用 Delta 更新

如果只做一件事，就做这个。

Capgo 的增量更新只发送版本间变更的文件，而不是重新下载整个 web bundle。这是提升日常 OTA 性能最大的一项收益。

bun run build
bunx @capgo/cli@latest bundle upload --channel staging --delta

QA 测试完成后：

bunx @capgo/cli@latest bundle upload --channel production --delta

如果你希望 CI 保持严格，请使用 --delta-only 这样就不会有人不小心回退到全量 bundle 上传：

bunx @capgo/cli@latest bundle upload --channel production --delta-only

仅使用 --delta-only 当你的生产设备群支持 Delta updates 时。在插件版本混杂时，不支持基于 manifest 的 delta 交付的旧设备将无法下载该更新。

如果你使用 directUpdate，这一点就更重要，因为用户会看到从“发现更新”到“应用重新加载”之间的这段时间。

2. 把资源当资源，而不是 JavaScript 包袱

大型资源正是 OTA bundle 悄悄变臃肿的地方。

几条实用规则：

如果普通资源文件就能满足需求，就不要把大图片或媒体文件内联到 JavaScript 中。
如果频繁变动的内容不需要放进随应用发布的 app bundle，就把它放在你自己的 CDN 或 API 上。
注意营销图片、onboarding 视频，以及每次发布都会被替换的一次性活动素材。
让稳定的资源保持稳定。使用 Delta 更新时，未更改的文件会被复用，而不是重新下载。

随着应用不断增长，这是让 Capgo 保持快速的最简单方法之一。最糟糕的模式是：为了一个微小的 UI 修复，却迫使用户下载一大堆无关的媒体文件。

3. 原生发布只留给真正的原生变更

Capgo 更新的是 Web 层：HTML、CSS、JavaScript 以及运行时加载的资源。

它不适合用于：

新的原生插件，
权限变更，
capacitor.config.ts 变更，
任何会修改 iOS 或 Android 原生项目状态的内容。

这条界线对性能也很重要。如果你一直把重大的结构性变更硬塞进 OTA 通道，更新策略会随着时间推移变得更重、风险更高。

请有意使用两条发布通道：

Native 通道

针对插件变更、权限变更和原生配置：

bun run build
bunx cap sync

然后发布常规商店版本。

Capgo 通道

用于安全的 Web 层迭代：

bun run build
bunx @capgo/cli@latest bundle upload --channel production --delta

如果最近添加了大量长期存在的资源，也请定期刷新原生基线。新的商店构建会嵌入该基线，从而保持未来 Capgo 差异更小。

4. 用 Channel 控制发布规模

“精简”更新不仅关乎兆字节大小，还关乎在确认更新良好之前，有多少设备接收到了该更新。

Capgo 的 channel 系统是控制这一点的最佳方式：

staging 供 QA 使用
beta 供受邀测试者使用
production 面向所有用户
hotfix 用于紧急恢复

一个简单的流程如下：

上传至 staging.
在真机上验证。
逐步推广，无论是通过受控渠道还是基于百分比的发布。
如果健康度下降，立即回滚。

如果你的应用在线上有多个原生基线，请将 channels 与版本定向搭配使用。这样可以避免不兼容或过于臃肿的 bundle 被推送到旧版二进制文件上。

对于希望进一步收紧审查流程的团队，Capgo 也非常适合用于 PR 预览这让产品、QA 和相关方无需等待新的 TestFlight 或 Play 内部 build，就能测试仅 JS 变更。

5. 如果启用直接更新，请务必优化启动性能

你希望更新生效得越快，启动路径就必须越规范。

Capgo 的更新行为文档明确建议搭配 directUpdate Delta updates。这是正确的默认做法。

第二个保障机制是 notifyAppReady().

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

CapacitorUpdater.notifyAppReady()

如果你的应用未能在默认的 10 秒 notifyAppReady() 窗口内，或在 appReadyTimeout Capacitor 配置中设置的任何时长内上报就绪，Capgo 可以将该 bundle 标记为无效并恢复上一个正常版本。这种回滚行为在生产环境中正是你需要的，但也意味着你应保持启动过程干净：

调用 notifyAppReady() 在正确的位置
避免在关键路径中执行耗时的启动任务
如果立即重新加载，请谨慎保存和恢复应用状态
在大规模发布前，测试弱网和低端设备场景

如果你最近没有看过， notifyAppReady 指南值得再读一遍。

6. 使用内部更新通道，避免不必要的原生重建

许多移动端团队在处理明显的纯 Web 变更时，浪费了大量时间去构建二进制文件。

如果变更属于：

文案修改，
UI 优化，
onboarding 流程、
定价页逻辑、
分析埋点接入、
feature flags、
prompt 或 API 响应渲染、

那么 Capgo 更新通常是更快的评审产物。

这意味着更少的原生重建、更少的 TestFlight 迭代，以及更紧密的团队反馈闭环。这是 Capgo 最未被充分利用的优势之一：你可以把更多评审和 QA 工作放到 OTA 通道，而不打破原生/Web 边界。

我们这份关于使用单个移动 App ID 进行预发布的指南，介绍了一种长期保持整洁的实用方法。

7. 将 lean 与 secret 分开

小 Bundle 与安全 Bundle 解决的是不同问题。

Channel 控制的是更新资格，本身并不能让 bundle 保密。

如果你需要更强的交付保障：

这样的工具可实现 Live Update 加密,
使用自定义存储或自托管交付,
私钥只应保存在 CI 或受保护的运维工作流中。

但这并不意味着更新包大小不再重要。它只是说明，你应当同时针对这两个维度优化：

保持精简以提升速度，
通过加密实现交付控制，
通过 Channel 实现发布控制，
通过 Rollback 实现恢复。

实用的“精简 Capgo”工作流

如果你想要一个简单的默认运行模式，可以这样做：

将原生发布和 OTA 发布通道分开。
使用以下命令上传 JS 更改： --delta 默认情况下。
使用 staging 以及 beta 发布前的 channels production.
观看更新统计与日志不仅要在发布前，还要在发布后。
当无需 Native Build 时，将 PR 转换为可安装的预览版本。
尽可能避免将体积大、频繁变动的媒体文件放入 bundle 中。
在资源大幅增长或发生 Native 变更后，及时刷新 Native baseline。
把 notifyAppReady() 和回滚行为视为发布工程的一部分，而不是配置阶段的小事。

这种组合比常见的“有变化就上传”方案能更持久地保持快速。

结语

对于 Capgo 团队而言，“精简与快速”不仅仅是 bundle 体积的问题。

这是一个发布设计问题。

利用 Delta updates 控制 payload 大小，利用 channels 控制发布范围，利用 rollbacks 控制故障影响范围。一旦这样看待 OTA，即使 app、团队和用户群不断扩大，更新也能保持快速。

延伸阅读：如何保持 Capgo 更新精简且快速

如果你正在使用 如何让 Capgo 更新更轻量、更快速 要规划 Channel 路由和分阶段发布，请将其与通道有关 Channels 的实现细节，通道有关 Channels 的实现细节，通道有关 Channels 的实现细节， Beta 测试解决方案适用于 Beta Testing Solution 产品工作流的，以及版本定向解决方案适用于 Version Targeting Solution 产品工作流的。