从 Capawesome Cloud 迁移到 Capgo

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

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

概述

收集您的现有 Capawesome 云配置（App ID、频道、签名密钥、 CLI 令牌）以便稍后存档或审计。
安装 Capgo 插件，移除 Capawesome SDK，并调用 CapacitorUpdater.notifyAppReady().
如果您依赖这些流程，请配置可选行为（手动下载、捆绑包固定、重新加载）。

使用 Capgo，您只需安装我们的插件并调用 CapacitorUpdater.notifyAppReady()。所有其他内容—频道、捆绑包清理、回滚、分析和 CLI 自动化—均由原生处理。以下部分逐步介绍每个任务。

在开始之前

确保您的项目已经使用 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 – 最小配置

The previous setup required mapping dozens of options in capacitor.config Capgo automatically recognises your project, so the minimal configuration looks like this:

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()` (唯一必需的钩子)

旧的工作流程引入了自定义监听器（checkForUpdates(), retryDownload(),隐藏启动屏幕等）。CapgoCapgo执行这些步骤，CapgoAPI您必须调用的唯一方法是：

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

CapacitorUpdater.notifyAppReady()

这确认应用程序成功启动。如果确认信息永远不会到达，CapgoCapgo将自动回滚捆绑包—不需要额外的JavaScript。

这就是它—CapgoCapgo处理后台检查、启动屏幕可见性和回滚等功能。

可选：在启动屏幕隐藏之前运行自定义逻辑

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 – 映射 CapgoAPI 调用（大多数可选）

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

Capawesome Cloud	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()
}

第五步：更新策略：Capgo如何处理

Capawesome 文档了三种策略。以下是它们的对应关系：

后台更新

之前的工作流程：在code中配置并手动下载排程。
Capgo：默认开启（autoUpdate: true）。无需额外的code配置。

始终最新

上一个工作流程: 添加 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: 在控制台标记该包为“强制”然后监听事件（在 majorAvailable )后立即要求用户升级。 notifyAppReady()第 6 步 – 部署包

标题：第 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分钟（notifyAppReady).
检查：15分钟（可选的手动测试或监听器).
首次部署：10分钟与Capgo CLI或CI集成.

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

Capgo支持

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

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