无需等待 App Store 审核，即可发布 Capacitor 修复
假设你的结账页面在早上 8 点出现 CSS 对齐问题。恐慌开始了——你需要发布 iOS 版本、Android 版本，做原生重建，还要经历数天的审核。现在不用了。
构建全新的 web bundle，将其推送到受控的 Capgo channel，兼容设备即可拉取，完全无需进入应用商店审核队列。 CSS、JavaScript、文案和资源修复可以在几分钟内送达用户，而原生变更仍遵循常规的二进制发布流程。
目录
何时适合使用 Live File Update
当原生外壳没问题，但 Web 层需要调整时，live update 就能派上用场。那个 CSS 对齐问题？修正样式表，重新构建 Web 资源，发布一个签名 bundle。早上 9 点——bug 出现仅一小时后——用户下次启动应用时就能收到修复。Capgo 通过其更新器应用该 bundle，完全不会触碰原生二进制文件。
以下是我选择方案的方式：
- 使用 live update 适用于 JavaScript 行为、CSS、文本、配置及兼容资源。
- 使用原生发布 适用于插件变更、权限、原生依赖或操作系统级功能。
- 通过渠道测试 在向所有客户公开修复之前。
| 发布类型 | 典型用途 | 用户影响 |
|---|---|---|
| 原生包 | 新的原生能力 | 应用商店下载与审核 |
| 实时 Web bundle | 紧急兼容性修复 | 应用启动时更新 |
保持原生层与 Web 层兼容。 实时 bundle 无法安全引入已安装二进制中不包含的原生 API。如果添加新插件或更改权限，就必须进行原生构建——这一点无法绕过。
如需逐步部署流程，建议阅读 这份关于部署 Capgo 热修复的指南。它介绍了如何将经过测试的修复方案转化为受控发布，而无需将生产环境用户当作你的 QA 团队。
在向生产环境推送更新之前，请先确保本地构建环境稳定。安装 Capgo的开源更新器插件，然后添加其 TypeScript 包，这样编辑器才能识别更新器方法，而不是抛出类型缺失错误。对于 Capacitor 项目，他们的 本地 Capacitor 环境设置指南 值得收藏——它详细说明了如何准备一个干净的工作区。
保持 Web 资源可预测
你的 live bundle 仅包含编译后的 Web 资源——而非你可能编辑的任意源文件。请配置项目，确保构建命令始终将最终的 JavaScript、CSS、HTML 及兼容资源输出到同一 www 或 public 原生外壳引用的目录。
实际操作如下：修改 checkout 样式表后，先跑一遍常规 web build，再检查输出目录，确认生成的文件确实替换了旧版本。不要手动改编译后的文件——下次 build 会悄悄覆盖它们，你会在毫无察觉的情况下丢掉这些改动。
live update 只能分发你的 web build 中包含的内容。 如果修复未包含在
www或public，设备根本无法收到它。
为开发、预发布和生产环境设置独立的 channel。开发版 build 绝不应指向生产 channel，尤其是多名团队成员同时测试未完成的 bundle 时。
- 开发 能在它们继续往下走之前捕获失效的 import 和缺失的 assets。
- Staging 环境 使用接近 release 的设置验证真机行为。
- 生产环境 仅提供审核通过且经过测试的 bundle —— 不含任何实验性内容。
发布前验证 Bundle
在 upload 任何内容前，先做一次简短的完整性检查。这能拦截大多数原本会到达用户的问题：
- 删除之前的 build 输出，然后创建一个新的 build。
- 确认修正后的文件确实存在于输出目录中。
- 测试导航、登录、离线行为以及原生插件调用——而不仅仅是更改的功能。
- 在 iOS 和 Android 测试设备上安装 bundle。
- 记录测试期间使用的 channel 和 bundle 版本，以便日后复现问题。
Electron 团队也可以采用同样的规范：单独构建渲染进程资源，然后确认打包后的应用引用了预期的输出目录。Capgo 的类型化 API 和通道控制让这一工作流更容易保持一致，但它们不能替代实际的兼容性测试。如果更改需要新的原生插件或权限，请发布新的二进制文件，而不是尝试将其作为实时 Web bundle 发布——更新器无法自行修改原生 code。
在 Capacitor 和 Electron 应用中正确进行文件更新，关键在于一个坚如磐石的发布产物。从你已测试过的确切 commit 构建 Web 层，然后仔细检查所有 JavaScript、CSS、HTML 和资源是否都位于 www 或 public 预期位置。如果你在使用 Electron，请单独构建渲染进程，并验证打包后的外壳是否指向该输出目录。
创建可验证的 Bundle
在考虑上传之前，先清除旧的构建输出并重新运行生产构建。记下 commit 哈希、bundle 版本、目标通道以及对应的原生应用版本。这些细节将在日后出现不匹配时为你节省数小时的排查时间。
务必在真机上检查 bundle——真实的 iPhone、Android 手机或 Electron 安装环境。走一遍登录、导航、离线模式，以及所有涉及你刚更新文件的原生插件。如果设备无法实际运行你发送的内容，成功上传到更新服务器毫无意义。
签名会为你的构建产物提供加密指纹。更新器依赖该签名来确认 bundle 在发布 pipeline 中未被篡改。请将签名凭据完全存放在仓库之外，严格限制访问权限，并根据安全策略要求定期轮换。
签名的 bundle 不能替代测试。 签名只能证明构建产物的来源及其未被篡改，但无法说明你的应用是否真的能正常运行它。
如果你想了解全貌，我建议阅读 Capgo 的端到端安全指南以及 code 签名.
通过受控渠道发布
一旦签名的 bundle 准备就绪，将其上传到 Capgo 并分配给符合你发布策略的 channel。你最常使用的有用 channel 包括：
- Beta — 供内部员工和精选测试人员使用
- Staging 环境 — 在真实用户看到之前，先在类生产环境中验证
- 生产环境 — 面向已获授权的受众
- 客户专属 Channel — 当不同租户需要各自独立的更新时机时
这里有个很常见的场景：一家 fintech 团队在生产环境发现支付标签出错。他们把修复后的 web bundle 推送到内部 channel，在几台设备上验证结账流程，再把这份完全相同的、已测试的 artifact 提升到一小部分生产用户，然后才逐步扩大范围。这些 channel 护栏能防止仓促的修复演变成严重事故。
发布后，请深入查看每台设备的 logs，而不是只信 dashboard 上的聚合状态。你需要确认拿到 bundle 的是正确的 App 版本、签名验证通过、安装顺利完成，并且下次启动时确实加载了新文件。
如果有设备报告不匹配，立即暂停该 channel，并逐项对比 bundle 版本、原生兼容性、签名密钥和 channel 分配。只有当测试组的 logs 全部正常后，才扩大分发范围，并且务必保留上一个 bundle 以备回滚。
本地 build 跑顺之后，就该把发布接进 CI/CD pipeline 了。目标很明确：构建 web 资源、给 bundle 签名，并在测试通过后自动发布。不再手动 upload，也不用再纠结 merge 后怎么更新文件 —— 流程会自动搞定。
实际中，一条实用的 pipeline 是这样的：
- 当 release 分支合并到目标分支时，触发该任务。
- 安装依赖并生成一个干净的
www或publicbuild。 - 运行完整的测试套件 —— 包括单元测试、集成测试和设备冒烟测试。
- 使用存储在 CI secret manager 中的凭据对 bundle 进行签名。
- 通过 Capgo 的公开 API 推送到 beta 或 staging channel。
- 验证检查通过后，将同一个 artifact 原样推进到后续环境。不要重新构建。
有一点需要反复强调：切勿将签名密钥或 API token 提交到代码库。请将它们存储为受保护的环境变量，生产发布仅限已批准的分支，并记录每次发布的 bundle 版本、commit hash、native app 版本和目标 channel。Capgo 的 GitHub Actions 集成指南 会带你端到端完成配置。
这里的要点是 验证是交付流程的一部分。发布并不是终点。你的 pipeline 应确认目标设备确实接收并接受了 bundle。
通过差分更新降低传输成本
每次都发送完整 bundle 是浪费——尤其是当版本只修改了样式表或几个 JavaScript 模块时。启用 differential delivery，让设备只下载变更的文件。但务必测试被删除或重命名的资源如何处理，否则生产环境会出大问题。
我见过一家机构通过这种方式，将平均带宽成本降低了 47% ，因为他们从全量 re-bundle 切换到了增量交付。真正的收益在于慢速网络用户，更小的下载量也意味着安装速度明显加快。
我还建议使用独立的 channel 来控制风险暴露：
- Beta 用于内部构建并收集测试者反馈。
- Staging 环境 复刻生产环境设置，不影响客户。
- 生产环境 先面向小范围受众起步，再扩大。
- 客户渠道 让各租户的发布版本彼此隔离。
将已测试的制品晋级——不要跨阶段重新 build。 为每个环境重新 build 会引入漂移，转眼你就在调试本不该存在的差异。
对于金融科技 App，流程可能如下：先发布给员工，再向 5% 的符合条件用户发布，检查每台设备的 logs，只有在采用情况良好且失败率保持平稳时才扩大范围。同时始终保留上一个 bundle。如果出现问题，你需要能在几分钟内暂停或回滚，而不是几小时。
发布 bundle 只是中间一步。要确认用户确实收到了更新，请打开 Capgo 中每台设备的 logs，检查 native 版本、channel、bundle 版本、签名验证、下载状态和安装结果。
一次健康的 rollout 应显示安装后成功启动，而不只是下载完成。对于结账修复，请在多台设备上测试真实购买流程，再将这些结果与网络较慢或 App 版本较旧用户的报告进行对比。
清晰解读更新信号
将采用率与失败指标结合分析。下载率高但反复启动失败，说明 bundle 已损坏；采用率低则可能指向 channel 定向、设备离线或 updater 配置问题。
| 信号 | 通常意味着什么 |
|---|---|
| 已下载 | 设备已获取 bundle |
| 已安装 | 文件已通过安装检查 |
| 启动成功 | App 已使用新文件启动 |
| 已回滚 | 已恢复上一个已知良好的 bundle |
追踪成功启动次数，而不只是下载量。 只有当用户能够正常打开并使用 App 时，更新才算真正生效。
Capgo 的自动回滚保护机制能在新 bundle 导致崩溃或无法启动时提供安全保障。请保留上一版本可用，暂停受影响的 channel，并在发布另一个 artifact 前排查 logs。
视频版本控制与实时分发 pipeline 中的文件更新监控和回滚管理在概念上有共通之处，因此团队在以下场景中也可能觉得这些思路有用： 管理培训视频版本.
验证发布
请参考这份发布后检查清单：
- 确认各 channel 和 App 版本的采用情况。
- 检查下载失败、签名错误和启动失败。
- 在真机上测试变更后的工作流。
- 对比错误发生时间与发布时间戳。
- 如果失败数意外上升，请暂停分发。
- 记录最终的 bundle、commit 以及回滚决策。
如需更深入的指导，请阅读 如何在 Capacitor 应用中监控 OTA 更新。这将文件更新从发布任务转变为受控的运维流程。
Live Updates 是否遵守应用商店规则？
Live Updates 最适合用于 JavaScript、CSS、文案修改、配置调整及兼容资源。它们不是添加原生功能、更改权限或绕过商店审核的后门。发布任何内容前，请务必查看 Apple 和 Google 针对您应用类别的具体政策。
差分更新如何减少下载量？
差分分发仅发送实际变更的文件，而非整个 web bundle。例如，如果您修改了结账页面的一个样式表，就没有必要重新传输所有无关资源。这意味着传输更快，带宽消耗更少。
不过要留意重命名和删除的文件。旧版本残留的陈旧资源可能引发奇怪且难以追踪的 bug。
小补丁仍需进行完整的兼容性测试。 下载体积更小，并不能省去验证完整用户流程的必要性。
设备离线时会发生什么？
离线设备会一直运行当前已安装的 bundle。一旦网络恢复，更新程序会检查分配的 channel 并获取最新的兼容版本。不要假设所有设备都会立即更新——网络不稳定的外勤团队可能会有延迟。
如何处理 Breaking Changes？
把 native binary 和 web bundle 看作配套的一对。如果更新后的 web 文件调用了当前已安装 binary 中不存在的 native 方法，你需要先发布新的 native 版本，再在其上推送 web 更新。
为 beta、staging 和 production 分别运行独立的 channel。务必确认每台设备实际接收到的都是你预期的 channel。出现签名不匹配时，通常说明 artifact 被改动、凭据有误或配置有问题。先暂停分发，对比已发布的内容和测试过的内容，并在重试前仔细查看 device logs。
对于实际的部署工作流， 探索 Capgo — 它为你提供签名发布、channel 控制、差分交付和回滚保护，让你更新文件时不再头疼。
