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