从 Capawesome Cloud 迁移到 Capgo

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

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

概述

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

使用 Capgo 只需安装我们的插件并调用 Everything else—channels、捆绑包清理、回滚、分析和 Capgo 自动化—is handled natively。下面的部分逐步介绍每个任务。 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()` (唯一必需的钩子)

旧的工作流程引入了自定义监听器（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如何处理它们

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 步 – 部署包

, __CAPGO_KEEP_0__ 提供了一个类似的 __CAPGO_KEEP_1__ 工作流程，您还可以完全自动化部署过程。 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个月
实时延迟指标在 status.capgo.app/history.

迁移时间线

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

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

Capgo 支持

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

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