从 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 – 最小配置

上一个设置需要映射数十个选项在 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.

Section titled “Step 3 – Call notifyAppReady() (the only required hook)”	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: 默认启用（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: 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 工作流程，您还可以完全自动化部署 via 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).
sanity: 15 分钟（可选的手动测试或监听器）。
首次部署: 10 分钟与 Capgo CLI 或 CI 集成。

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

Capgo 支持

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

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