跳转至正文
直接更新

用户打开 App 时即显示最新版本

默认情况下，live update 在下载后仅运行一个会话。而 Direct Update 模式会在启动时、在 Splash Screen 之后直接应用更新，确保用户看到的第一个界面就是新版本。

autoUpdate：atInstall、onLaunch 或 always
启动屏会保持显示，直到更新就绪
Delta 下载缩短等待时间

面临的问题

后台更新会延迟一个会话生效

在默认模式下会发生什么

1

用户打开 App

App 使用现有的 bundle 启动。更新程序会检查新版本并在后台进行 download。

2

当前会话运行旧版本

在本次会话剩余的时间里，用户运行的是你在修复前安装的 code。

3

更新在下次恢复时生效

当用户退出 App 时，更新程序会安装新的 bundle。用户在下次打开 App 时才能看到更新。

对于大多数发布，这是合理的权衡。但如果你希望在 upload 后的第一个会话中就运行新的 code，请使用 direct update 模式。

当首个会话至关重要时

支付或登录流程出现故障

在修复生效前，打开 App 的用户不应再次遇到故障界面。

Web 层安全修复

你希望修复后的 JavaScript 从启动时就开始运行，而不是等到下次会话。

时效性变更

条款、通知或活动内容必须在用户看到的首屏上保持最新。

解决方案

Direct Update 模式会带来哪些变化

更新器会在启动时检查，此时 Splash Screen 保持显示。如果有新 bundle，它会在 Splash Screen 隐藏前完成下载并应用。

默认模式（atBackground）

1
用户打开 App
2
App 显示当前版本
3
更新在后台下载
4
更新在下次 resume 时应用

无需等待启动。用户在下一次启动时即可看到更新。

直接模式 (onLaunch)

1
用户打开 App，启动页（splash screen）保持显示
2
更新程序检查并下载变更文件
3
更新生效，启动页隐藏，展示新版本

用户在首屏即可看到新版本。下载期间，用户需在启动页等待。

更新行为文档

工作原理

如何配置直接更新

直接模式属于原生配置，因此需先通过应用商店构建版本。之后，每一次 live update 都会遵循此配置。相关命令请参考 Capgo 文档。

  1. 添加启动页插件并选择模式

    安装 @capacitor/splash-screen，然后在 capacitor.config.ts 中设置 autoUpdate、autoSplashscreen 和 launchAutoHide。

    npm install @capacitor/splash-screen
npx cap sync

// capacitor.config.ts
plugins: {
  CapacitorUpdater: {
    autoUpdate: 'onLaunch', // or 'atInstall' / 'always'
    autoSplashscreen: true,
    keepUrlPathAfterReload: true,
  },
  SplashScreen: { launchAutoHide: false },
}
    Splash screen 处理

  2. 在 Store 版本中包含配置

    capacitor.config 会被编译进 Native Build，因此新模式会随您的下一个 Store 版本发布到达用户手中。Capgo Build 可以在云端生成它。

    npx @capgo/cli@latest build request --platform ios
npx @capgo/cli@latest build request --platform android
    Capgo Build 文档

  3. 以 Delta 方式上传 Bundle

    用户在启动时会等待下载，因此只需发送变更的文件。CLI 会检测即时应用模式并提示进行 Delta upload。

    npx @capgo/cli@latest bundle upload --channel production --delta
    Delta updates 文档

  4. 保持自动回滚开启

    应用启动后调用 notifyAppReady()。如果新 Bundle 启动失败，设备将自动回滚到上一个可用的版本。

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

await CapacitorUpdater.notifyAppReady()
    notifyAppReady() 文档

选择最适合您 App 的模式

Direct updates 是一种权衡：通过在启动时进行短暂等待，换取在首屏即展示新版本。

三种即时应用模式

在 capacitor.config.ts 中设置 autoUpdate。每种模式决定了用户等待时何时应用更新。

  • atInstall：仅在原生 App 首次安装或通过应用商店更新后执行
  • onLaunch：当 App 从终止状态启动时（冷启动）
  • 始终开启：每次进入前台时都会检查，即使应用正在运行中
更新器设置

3

autoUpdate 中的即时应用模式

Splash screen 处理

Direct 模式需要将 @capacitor/splash-screen 的 launchAutoHide 设置为 false，并将 autoSplashscreen 设置为 true。一旦更新应用完成，或者确认无需更新时，更新器会自动隐藏 splash screen。

  • 无需手动调用 SplashScreen.hide()
  • keepUrlPathAfterReload 可确保用户在 reload 后保持在同一路由
  • 如果需要在 splash 隐藏后执行额外操作，请监听 appReady
Splash screen 处理

自动管理 Splashscreen

每种 Direct 模式均需配置

需要权衡的方案

用户在启动时等待下载，而通过始终更新，可以在应用使用过程中进行热重载。两者兼顾。

  • 使用 --delta 进行 upload，仅下载变更文件
  • 保存并恢复应用状态，确保 reload 不会丢失用户进度
  • 如果允许单次会话延迟，请保持默认模式
Delta 更新文档

--delta

建议在每次 direct update upload 时使用

何时使用 direct updates

当当前会话必须运行新的 code 时，请使用 direct 模式。其他情况请保持默认。

修复严重 Bug

支付、登录或数据相关的 Bug，无法容忍再使用一个会话的旧版 code。

首次运行 onboarding

atInstall 会在全新安装或应用商店更新后立即应用最新的 bundle，确保新用户直接进入当前的 onboarding 流程。

时效性内容

用户打开 App 时必须保持最新的活动页面、通知或服务条款。

安全补丁

应在启动时生效的 Web 层安全修复。若涉及 native code 的修复，仍需通过应用商店发布。

常规发布

样式微调和小功能通常无需等待应用商店审核。默认模式会在下次启动会话时应用这些更改。

长时间运行的应用

配合 always 模式，周期性检查（默认每 10 分钟一次）可以在 App 运行期间应用更新。请在依赖此功能前先保存应用状态。

缩短启动等待时间

启动时的等待时间由检查更新和下载组成。Delta updates 可确保仅下载发生变化的文件。

~50ms

典型的 API 延迟

增量更新

仅下载已更改的文件

10 亿+

每月下发的更新数

按团队类型的解决方案

找到符合你团队需求的解决方案

企业版

支持多应用、多团队部署

初创公司

快速交付，告别繁琐流程

独立开发者

14 天免费试用，支持 CLI upload

代理机构

管理多个客户端 App

使用 Capacitor 构建的应用

面向公众的信息类 App 需要即时内容修复

应急、医疗和政务类 App 无法忍受因修复损坏的清单、资源链接或特定位置通知而等待数日。通过 Direct updates，Web 层可以在修复方案获批后立即生效。

FEMA App 图标 天气

FEMA

在内容微小错误可能引发紧急情况的场景下，提供应急指导。

Google Play 安装量
160万
应用商店评分
4.0
Conecte SUS 应用图标 医疗

连接 SUS

在需要快速发布经审核的内容变更的健康记录与指导界面中使用。

Google Play 安装量
27.7M
应用商店评分
4.6
e-Título 应用图标 社交

e-Título

在多设备环境下，需要版本安全的引导来保障公民身份认证流程。

Google Play 安装量
54.9M
应用商店评分
4.8

客户证言

使用 Capgo 发布应用的团队怎么说

5.0/5 开发团队评分 9,400+ 团队 查看评价

Kapil

NuTriQ 创始人

“无需等待完整的 App Store 审核周期，就能即时推送生产环境的 OTA 更新，这是巨大的运营优势。”

Sergiu S 的肖像

Sergiu S

drivolino GmbH 首席开发者

“Capgo Capacitor Updater plugin 彻底改变了我们发布更新的方式。过去要花几天，现在只要几分钟。”

Luis Dominguez 的肖像

Luis Dominguez

谁付费，Anirol

“自从开始使用 Capgo，一切都变快了，我也能在不耽误日常生活的情况下，把应得的时间留给用户。”

常见问题

关于 Direct Updates 的常见问题

何时使用、如何配置，以及上线时的费用。

我们应该使用 Direct Updates 还是默认的后台模式？

大多数发布使用默认模式：启动时无需等待，用户会在下一个会话拿到更新。如果上传后开始的会话必须运行新的 code，例如结账流程故障或 Web 层安全修复，就用 Direct 模式。

更新行为文档

atInstall、onLaunch 和 always 之间有什么区别？

atInstall 仅在原生应用全新安装或商店更新后立即应用更新，之后与默认模式一致。onLaunch 在应用从被杀死状态启动时立即应用。always 会在每次进入前台时检查，并在下载完成后立即应用，即使用户正在使用应用。

Updater 设置

为什么需要 Splash Screen 插件？

Direct 模式会在用户等待时应用更新。如果没有 @capacitor/splash-screen、autoSplashscreen: true 和 launchAutoHide: false，用户在重新加载前可能会看到闪烁或旧的 UI。有了这些配置，Splash Screen 会一直显示，直到更新已应用，或 Updater 确认无需更新。

Splash Screen 处理

我们可以通过 live update 开启 Direct Updates 吗？

不再使用 autoUpdate，而是通过 capacitor.config 进行配置，该配置会在构建时读取到原生应用中。请在应用商店发布新版本以包含此设置。之后，每次 live update 都会遵循新的模式。

Native 兼容性文档

我们的配置使用的是 directUpdate，这还受支持吗？

directUpdate 已弃用，但仍会被检测到。其值与 atInstall、onLaunch 和 always 等 autoUpdate 模式相匹配。请在下次 Native Build 发布时将设置迁移至 autoUpdate。

Updater 设置

让您的下一个修复版本即刻上线

在试用期间，可以在测试构建中尝试 direct update 模式，并亲自测试您应用的启动等待时间。

14 天免费试用。无需信用卡。