从 Capawesome Cloud 迁移到 Capgo

复制包含安装步骤和该插件完整 Markdown 指南的配置 prompt。

⚡️ Capgo 原生自动处理 channels、bundle 清理、回滚、analytics 和 CLI 上传。请按本指南完成迁移所需的最少步骤，并按需重建你仍然需要的自定义行为。

概览

收集现有 Capawesome Cloud 配置（App ID、channels、签名密钥、CLI token），以便之后归档或审计。
安装 Capgo 插件，移除 Capawesome SDK，并调用 CapacitorUpdater.notifyAppReady().
如果你目前依赖这些流程，请配置可选行为（手动下载、固定 bundle、重新加载）。

使用 Capgo 时，你只需安装我们的插件并调用 CapacitorUpdater.notifyAppReady()。其余一切——channels、bundle 清理、回滚、analytics 和 CLI 自动化——都以原生方式处理。下面各节会直接逐一介绍每项任务。

开始之前

请确保你的项目已在使用 Capacitor 5 或更高版本。
安装 Capgo CLI（npm install -g @capgo/cli）如果你计划从 CI/CD 推送 bundle。

步骤 1 – 安装 Capgo 并移除 Capawesome SDK

npm uninstall @capawesome/capacitor-live-update
npm install @capgo/capacitor-updater
npx cap sync

这是唯一必须替换的部分。Capgo 的原生 code 随插件提供，无需额外的 JavaScript 辅助函数。

步骤 2 – 最小化配置

之前的设置需要在 capacitor.config. Capgo 会自动识别您的项目，因此最小配置如下：

import { CapacitorConfig } from '@capacitor/cli'

const config: CapacitorConfig = {
  plugins: {
    CapacitorUpdater: {
      autoUpdate: true,
      autoDeletePrevious: true,
      periodCheckDelay: 10 * 60 * 1000, // optional: check every 10 minutes
    },
  },
}

export default config

Capawesome 列为手动标志的所有内容（defaultChannel, autoDeleteBundles保留策略等）均可通过 Capgo dashboard 或 API 管理。只有当你需要的行为与 Capgo 的默认行为不同时，才需要覆盖这些键。

配置速查

Capawesome 选项	Capgo 对应项	需要设置吗？
`appId`	创建项目后从 Capgo dashboard 获取	仅当你在同一个 binary 中使用多个项目时
`defaultChannel`	在 dashboard/API 中管理 Channel 规则	可选；大多数团队会在服务端设置
`autoDeleteBundles`	`autoDeletePrevious: true` （默认）	已启用
`publicKey`	在 Capgo 控制台中管理	仅当手动轮换密钥时
`maxVersions` / 保留	Bundle 保留策略	在 Capgo 中集中配置（默认 1 个月，最长 24 个月）

步骤 3 – 调用 `notifyAppReady()` （唯一必需的 hook）

旧的工作流引入了自定义监听器（checkForUpdates(), retryDownload()隐藏 splash screen 等）。Capgo 会以原生方式执行这些步骤。唯一必须调用的 API 是：

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

CapacitorUpdater.notifyAppReady()

这确认应用已成功启动。如果未收到确认，Capgo 会自动回滚 bundle——无需额外的 JavaScript。

就这样——Capgo 原生处理后台检查、启动画面可见性和回滚。

可选：在启动画面隐藏前运行自定义逻辑

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

CapacitorUpdater.addListener('appReady', () => {
  // Run diagnostics or logging if you need to
  SplashScreen.hide()
})

CapacitorUpdater.notifyAppReady()

步骤 4 – 映射 API 调用（大多可选）

在 Capgo 中，通常让自动更新器运行；如需完全控制，手动 API 仍然可用。

Capawesome Cloud	Capgo 对应项	需要吗？
`LiveUpdate.fetchLatestBundle()`	`CapacitorUpdater.getLatest()`	仅在实现自定义下载流程时需要
`LiveUpdate.downloadBundle()`	`CapacitorUpdater.download()`	可选：原生自动更新已负责下载
`LiveUpdate.setNextBundle()`	`CapacitorUpdater.next()`	可选：dashboard 会自动固定 bundle
`LiveUpdate.reload()`	`CapacitorUpdater.reload()`	可选；随后由 Capgo 强制执行强制 bundle `notifyAppReady()`
`LiveUpdate.getCurrentBundle()`	`CapacitorUpdater.current()`	可选诊断信息

如果你继续使用原生自动更新行为，可以完全删除 Capawesome 的 JavaScript。

手动控制示例

下载最新 bundle

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

const downloadUpdate = async () => {
  const latest = await CapacitorUpdater.getLatest()
  if (latest?.url) {
    const bundle = await CapacitorUpdater.download({
      url: latest.url,
      version: latest.version,
    })
    console.log('Bundle downloaded', bundle?.id)
  }
}

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

const downloadUpdate = async () => {
  const result = await LiveUpdate.fetchLatestBundle()
  if (result.downloadUrl) {
    await LiveUpdate.downloadBundle({
      bundleId: result.bundleId,
      url: result.downloadUrl,
    })
    console.log('Bundle downloaded')
  }
}

设置下一个 bundle

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

const setNextBundle = async () => {
  await CapacitorUpdater.next({ id: 'bundle-id-123' })
}

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

const setNextBundle = async () => {
  await LiveUpdate.setNextBundle({ bundleId: 'bundle-id-123' })
}

立即应用已下载的 bundle

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

const applyUpdate = async () => {
  await CapacitorUpdater.reload()
}

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

const applyUpdate = async () => {
  await LiveUpdate.reload()
}

第 5 步 – 更新策略：Capgo 如何处理这些策略

Capawesome 文档介绍了三种策略。以下是它们的对应方式：

后台更新

上一个工作流：在 code 中配置并手动安排下载。
Capgo：默认启用（autoUpdate: true）。无需额外的 code。

始终保持最新

上一个工作流：添加一个 App.resume 监听器、调用 download，然后 set.
Capgo：后台自动更新在 resume 后已经会执行检查。只有想自定义间隔时，才需要手动监听器。

可选：手动 resume 检查

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

App.addListener('resume', async () => {
  const latest = await CapacitorUpdater.getLatest()
  if (latest?.url) {
    const downloaded = await CapacitorUpdater.download({
      url: latest.url,
      version: latest.version,
    })
    if (downloaded) {
      await CapacitorUpdater.next({ id: downloaded.id })
    }
  }
})

强制更新

上一个工作流：接入 prompt 逻辑并强制重新加载。
Capgo：在 dashboard 中将 bundle 标记为“mandatory”，然后监听 majorAvailable 事件（在...之后触发 notifyAppReady()) 以要求用户在应用内升级。

第 6 步 – 部署 bundle

如果你之前依赖 capawesome live-update deploy，Capgo 提供类似的 CLI 工作流，你也可以完全通过 API 自动化部署。

# Authenticate once (stores a token in your CI environment)
capgo login

# Upload a new bundle (auto-detects platform/version)
capgo bundle upload --path dist --channel production

由于 Capgo 会自动跟踪 bundle 健康状态，你还能获得：

每次安装的设备级审计日志。
自动保留（默认一个月），上限可配置至 24 个月。
实时延迟指标： capgo.app/历史状态.

迁移时间线

清点与安装: 10 分钟 (npm install，移除旧插件)。
配置与就绪检查: 5 分钟 (notifyAppReady).
基本检查: 15 分钟 (可选的手动测试或监听器)。
首次部署: 使用 Capgo CLI 或 CI 集成需 10 分钟。

实际中，团队通常不到一小时就能完成。如果你提供 Capawesome 项目详情，我们甚至可以帮你导入 channels 和设备列表。

Capgo 支持

迁移顾问服务：在以下地址预约 book.capgo.app/demo.
社区：加入 Capgo Discord.
问题追踪器: github.com/Cap-go/capacitor-updater/issues.

Capgo 专为长期可靠性而设计：原生增量更新、加密 bundle、自动回滚，以及无需自定义 JavaScript 的分析功能。迁移后，你可以删掉那些维护繁重的胶水代码，让平台自动执行更新。

继续阅读：从 Capawesome Cloud 迁移至 Capgo

如果你正在使用 从 Capawesome Cloud 迁移到 Capgo 规划 CI/CD 自动化，并将其与 Capgo CI/CD 集成用于 Capgo CI/CD 中的产品工作流， Capgo Native Build 用于 Capgo Native Builds 中的产品工作流， Capgo 集成用于 Capgo 集成中的产品工作流， CI/CD 集成了解 CI/CD 集成的实现细节，以及 GitHub Actions 集成有关 GitHub Actions 集成的实现细节。