跳转至正文
直接更新

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

默认情况下,live update 下载后只运行一个会话。Direct update 模式则会在启动时、在 Splash Screen 背后应用更新,因此用户看到的第一个界面就已经是新版本。

autoUpdate:atInstall、onLaunch 或 always
启动屏会一直显示,直到更新就绪
Delta 下载缩短等待时间

问题

后台更新晚一个会话才生效

默认模式下会发生什么

1

用户打开 App

App 会从现有 bundle 启动。更新器会在后台检查新版本并下载。

2

当前会话运行的是当前版本

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

3

更新会在下次 Resume 时应用

当用户退出 App 时,更新器会安装新的 bundle。用户下次打开 App 时才会看到。

对于大多数发布,这是合理的取舍。如果上传后启动的会话必须运行新的 code,请使用 direct update 模式。

当首个会话至关重要时

支付或登录流程故障

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

Web 层安全修复

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

时效性变更

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

解决方案

Direct Update 模式会带来哪些变化

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

默认模式 (atBackground)

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

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

直接模式 (onLaunch)

1
用户打开 App,启动页保持显示
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. 在商店构建中发布配置

    capacitor.config 会被编译进原生应用,因此新模式会随下一次商店发布到达用户。Capgo Build 可以在云端生成它。

    npx @capgo/cli@latest build request --platform ios
    npx @capgo/cli@latest build request --platform android
    Capgo 构建文档
  3. 以增量方式上传 bundle

    用户在启动时要等待下载,所以只发送变更的文件。CLI 会检测即时应用模式并提示进行增量上传。

    npx @capgo/cli@latest bundle upload --channel production --delta
    Delta 更新文档
  4. 保持自动回滚开启

    应用启动后调用 notifyAppReady()。如果新 bundle 启动失败,设备会回退到上一个正常工作的版本。

    import { CapacitorUpdater } from '@capgo/capacitor-updater'
    
    await CapacitorUpdater.notifyAppReady()
    notifyAppReady() 文档

选择最适合您 App 的模式

Direct updates 是一种取舍:启动时短暂等待,换取首屏即为新版本。

三种即时生效模式

在 capacitor.config.ts 中设置 autoUpdate。每种模式决定用户在等待期间更新何时可以生效。

  • atInstall:仅在原生 App 全新安装或应用商店更新后生效
  • onLaunch:App 从被终止状态启动时(冷启动)
  • always:每次应用进入前台时都会检查,即使应用当前处于打开状态
Updater 设置

3

autoUpdate 中的即时应用模式

Splash Screen 处理

Direct 模式需要 @capacitor/splash-screen 将 launchAutoHide 设置为 false,并将 autoSplashscreen 设置为 true。更新器会在更新应用后,或确定无需更新时隐藏启动画面。

  • 无需手动调用 SplashScreen.hide()
  • keepUrlPathAfterReload 在重新加载后保持用户停留在相同路由
  • 如果需要在启动画面隐藏后执行额外操作,请监听 appReady
Splash Screen 处理

autoSplashscreen

所有 Direct 模式的必需项

需要规划的权衡

用户会在启动时等待下载,而使用 always 更新时,可以在应用使用中重新加载。两种方式都要考虑。

  • 使用 --delta 上传,只下载变更文件
  • 保存并恢复应用状态,让重新加载不会丢失用户进度
  • 如果延迟一个会话可以接受,就保持默认模式
Delta 更新文档

--delta

建议每次 direct update 上传都使用

何时使用 direct updates

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

关键 Bug 修复

支付、登录或数据 Bug,旧版 code 再多跑一个会话都无法接受。

首次启动 onboarding

atInstall 会在全新安装或商店更新后立即应用最新 bundle,让新用户从你当前的 onboarding 开始。

时效性内容

活动页面、公告或条款必须在用户打开 App 时保持最新。

安全补丁

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

常规发布

样式微调和小功能通常不值得在启动时等待。默认模式会在下一次会话时应用它们。

长时间运行的应用

配合 always 模式,定期检查(默认每 10 分钟一次)可以在 App 打开时应用更新。依赖此功能前请先保存状态。

缩短启动等待时间

启动时的等待时间来自更新检查和下载。Delta updates 只下载发生变化的文件。

~50ms

API 的典型延迟

增量

仅下载变更的文件

10 亿+

每月交付的更新次数

使用 Capacitor 构建的应用

公共信息应用急需内容修复

应急、医疗和政务类应用不能等上几天才修正出错的清单、资源链接或按地点发布的通知。通过 Direct updates,Web 层可以在修复获批后立即更新。

FEMA 应用图标 天气

FEMA

应急指导中,小内容错误也可能变成紧急问题。

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

连接 SUS

医疗记录与指导界面,已审核的文案变更需要快速发布。

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

电子标题

跨设备场景下,版本安全引导至关重要的公民身份工作流。

Google Play 安装量
5490万
应用商店评分
4.8

客户证言

使用 Capgo 交付的团队怎么说

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

Kapil

NuTriQ 创始人

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

Sergiu S 的肖像

Sergiu S

drivolino GmbH 首席开发者

“Capgo Capacitor Updater 插件彻底改变了我们的更新发布方式。过去需要几天的工作,现在只需几分钟。”

Luis Dominguez 的肖像

Luis Dominguez

谁付钱,谁说了算

“自从开始使用 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 已弃用但仍会被检测到。其值对应 autoUpdate 的 atInstall、onLaunch 和 always 模式。请在下一个原生版本中将设置迁移到 autoUpdate。

Updater 设置

将下一个修复方案置于首屏

在试用期间,在测试构建中尝试直接更新模式,并测量您自己应用的启动等待时间。

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