更新行为

当你为 Capgo 应用发布更新时，通常希望用户尽快收到。但你也不希望强制他们等待下载或在会话中途重启应用，从而影响用户体验。

Capgo 的更新行为旨在兼顾快速交付更新与尽量减少对用户的干扰。

默认更新流程

默认情况下，Capgo 处理应用更新的方式如下：

1. 当应用进入前台时，Capgo 插件会检查是否有可用的新更新。应用保持打开期间，它还会按由以下项控制的循环定时器再次检查： periodCheckDelay （默认为 10 分钟）。

2. 如果发现更新，会在后台下载，用户可继续使用当前版本的应用。

3. 下载完成后，Capgo 会等待用户将应用切至后台。

4. 当用户下次将应用切回前台时，运行的就是更新后的版本。

这一流程确保用户始终运行最新版本的应用，既不会被更新提示打断，也无需被迫等待下载。

提示

Capgo 会在应用进入前台时，以及应用保持打开期间通过重复定时器检查更新。 periodCheckDelay 控制该间隔时间（默认 10 分钟）。

为什么采用这种方案？

在后台或 kill 事件时应用更新，对用户体验有几个关键好处：

• 用户不会在会话过程中被更新提示中断，也不必被迫等待下载。

• 更新会在会话间隙无缝应用，因此每次启动应用都是最新版本。

• 你可以频繁发布更新，而无需担心干扰正在使用应用的用户。

主要缺点是，如果用户把应用切到后台又很快切回，由于更新是在这两步之间应用的，可能会丢失未保存的状态。

为了缓解这一问题，我们建议：

• 频繁保存状态，并在应用恢复时平滑还原。

• 避免发布过于频繁且会大幅修改应用状态的更新。

• 对于敏感业务流程，建议考虑自定义更新行为（见下文）。

自定义更新应用时机

在某些情况下，你可能希望更精确地控制更新的应用时机。例如，你可能希望确保用户在更新前完成当前流程，或者让 App 更新与服务端变更保持同步。

Capgo 提供了一个 setDelay 函数，允许你指定安装更新前必须满足的条件：

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

await CapacitorUpdater.setMultiDelay({
  delayConditions: [
    {
      kind: 'date',
      value: '2023-06-01T00:00:00.000Z',
    },
    {
      kind: 'background',
      value: '60000',
    },
  ],
});

此示例将延迟更新安装，直到 2023 年 6 月 1 日之后，且 App 已进入后台至少 60 秒。

可用的延迟条件包括：

• date: 等待到特定日期/时间后再应用更新。
• background: 在 App 进入后台后，等待至少一段时长再应用更新。
• nativeVersion: 在应用更新前，等待安装了满足最低版本要求的 Native Build。
• kill: 等待下次应用被杀进程（kill event）时再应用更新。

你可以组合使用这些条件，从而精确控制更新的安装时机。

危险

请注意， kill 该条件目前会在首次 kill event 后触发更新，而不是像其他条件那样在下次后台事件后触发。此不一致性将在后续版本中修复。

立即应用更新

对于关键更新或状态非常简单的应用，你可能希望在下载完成后立即应用更新，而不必等待后台或 kill event。Capgo 通过以下方式支持此功能： autoUpdate 在你的 Capacitor 配置中的 policy。

立即应用所需的参数：--delta, autoSplashscreen, 和 SplashScreen

"atInstall", "onLaunch"，以及 "always" 在用户等待时应用更新。使用 增量更新 以便仅下载变更的文件。上传完整的 zip 包会降低用户体验。

这些模式还需要 @capacitor/splash-screen 以及 autoSplashscreen: true 配合 SplashScreen.launchAutoHide: false。如果没有 splash 插件，用户在应用更新时可能会看到闪烁或过时的 UI。

当 autoUpdate 已设置为 "atInstall", "onLaunch"，或 "always" 在您的 capacitor.config中，CLI 会检测到它。在非交互式环境中，它会自动发送 Delta 更新；在交互式环境中，它会在上传前提示你确认。旧版 directUpdate 配置仍会被检测到。使用 --no-delta 来强制上传完整 bundle。

npx @capgo/cli@latest bundle upload --delta

autoUpdate 在你的 capacitor.config.ts 文件中设置，而不是在 JavaScript code 中。它支持以下值：

• false 或 'off': 禁用自动更新检查
• true 或 'atBackground' (默认值): 每次进入前台时自动检查并下载，并在下次应用进入后台时应用更新
• 'atInstall': 仅在全新安装或通过原生应用商店更新后立即应用；否则使用 "atBackground" 行为
• 'onLaunch': 仅在应用从被终止状态进入前台（冷启动）时立即应用。首次检查后，回退到 "atBackground" 行为
• 'always': 每次进入前台时检查，并在有可用更新时立即应用
• 'onlyDownload': 自动检查并下载，触发 updateAvailable, 且绝不会自动设置下一个 bundle 或应用更新

在不使用 Live Updates 的情况下测试 Native Build

查看 无需 Live Updates 测试 Native Build 以了解 native-version、channel-policy 和 CI 配置防护。

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  plugins: {
    CapacitorUpdater: {
      autoUpdate: 'always', // or 'atInstall' for updates only on app install/update
      autoSplashscreen: true,
      keepUrlPathAfterReload: true,
    },
    SplashScreen: {
      launchAutoHide: false, // Required for instant apply with autoSplashscreen
    },
  },
};

export default config;

注意

重要提示: instant apply 模式仅在插件实际进行检查时才会应用更新。默认情况下，检查会在应用进入前台时运行，并在应用保持打开状态时通过定时器循环运行。 periodCheckDelay 控制该间隔时间（默认 10 分钟）。

使用 autoUpdate: 'always'，Capgo 会在每次进入前台时进行检查，并在该次检查的下载完成后立即应用更新，即使此时用户正在使用应用。由 Capgo 控制的定期检查 periodCheckDelay 也可以在应用保持打开状态时触发相同的立即应用行为。

请注意，由于 autoUpdate 属于原生配置，instant apply 模式需要在您的 JavaScript code 中进行一些额外的处理。

注意

即时应用模式需要 @capacitor/splash-screen 以及 autoSplashscreen: true。在 launchAutoHide: false 中进行 SplashScreen 配置（如上所示），以便在更新完成前保持启动页可见。

仅自动下载而不应用

如果您希望 Capgo 自动检查并下载更新，但绝不自动应用，请使用 autoUpdate: 'onlyDownload':

const config: CapacitorConfig = {
  plugins: {
    CapacitorUpdater: {
      autoUpdate: 'onlyDownload',
    },
  },
};

在此模式下，插件会在 bundle 下载完成后发出 updateAvailable 您的应用随后可以决定何时调用 CapacitorUpdater.set() 或显示自定义的更新提示。

自动处理 Splashscreen

即时应用模式 ("atInstall", "onLaunch", "always") 需要 autoSplashscreen 以及 @capacitor/splash-screen （自 7.6.0 版本起可用）。安装插件后，请保持 splash 显示，直到 Capgo 将其隐藏：

const config: CapacitorConfig = {
  plugins: {
    CapacitorUpdater: {
      autoUpdate: 'always', // or 'atInstall'
      autoSplashscreen: true, // Automatically hide splashscreen
      keepUrlPathAfterReload: true,
    },
    SplashScreen: {
      launchAutoHide: false,
    },
  },
};

当 autoSplashscreen 已启用：

• 应用更新时，插件会自动隐藏 splashscreen
• 无需更新时，插件会自动隐藏 splashscreen
• 你无需手动监听 appReady 事件或调用 SplashScreen.hide()

Splashscreen 隐藏后的额外工作

保留 autoSplashscreen: true. 如果您需要在更新就绪后执行额外逻辑，请监听 appReady 也要监听。请勿跳过 splash 插件或 autoSplashscreen 用于此操作：

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

CapacitorUpdater.addListener('appReady', () => {
  // Update is applied. autoSplashscreen already hid the splash.
});

CapacitorUpdater.notifyAppReady();

本指南中介绍的 appReady 事件会在应用完成初始化并应用所有待处理更新后触发。

设置 keepUrlPathAfterReload 改为 true 在使用 instant apply 模式时。这可以在应用因更新而重新加载时保留当前的 URL 路径。

使用 instant apply 模式有助于推送关键 Bug 修复或安全补丁，但也有一些取舍：

• 在应用更新时，用户可能会看到短暂闪烁或加载状态，如果 @capacitor/splash-screen 缺失或 autoSplashscreen 未启用。
• 如果更新改动了应用状态或 UI，用户可能会在会话中途遇到干扰性变化。
• 用户在应用中的位置可能会丢失，如果 keepUrlPathAfterReload 未设置，可能会让用户迷失方向。
• 你需要仔细处理状态的保存与恢复，以确保过渡顺畅。

如果你确实启用了 instant apply，我们建议：

• 使用以下方式上传 npx @capgo/cli@latest bundle upload --delta 以确保下载不会拖慢用户体验。
• 安装 @capacitor/splash-screen 以及设置 autoSplashscreen: true 配合 launchAutoHide: false.
• 设置 keepUrlPathAfterReload 改为 true 以保留应用中的用户位置。
• 根据需要保存和恢复应用状态，避免用户进度丢失。
• 彻底测试应用的更新行为，确保不会出现突兀的过渡、状态丢失或令人困惑的位置变化。

在大多数情况下，默认的更新行为在快速交付更新和减少干扰之间达到了最佳平衡。但对于有特殊需求的 App，Capgo 提供了高度的灵活性，允许您自定义更新的应用时机和方式。

继续了解更新行为

如果你正在使用 更新行为 要规划 live update 的交付，请将其与 Capgo Live Updates 用于 Capgo Live Updates 中的产品工作流， 概览 用于 Overview 中的实现细节， 功能 用于 Features 中的实现细节， 更新类型 请参阅 Update Types 中的实现细节，以及 快速入门 有关 Getting Started 中的实现细节，请参阅