从 Capawesome Cloud 迁移到 Capgo

复制一个包含安装步骤和此插件的完整Markdown指南的设置提示。

⚡️ Capgo 自动化频道、打包清理、回滚、分析和 CLI 原生上传。使用本指南执行迁移所需的最少步骤，并可选地重建任何您仍需要的自定义行为。

Overview

Gather your existing Capawesome Cloud configuration (App ID, channels, signing keys, CLI tokens) so you can archive or audit it later.
Install the Capgo plugin, remove the Capawesome SDK, and call CapacitorUpdater.notifyAppReady().
Configure optional behaviour (manual downloads, pinning bundles, reloads) if you rely on those flows today.

With Capgo you only need to install our plugin and call CapacitorUpdater.notifyAppReady(). Everything else—channels, bundle cleanup, rollbacks, analytics, and CLI automation—is handled natively. The sections below walk through each task directly.

开始之前

确保您的项目已经使用 Capacitor 5 或更高版本。
如果您计划从 CI/CD 推送捆绑包，请安装 Capgo 的 CLI (npm install -g @capgo/cli)。

步骤 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 控制台或 API 来管理。您只需要覆盖这些键，如果您想与 Capgo 的默认行为不同。

配置快速参考

Capawesome 选项	Capgo 等效项	您需要设置它吗？
`appId`	从 Capgo 控制台创建项目后，您可以从中获取	只在使用多个项目时才会生效
`defaultChannel`	API 中的频道规则管理	可选，多数团队在服务器端设置
`autoDeleteBundles`	`autoDeletePrevious: true` (默认值)	已启用
`publicKey`	在 Capgo 控制台中管理	只在手动轮换密钥时才会生效
`maxVersions` /保留	保留策略	在 Capgo 中集中配置（默认 1 个月，最大 24 个月）

步骤 3：调用 `notifyAppReady()` (唯一必需的钩子)

旧的工作流程引入了自定义监听器（，隐藏启动屏幕等）。__CAPGO_KEEP_0__ 原生执行这些步骤。您必须调用的唯一__CAPGO_KEEP_1__是：checkForUpdates(), retryDownload(), hiding the splash screen, etc.). Capgo performs those steps natively. The only API you must call is:

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

CapacitorUpdater.notifyAppReady()

这就是它—Capgo 原生处理后台检查、启动屏幕可见性和回滚。

That’s it—Capgo handles background checks, splash visibility, and rollbacks natively.

复制到剪贴板

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 调用（大部分可选）

In Capgo you normally let the auto-updater run; manual APIs remain available if you want full control.

__CAPGO_KEEP_0__	Capgo等价物	您需要吗?
`LiveUpdate.fetchLatestBundle()`	`CapacitorUpdater.getLatest()`	只有在实现自己的下载工作流程时才会
`LiveUpdate.downloadBundle()`	`CapacitorUpdater.download()`	可选：本地自动更新已经下载
`LiveUpdate.setNextBundle()`	`CapacitorUpdater.next()`	可选：仪表板固定包自动下载
`LiveUpdate.reload()`	`CapacitorUpdater.reload()`	可选；Capgo强制要求必须的包后 `notifyAppReady()`
`LiveUpdate.getCurrentBundle()`	`CapacitorUpdater.current()`	可选诊断

如果您坚持使用本地自动更新行为，则可以删除Capawesome JavaScript

手动控制示例

下载最新的包

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')
  }
}

设置下一个捆绑包

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' })
}

立即应用下载的捆绑包

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：默认启用（，）无需额外的__CAPGO_KEEP_0__。autoUpdate: true). No additional code required.

始终最新版

上一个工作流程: 添加一个 App.resume 监听器，调用 download, 然后 set.
Capgo: 后台自动更新已经在恢复后执行检查。您只需要手动监听器，如果您想自定义间隔。

可选：手动恢复检查

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 })
    }
  }
})

强制更新

上一个工作流程: wire prompt logic and enforce reload.
Capgo: mark the bundle as “强制” in the dashboard, then listen for the majorAvailable event (emitted after notifyAppReady()) to require users to upgrade inside your app.

第 6 步 – 部署捆绑包

如果您以前依赖 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 自动跟踪捆绑包的健康状况，所以您也能获得：

设备级别的安装日志
自动保留（默认一个月）可配置限制至24个月
实时延迟指标在 status.capgo.app/history.

迁移时间线

设备清单和安装: 10分钟（npm install: 5分钟（
配置和准备Sanity检查notifyAppReady).
移除旧插件: 15 分钟（可选手动测试或监听器）。
首次部署: 10 分钟与 Capgo CLI 或 CI 集成。

在实践中团队在一个小时内完成。如果您提供 Capawesome 项目详细信息，我们甚至可以为您导入通道和设备列表。

Capgo 支持

迁移顾问: 预约一个会话在预约.capgo.app/demo.
社区: 加入的 Capgo Discord.
问题跟踪器: github.com/Cap-go/capacitor-updater/issues.

Capgo 是为长期可靠性而设计的：原生delta更新、加密包、自动回滚和不需要自定义JavaScript的分析。您迁移后可以删除繁琐的维护性胶水，让平台自动运行更新。