热更新（Live Updates）

热更新（Live Updates），也称为 OTA（Over-the-Air）更新或热代码推送，是一种无需经过应用商店审核流程即可推送更新的方式。这对于 Bug 修复或不需要完整发版的小更新特别有用。

Capgo

Capgo 提供了开源的 @capgo/capacitor-updater 插件。它同时支持免费的自托管流程和托管的云服务。

安装

进入 Capacitor 项目目录并安装插件：

cd src-capacitor

pnpm add @capgo/capacitor-updater

然后同步原生项目：

npx cap sync

配置

对于自托管的手动更新流程，在 capacitor.config 文件中禁用自动更新。这样可以让更新决策留在应用代码中，同时你在自己的基础设施上托管更新包和元数据。

import { defineCapacitorConfig } from '@quasar/app-vite/capacitor'

export default defineCapacitorConfig({
  plugins: {
    CapacitorUpdater: {
      autoUpdate: 'off'
    }
  }
})

配置插件后，再次同步 Capacitor 项目：

npx cap sync

使用方法

在应用成功加载后调用 notifyAppReady()。这会确认当前包正常工作，防止不必要的回滚。

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

await CapacitorUpdater.notifyAppReady()

在手动模式下，你的应用会检查自己的更新端点，下载更新包，并决定何时激活它。以下示例假设端点返回 version、url 和 checksum 字段：

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

const sync = async () => {
  const response = await fetch('https://example.com/api/mobile-update')

  if (!response.ok) return

  const update = await response.json()

  if (!update?.url || !update?.version || !update?.checksum) return

  const bundle = await CapacitorUpdater.download({
    url: update.url,
    version: update.version,
    checksum: update.checksum
  })

  await CapacitorUpdater.next({ id: bundle.id })
}

下载的更新包将在下次应用启动时生效。如果想在你自己的确认界面或维护页面后立即应用，可以重新加载应用：

await CapacitorUpdater.reload()

发布更新

回到 Quasar 项目根目录，创建 Capacitor Web 包：

quasar build -m capacitor -T [android|ios] --skip-pkg

然后使用 Capgo CLI 从 src-capacitor/www 创建 bundle 压缩包：

npx @capgo/cli@latest bundle zip [appId] --path src-capacitor/www --json

将生成的压缩包上传到你的 HTTPS 服务器或存储桶。你的更新端点应返回其元数据：

{
  "version": "1.0.1",
  "url": "https://example.com/mobile-updates/1.0.1.zip",
  "checksum": "sha256-checksum-returned-by-the-capgo-cli"
}

将 [appId] 替换为 Capacitor 配置中的应用 ID。压缩包的根目录必须包含 index.html。Capgo CLI 会处理预期的 bundle 结构并返回用于验证下载的校验和。详见 Capgo 自托管文档了解完整的服务器端工作流程。

如果你不想自己维护更新 API、存储、通道、回滚和分析，同一个插件也可以使用托管的 Capgo Cloud 服务。

Capawesome Cloud

Capawesome Live Update 通过 Capawesome Cloud 提供托管的更新工作流程。

安装

要在 Quasar Capacitor 应用中启用热更新，需要安装 @capawesome/capacitor-live-update 插件。首先，进入 Capacitor 项目目录：

cd src-capacitor

然后安装插件：

pnpm add @capawesome/capacitor-live-update

安装完成后，需要将更改同步到原生项目：

npx cap sync

配置

接下来，需要配置该插件以配合 Capawesome Cloud 使用。

App ID

为了让应用能够向 Capawesome Cloud 标识自己，需要在 capacitor.config 文件中设置 appId。为此，你需要在 Capawesome Cloud 控制台 上创建一个应用并获取 App ID。

import { defineCapacitorConfig } from '@quasar/app-vite/capacitor'

export default defineCapacitorConfig({
  plugins: {
    LiveUpdate: {
      appId: '00000000-0000-0000-0000-000000000000'
    }
  }
})

将 00000000-0000-0000-0000-000000000000 替换为你在 Capawesome Cloud 控制台上获取的实际 App ID。

配置好 App ID 后，再次同步 Capacitor 项目：

npx cap sync

使用方法

Live Update 插件最基本的用法是在应用启动时调用 sync(...) 方法。该方法会检查是否有可用更新，如果有则下载更新，并将其设置为下次加载时使用的 bundle。随后你可以调用 reload() 方法来立即应用更新。如果不调用 reload()，新的 bundle 将在下次启动应用时生效。

import { LiveUpdate } from '@capawesome/capacitor-live-update'

const sync = async () => {
  const result = await LiveUpdate.sync()
  if (result.nextBundleId) {
    await LiveUpdate.reload()
  }
}

发布更新

要发布你的第一个更新，需要在 Capawesome Cloud 上创建一个 bundle。为此，你需要一个 bundle 产物。Bundle 产物就是 Web 应用的构建输出。在 Quasar 中，对应的是 src-capacitor/www 目录。你可以运行以下命令来生成 bundle 产物：

quasar build -m capacitor -T [android|ios] --skip-pkg

这会在 src-capacitor/www 目录下生成 Web 应用的构建输出。然后你可以使用 Capawesome CLI 将该目录上传到 Capawesome Cloud。

安装 Capawesome CLI：

pnpm add -g @capawesome/cli

安装 Capawesome CLI 后，登录你的 Capawesome Cloud 账户并按照提示操作：

capawesome login

登录成功后，运行以下命令来创建 bundle：

capawesome apps:bundles:create --path src-capacitor/www

恭喜！你已经成功发布了第一个热更新。现在可以在设备或模拟器上运行应用来测试效果。应用会自动检查并应用可用的更新。 欢迎查阅 Live Update 插件的完整文档，了解更多功能。