更新类型

Capgo 支持多种 OTA 更新类型。本页会列出并说明所有类型，帮你为应用选择合适的组合。

生效时机

控制项 何时 更新在下载完成后才会应用。当应用切换到前台时，插件会检查更新；在应用保持打开期间，插件还会通过重复定时器定期检查。 periodCheckDelay 控制该间隔时间（默认 10 分钟）。

类型	描述	使用场景
autoUpdate: atBackground	每次前台检查时检查并下载，App 切到后台时应用更新	适用于大多数应用；干扰最小
autoUpdate: atInstall	仅在全新安装或原生应用商店更新后立即应用；否则使用 atBackground	新用户获取最新版本；现有用户使用后台应用
autoUpdate: onLaunch	仅在冷启动（进程被杀 → 前台）时立即应用；随后回退至 atBackground	在更新及时性与会话稳定性之间取得平衡
autoUpdate: always	每次切回前台时检查，一旦有更新便立即应用	关键修复，或状态管理简单的应用
autoUpdate: onlyDownload	自动检查并下载，发出 updateAvailable，且永不自动应用	自行显示更新提示，或精确控制调用时机的应用 set()

在以下位置配置 capacitor.config.ts:

plugins: {
  CapacitorUpdater: {
    autoUpdate: 'atBackground', // default; true is still accepted
    // or: 'off' | 'atInstall' | 'onLaunch' | 'always' | 'onlyDownload'
  }
}

提示

完整详情和 splashscreen 处理，请参阅 更新行为.

延迟条件

必须满足的条件 在……之前 更新已安装。使用 setMultiDelay 来组合它们（必须满足所有条件）。

条件	描述	示例
日期	等到指定日期/时间之后	配合服务端发布
后台	应用进入后台后等待最短时长 (ms)	避免在应用快速切换时应用更新
nativeVersion	要求原生二进制最低版本	在不兼容的 native code 上阻止更新
kill	等到下一次应用 kill 事件	仅在完全重启时应用

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

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

危险

本指南中介绍的 kill 该条件在首次 kill 事件后触发，而非像其他条件那样在下次进入后台时触发。此问题将在未来版本中修复。

版本阻止（Channel 策略）

控制哪些 semver 更新 会被 Channel 自动分发。通过 --disable-auto-update 在 Channel 上设置。

策略	阻止	允许	使用场景
无	无	任意目标 bundle 版本	默认；全自动更新
主版本	主版本号高于 version_build，例如 1.2.3 -> 2.0.0	主版本号相同，例如 1.2.3 -> 1.9.0 或 1.2.3 -> 1.2.4	防止破坏性变更影响旧版 native code
minor 版本	主版本号或次版本号不同 version_build，例如 1.2.3 -> 1.3.0	主版本号和次版本号相同，例如 1.2.3 -> 1.2.4	将更新限制在同一条 native minor 版本线内
patch 版本	主版本号、次版本号或修订号发生任何变化，例如 1.0.0 -> 1.0.1	仅后缀发生变化，而 MAJOR.MINOR.PATCH 保持完全一致，例如 1.0.0-beta.1 -> 1.0.0-beta.2 或 1.0.0+build.1 -> 1.0.0+build.2	最严格模式：核心版本不变
元数据	缺失 min_update_version，或 version_build 其下方	目标 bundle，其 min_update_version 小于或等于 version_build	针对每个 bundle 的自定义兼容性规则

这些检查会将目标 bundle 与以如下形式发送的原生基准进行对比 version_build，而不是与以如下形式发送的当前已安装的已下载 bundle 进行对比 version_name.

npx @capgo/cli channel set production --disable-auto-update major

注意

patch 以及 metadata 需要仔细配置。参见 CLI 命令 以及 版本定向 详情。

分发类型

如何 传输 bundle 到设备。

类型	描述	使用场景
全量 bundle	下载整个 JS bundle	首次安装、较大变更，或 delta 不可用时
增量	仅下载变更的文件	大多数更新；更快、更省带宽

# Full bundle (default)
npx @capgo/cli bundle upload --channel production

# Delta updates
npx @capgo/cli bundle upload --channel production --delta

提示

使用 instant apply 模式时（atInstall, onLaunch，或 always），请启用 增量更新 以尽量缩短下载时间并提升用户体验。

快速参考

类别	类型
应用时机	off, atBackground, atInstall, onLaunch, always, onlyDownload
延迟条件	date, background, nativeVersion, kill
版本屏蔽	none, major, minor, patch, metadata
交付方式	全量 Bundle、增量

相关

• 更新行为 — 配置应用时机与延迟
• 版本定向 — 基于 Channel 的版本路由
• 增量更新 — 仅下载变更文件
• 通道 — Channel 配置与优先级

继续阅读 Update Types

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