从 Capawesome Cloud 迁移到 Capgo

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

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

概述

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

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

开始之前

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

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

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

这是唯一必须交换的内容。 Capgo 的本机 code 附带了插件；不需要额外的 JavaScript 助手。

步骤 2 – 最小配置

之前的设置需要映射 dozens 个选项在 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 的默认值不同。

配置快速参考

__CAPGO_KEEP_0__ 等效项	Capgo equivalent	从 __CAPGO_KEEP_0__ 控制台中获取，创建项目后
`appId`	Taken from the Capgo dashboard once you create a project	在控制台/ __CAPGO_KEEP_0__ 中管理的频道规则
`defaultChannel`	Channel rules managed in the dashboard/API	Optional; most teams set this server-side
`autoDeleteBundles`	`autoDeletePrevious: true` (default)	已经启用
`publicKey`	在Capgo控制台中管理	仅当您手动轮换密钥时
`maxVersions` /保留	捆绑保留策略	在Capgo中集中配置(默认1个月，最大24个月)

步骤3 – Call `notifyAppReady()` （唯一必需的钩子）

旧的工作流程引入了自定义监听器（checkForUpdates(), retryDownload()隐藏启动屏幕等。 Capgo 会在本地执行这些步骤。您必须调用的唯一 API 是：

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

CapacitorUpdater.notifyAppReady()

这确认应用程序已成功启动。如果确认信息从未到达，Capgo 将自动回滚捆绑包—无需额外的 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()`	可选：仪表板自动固定捆绑
`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 如何处理它们

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

背景更新

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

始终最新

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

Optional: 手动恢复检查

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

强制更新

之前的工作流: 连接提示逻辑并强制重新加载。
Capgo: 在仪表盘中标记包裹为“强制”然后监听事件（在 majorAvailable ]之后发射）要求用户在应用程序内升级。 notifyAppReady()第 6 步 – 部署包裹

标题：第 6 步 – 部署包裹

, __CAPGO_KEEP_0__ 提供了类似的 __CAPGO_KEEP_1__ 工作流程，您还可以通过 __CAPGO_KEEP_2__ 完全自动化部署。 capawesome live-update deploy, Capgo offers a similar CLI workflow, and you can also automate deployments entirely 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

Because Capgo tracks bundle health automatically, you also get:

自动保留（默认为一个月）可配置的限制至 24 个月。
Step 6 – Deploying bundles
实时延迟指标在 status.capgo.app/history.

迁移时间线

库存和安装: 10 分钟 (npm install, 删除旧插件).
配置和就绪: 5 分钟 (notifyAppReady).
sanity检查: 15 分钟 (可选手动测试或监听器).
首次部署: 10 分钟与 Capgo CLI 或 CI 集成。

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

Capgo 支持

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

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