回滚

虽然 Capgo 的 Live Update 可以让你快速向用户交付改进和修复，但在某些情况下，你可能需要回滚到 App 的上一个版本。例如，新更新引入了意料之外的关键问题，或者你希望在开发修复方案时先撤销某个特定的更改。

Capgo 提供了多种管理 Channel 构建版本并控制用户接收 App 版本的方法，包括手动回滚选项和自动安全机制。

自动回滚保护

Capgo 内置了安全机制，以保护用户免受损坏更新的影响。如果在调用 notifyAppReady() 方法之前发生了 JavaScript 错误，插件将自动回滚到上一个可用的版本。

自动回滚的工作原理

当下载并应用新更新时，Capgo 要求你的 App 在 notifyAppReady() 可配置的时间范围内调用该方法，以确认更新已成功加载。该方法表示：

• JavaScript bundle 已成功加载且无严重错误
• 应用的核心功能运行正常
• 该更新可以安全保留

如果 notifyAppReady() 若因 JavaScript 崩溃或严重错误而未调用，Capgo 将会：

1. 检测到更新未能正常初始化
2. 自动回滚至上一个可用的 bundle
3. 将有问题的更新标记为失败，防止其再次被应用

提示

请务必调用 notifyAppReady() 在应用初始化时，待核心组件成功加载后调用 code。这样可确保自动回滚保护按预期生效。

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

// Call this after your app has successfully initialized
await CapacitorUpdater.notifyAppReady()

这种自动保护机制可以确保即使您不小心推送了有问题的更新，用户也不会因为应用无法运行而陷入困境。

配置超时时间

您可以通过设置以下参数来配置 Capgo 的等待时长： notifyAppReady() 等待被调用的时间，通过设置 appReadyTimeout 在您的 Capacitor 配置中：

{
  "plugins": {
    "CapacitorUpdater": {
      "appReadyTimeout": 10000
    }
  }
}

本指南中介绍的 appReadyTimeout 该值以毫秒为单位。默认超时时间通常为 10 秒，但您可以根据应用的初始化需求进行调整。如果您的应用由于复杂的初始化过程导致加载时间较长，建议增加此值。

回滚到上一个 Bundle

每当您上传新的 build 并将其分配给某个 channel 时，Capgo 都会保留这些 build 的历史记录。如果您需要撤销某个特定的更新，可以选择其中一个之前的 build 重新部署到该 channel。

回滚的主要方式是通过回滚界面。在 Capgo Dashboard 中查看频道时，该界面位于第 4 个标签页（History）。此标签页提供了该频道所有可用 build 的完整视图，方便您轻松选择并恢复到任何之前的版本。

通过 History 标签页进行回滚：

1. 登录 Capgo 控制台.

2. 导航至 “Channels” 部分。

3. 点击您想要回滚的频道名称。

4. 在频道视图中进入第 4 个标签页 (History)。

5. 在 build history 中找到您想要恢复的版本。

6. 选择该 build，将其设为该频道的当前 active build。

7. 确认您要回滚到此构建记录。

备选方法：使用 Crown 图标

第二种方式是，您也可以直接在第一个标签页中，点击该 Channel 构建历史里任意构建旁的皇冠图标来回滚：

1. 在 Channel 视图的第一个标签页中，找到您想要回滚到的构建记录。
2. 点击该构建记录旁的皇冠图标，将其设为该 Channel 的活动构建。
3. 确认您要回滚到此构建记录。

注意

回滚到之前的构建仅影响所选的 Channel。如果您有多个 Channel（例如 Production、Staging 等），则需要对每个受影响的 Channel 重复回滚操作。

回滚完成后，配置为监听该 Channel 的设备在下次检查更新时，将接收到之前的构建。回滚后的构建会被视为一次新更新，因此仍适用常规的更新流程和条件。

通过通知加速关键回滚

重新指向 Channel 通常会在设备下次检查更新时生效。Capgo 通知可以在支持的应用处于后台时，发送静默更新检查通知。启用 updater 集成后，应用可以根据配置的更新模式，自动检查、下载并安装回滚版本。

这是一种加速路径，而非强制性的集群命令。推送仍遵循尽力而为原则，取决于操作系统的后台调度、网络可用性以及设备状态。它无法更新离线或被强制退出的应用，因此无法保证每个设备都能在固定时间内完成更新。

要配置此路径，请遵循以下步骤： 通知：启用静默更新检查.

取消 Channel 绑定

如果您想在排查问题时暂时停止某个 Channel 的更新，可以将其与当前的 Build 解绑。

要解绑 Channel：

1. 在 Capgo Dashboard 中前往该 Channel。

2. 点击当前 Build 旁的 “Unlink” 按钮。

3. 确认您要解绑该 Channel。

Channel 一旦解绑，将不再分发任何新更新。配置了该 Channel 的设备将保持在当前 Build 版本，直到该 Channel 再次与某个 Build 绑定。

如果你发现某个更新有问题，但还不确定要回滚到哪个 build，这个功能会很有用。取消关联 Channel 可以让你有时间排查，而无需推送更多更新。

强制使用内置 Bundle

在更严重的情况下，你可能希望将某个 Channel 上的所有设备都回滚到最初随 App 原生二进制文件一起打包的 Web build。这被称为“内置 Bundle”。

要在某个 Channel 上强制使用内置 Bundle：

1. 在 Capgo Dashboard 中前往该 Channel。

2. 点击“Built-in Bundle”按钮。

3. 确认你要强制使用内置 Bundle。

当你强制使用内置 Bundle 时，所有配置到该 Channel 的设备在下次检查更新时，都会回滚到最初打包的 Web build。无论它们当前运行的是哪个 build，都会如此。

这是一种比回滚到指定旧 build 更激进的回滚选项，因为它会丢弃自 App 上次发布到 App Store 或 Play Store 以来发布的所有 Live Update。

注意

强制使用内置 bundle 时请务必谨慎，因为这会影响该 channel 下的所有设备。在执行此操作前，请确保已评估潜在影响并制定了后续方案。

监控并响应问题

为了快速发现问题并最大限度地减少故障更新带来的影响，制定一套针对发布版本的监控及问题响应方案至关重要。

一些策略包括：

对于仍仅面向某个 cohort 的 rollout，请使用 渐进式发布 来暂停曝光或清除其目标，然后再更改整个 channel 的 stable bundle。

• 在发布更新后立即监控崩溃报告和用户反馈
• 使用 phased rollout 或分阶段 channel 系统，在全量发布前先在小范围测试更新
• 建立明确的决策流程，确定何时进行 rollback、unlink 或强制使用内置 bundle，以及谁有权执行
• 在适当时向用户说明问题及解决方案

通过结合严密的监控与快速管理问题更新的能力，您可以在最大限度减少用户干扰的同时，持续提升 App 的使用体验。

继续了解 Rollbacks

如果你正在使用 回滚 要规划回滚和版本控制，请将其与 版本定向 有关 Version Targeting 的实现细节， 更新行为 有关 Update Behavior 的实现细节， bundle 有关 bundle 的实现细节，请参阅： Capgo Live Updates 用于 Capgo Live Updates 的产品工作流，以及 Capacitor Live Updates 回滚策略 用于 Capacitor Live Updates 回滚策略的实际场景。