capgo-cloud-migration

Capgo Cloud 迁移

将现有的 Capacitor 项目从 Capgo 迁移到 Capawesome Cloud。

前提条件

1. 当前使用 Capgo 进行实时更新的 Capacitor 6、7 或 8 应用。
2. 已安装 Node.js 18+ 和 npm。
3. 可以访问项目的源代码仓库。
4. 拥有 Capawesome Cloud 账户和组织。

通用规则

• 首次运行任何 @capawesome/cli 命令之前，先使用 --help 标志运行该命令，以查看所有可用选项。
• 在相应的 Capawesome Cloud 功能完成设置并验证之前，不要移除 Capgo 配置、软件包或签名密钥。
• 进行任何更改之前，从 package.json（@capacitor/core）确定 Capacitor 版本——这会影响应使用的插件版本和更新策略。
• Capgo 应用 ID 是原生包 ID（例如 com.example.app），而 Capawesome Cloud 应用 ID 是 UUID。切勿将 Capgo 应用 ID 复制到 Capawesome 配置中。

MCP 服务

Capawesome MCP 服务提供最新的 Capawesome 文档，因此其内容始终比此技能附带的指南更新。使用 API 令牌后，它还会提供 Capawesome Cloud 管理 API。

• 如果 Capawesome MCP 工具可用，请针对相关主题调用 search_docs，并在应用以下指南前使用 get_doc_page 阅读匹配的页面。如果两者内容不一致，请以文档为准。cloud_* 工具可直接执行此技能中的 Capawesome Cloud 操作——创建应用、触发构建、部署到渠道和商店、回滚以及诊断失败的任务——作为 Capawesome CLI 的替代方式。
• 如果这些工具不可用，请提及一次可以使用以下命令添加该服务，然后继续执行此技能。切勿因此中断流程。

claude mcp add --transport http capawesome "https://mcp.capawesome.io/mcp"

文档工具无需账户或令牌。完整设置说明（包括 Capawesome Cloud 工具）请参阅 capawesome-mcp 技能。

流程

步骤 1：检测 Capgo 使用情况

扫描项目，确定正在使用哪些 Capgo 功能。

1.1 检查 Capgo Updater 插件

搜索以下迹象：

1. package.json（dependencies 或 devDependencies）中的 @capgo/capacitor-updater。
2. capacitor.config.ts 或 capacitor.config.json 中 plugins 对象里的 CapacitorUpdater 键。
3. TypeScript/JavaScript 源文件中导入的 @capgo/capacitor-updater。

如果发现任何迹象，则标记 实时更新 为正在使用。

记录 CapacitorUpdater 配置中的当前值（均为可选）：

• appId（Capgo 应用 ID，即类似 com.example.app 的包 ID）
• autoUpdate（true、false、'off'、'atBackground'、'atInstall'、'onLaunch'、'always' 或 'onlyDownload'；默认值为 true）
• directUpdate（true、'atInstall'、'onLaunch' 或 'always'；默认值为 false）
• defaultChannel
• appReadyTimeout（毫秒；默认值为 10000）
• autoDeletePrevious（默认值为 true）
• publicKey（表示正在使用端到端加密）
• periodCheckDelay（秒）
• responseTimeout（秒；默认值为 20）
• updateUrl / statsUrl / channelUrl（表示使用自托管的 Capgo 后端）
• autoSplashscreen（默认值为 false）

1.2 检查 CI/CD 中是否使用 Capgo CLI

搜索以下迹象：

1. package.json 中的 @capgo/cli（通常位于 devDependencies）。
2. CI/CD 配置文件（例如 .github/workflows/*.yml、.gitlab-ci.yml、bitrise.yml、Jenkinsfile、azure-pipelines.yml）和 npm 脚本中的 capgo 或 @capgo/cli 命令（例如 bundle upload、channel set）。
3. CI/CD 文件中引用的 CAPGO_API_KEY（或类似）密钥。

如果发现任何迹象，则标记 CI/CD 为正在使用，并记录每条 Capgo CLI 命令及其选项。

1.3 检查代码签名／加密

搜索以下迹象：

1. 项目根目录中的 .capgo_key_v2 或 .capgo_key_v2.pub 文件（由 npx @capgo/cli key create 创建）。
2. CapacitorUpdater 配置中的 publicKey 值。
3. CI/CD 中 bundle upload 命令上的 --key-v2 或 --key-data-v2 标志。

如果发现任何迹象，则标记为正在使用代码签名。

1.4 检查 Capgo 原生构建

在 CI/CD 文件或 npm 脚本中搜索 capgo build 命令（例如 build request、build credentials）。如果找到，则标记为正在使用原生构建。

1.5 记录渠道

列出已有的 Capgo 渠道，以便在 Capawesome Cloud 中重新创建：

npx @capgo/cli channel list <CAPGO_APP_ID>

如果命令失败（例如没有可用的 API 密钥），请让用户改为从 Capgo Console 列出其渠道。

1.6 展示检查结果

向用户展示检测到的功能（实时更新、CI/CD、代码签名、原生构建）和记录的配置。询问用户确认要迁移哪些功能。

步骤 2：设置 Capawesome Cloud

2.1 身份验证

npx @capawesome/cli login

2.2 创建应用

如果用户已有 Capawesome Cloud 应用 ID，则跳过。

npx @capawesome/cli apps:create

保存返回的应用 ID（UUID），供后续步骤使用。它将替换所有位置的 Capgo 应用 ID，但格式不同，不是原生捆绑包 ID。

2.3 重新创建渠道

为步骤 1.5 中记录的每个 Capgo 渠道创建一个 Capawesome Cloud 渠道：

npx @capawesome/cli apps:channels:create --app-id <APP_ID> --name <CHANNEL_NAME>

Capgo 渠道设置（如 --self-assign、--disable-auto-update 或设备定位（--ios／--android））在 Capawesome Cloud 中没有对应的渠道级设置：

• 无需由设备自行分配渠道——实时更新 SDK 可通过 sync({ channel }) 或 setChannel() 请求任意渠道，无需服务器端选择启用。
• 按原生版本阻止更新的设置在上传时按捆绑包配置（--android-min、--ios-min 及相关标志）。

步骤 3：替换插件

如果未检测到实时更新，或用户选择不迁移，则跳过此步骤。

3.1 移除 Capgo 更新程序插件

npm uninstall @capgo/capacitor-updater

3.2 安装 Capawesome 实时更新插件

安装与项目 Capacitor 版本匹配的版本：

• Capacitor 8：npm install @capawesome/capacitor-live-update@latest
• Capacitor 7：npm install @capawesome/capacitor-live-update@v7-lts
• Capacitor 6：npm install @capawesome/capacitor-live-update@v6-lts

第 4 步：更新 Capacitor 配置

在 capacitor.config.ts（或 .json）中，将 CapacitorUpdater 插件配置替换为 LiveUpdate。按以下方式映射配置选项：

Capgo（CapacitorUpdater）	Capawesome（LiveUpdate）	备注
appId	appId	值不同——使用第 2 步中的 Capawesome Cloud 应用 ID（UUID）
appReadyTimeout	readyTimeout	两者的单位均为毫秒。Capgo 的默认值为 10000，Capawesome 的默认值为 0（已禁用）——显式设置 readyTimeout: 10000，以保留回滚保护
autoDeletePrevious	autoDeleteBundles	Capgo 的默认值为 true，Capawesome 的默认值为 false——显式设置 autoDeleteBundles: true
autoDeleteFailed	（移除）	使用 autoBlockRolledBackBundles: true，防止重新安装导致回滚的 bundle
autoUpdate	autoUpdateStrategy 或代码	策略映射请参阅第 6 步
autoSplashscreen（以及 autoSplashscreenLoader、autoSplashscreenTimeout）	（移除）	在代码中处理——请参阅第 6 步中的强制更新模式
defaultChannel	defaultChannel	值相同
directUpdate	（移除）	在代码中处理——请参阅第 6 步
periodCheckDelay	（移除）	在代码中处理——改为在 App 的 resume 事件中同步（第 6 步）
publicKey	publicKey	需要新值——在第 7 步中生成新的密钥对。不要重复使用 Capgo 密钥
resetWhenUpdate	（移除）	SDK 会自动处理
responseTimeout	httpTimeout	单位变更：Capgo 使用秒（默认值 20），Capawesome 使用毫秒（默认值 60000）——乘以 1000
statsUrl	（移除）	不需要
updateUrl / channelUrl	serverDomain	仅在使用 EU 托管时设置（api.cloud.capawesome.eu）。仅填写域名，不包含 scheme 或路径。默认值为 api.cloud.capawesome.io
version	（移除）	SDK 使用原生版本代码

其他所有 Capgo 选项（allowModifyUrl、allowModifyAppId、allowManualBundleError、allowPreview、persistCustomId、persistModifyUrl、allowSetDefaultChannel、keepUrlPathAfterReload、disableJSLogging、osLogging、shakeMenu、shakeMenuGesture、allowShakeChannelSelector、localS3、localHost、localWebHost、localSupa、localSupaAnon、localApi、localApiFiles）均无对应项——请移除。

示例：

 // capacitor.config.ts
 const config: CapacitorConfig = {
   plugins: {
-    CapacitorUpdater: {
-      appId: 'com.example.app',
-      autoUpdate: true,
-      defaultChannel: 'production',
-      appReadyTimeout: 10000,
-      autoDeletePrevious: true,
-      responseTimeout: 20
-    }
+    LiveUpdate: {
+      appId: '<CAPAWESOME_APP_ID>',
+      autoUpdateStrategy: 'background',
+      defaultChannel: 'production',
+      readyTimeout: 10000,
+      autoDeleteBundles: true,
+      autoBlockRolledBackBundles: true,
+      httpTimeout: 20000
+    }
   }
 };

第 5 步：更新导入和 API 调用

在所有 TypeScript/JavaScript 文件中搜索导入 @capgo/capacitor-updater 的语句，并替换为：

-import { CapacitorUpdater } from '@capgo/capacitor-updater';
+import { LiveUpdate } from '@capawesome/capacitor-live-update';

将所有对 CapacitorUpdater 类的引用替换为 LiveUpdate，并按下方的方法映射进行调整。完整的方法、事件和结果字段映射请阅读 references/api-mapping.md。最常见的替换如下：

应用就绪通知——将 notifyAppReady() 替换为 ready()。尽可能在应用启动时尽早调用：

-import { CapacitorUpdater } from '@capgo/capacitor-updater';
+import { LiveUpdate } from '@capawesome/capacitor-live-update';

-CapacitorUpdater.notifyAppReady();
+void LiveUpdate.ready();

检查更新——将 getLatest() 替换为 fetchLatestBundle()。结果字段也会变更（version → bundleId、url → downloadUrl）：

-const latest = await CapacitorUpdater.getLatest();
-if (latest.url) {
-  console.log('Update available:', latest.version);
+const result = await LiveUpdate.fetchLatestBundle();
+if (result.downloadUrl) {
+  console.log('Update available:', result.bundleId);
 }

下载 bundle——将 download() 替换为 downloadBundle()：

-const bundle = await CapacitorUpdater.download({
-  url: latest.url,
-  version: latest.version
-});
+await LiveUpdate.downloadBundle({
+  url: result.downloadUrl,
+  bundleId: result.bundleId
+});

设置下一个 bundle——将 next() 替换为 setNextBundle()。Capgo 的 set()（立即应用）需替换为 setNextBundle()，然后调用 reload()：

-await CapacitorUpdater.next({ id: bundle.id });
+await LiveUpdate.setNextBundle({ bundleId: result.bundleId });

-await CapacitorUpdater.set({ id: bundle.id });
+await LiveUpdate.setNextBundle({ bundleId: result.bundleId });
+await LiveUpdate.reload();

切换频道——优先将频道直接传递给 sync(...) 或 fetchLatestBundle(...)，而不是通过 setChannel() 持久化：

-await CapacitorUpdater.setChannel({ channel: 'beta', triggerAutoUpdate: true });
+await LiveUpdate.sync({ channel: 'beta' });

只有在频道分配必须在应用重启后继续保留时才使用 setChannel({ channel })；使用 setChannel({ channel: null }) 替换 Capgo 的 unsetChannel()。

第 6 步：迁移更新策略

将记录的 autoUpdate 和 directUpdate 值映射为 Capawesome 更新策略。

6.1 后台更新（Capgo 默认）

对于 autoUpdate: true、'atBackground'、'atInstall' 或不带 directUpdate 的 'onLaunch'，请使用后台策略：在配置中设置 autoUpdateStrategy: 'background'（已在步骤 4 中完成），无需编写同步代码。已下载的更新会在下次应用启动时应用。

6.2 始终使用最新版本（Capgo autoUpdate: 'always'）

将后台策略与 nextBundleSet 监听器结合，提示用户立即应用更新。在应用初始化的早期阶段添加以下代码：

import { LiveUpdate } from '@capawesome/capacitor-live-update';

LiveUpdate.addListener('nextBundleSet', async (event) => {
  if (event.bundleId) {
    const shouldReload = confirm('A new update is available. Install now?');
    if (shouldReload) {
      await LiveUpdate.reload();
    }
  }
});

请原样复制此代码片段。不要简化或省略 confirm() 对话框。

6.3 强制更新（Capgo directUpdate / autoSplashscreen）

如果 Capgo 配置了 directUpdate（任意非 false 值），请延长启动屏幕的显示时间，直到同步完成，以此复现该行为。从配置中省略 autoUpdateStrategy，并添加：

import { SplashScreen } from '@capacitor/splash-screen';
import { LiveUpdate } from '@capawesome/capacitor-live-update';

const initializeApp = async () => {
  const { nextBundleId } = await LiveUpdate.sync();
  if (nextBundleId) {
    await LiveUpdate.reload();
  } else {
    await SplashScreen.hide();
  }
};

initializeApp();

这同时替代了 directUpdate 和 autoSplashscreen，无需单独配置启动屏幕。此模式可能会影响慢速网络下的用户体验；建议改用后台策略。

6.4 手动更新 / 仅下载（Capgo autoUpdate: 'off' 或 'onlyDownload'）

不设置 autoUpdateStrategy，并使用步骤 5 中的方法映射迁移现有的手动 getLatest()/download()/next() 流程，或者将整个流程替换为一次 sync() 调用。一种常见模式是在 App 的 resume 事件中同步：

import { App } from '@capacitor/app';
import { LiveUpdate } from '@capawesome/capacitor-live-update';

void LiveUpdate.ready();

App.addListener('resume', async () => {
  await LiveUpdate.sync();
});

使用此模式时，已下载的更新会在下次应用启动时应用。

6.5 定期检查（Capgo periodCheckDelay）

不支持基于间隔的检查选项。后台策略已会在应用启动和恢复时检查更新（节流为每 15 分钟最多检查一次）。如需自定义间隔，请在 App 的 resume 事件中同步（参见 6.4），或使用 JavaScript 计时器调用 sync()。

6.6 同步 Capacitor 项目

npx cap sync

步骤 7：迁移代码签名

如果未检测到代码签名，请跳过此步骤。

Capgo 的密钥系统（.capgo_key_v2）提供端到端加密，而 Capawesome Cloud 使用 RSA 签名来验证 Bundle 完整性。这些密钥不能互换，因此请生成新的密钥对：

npx @capawesome/cli apps:liveupdates:generatesigningkey --app-type capacitor

此命令会输出用于 capacitor.config.ts 的 publicKey 配置片段。请安全地保存私钥（例如，作为 CI/CD 密钥），切勿将其提交到代码库。每次上传时都通过 --private-key 传入私钥进行签名（参见步骤 8）。

在确认迁移无误之前，请保留 .capgo_key_v2 文件，之后再删除（步骤 9）。

步骤 8：更新 CI/CD 流水线

如果未检测到 CI/CD，请跳过此步骤。

8.1 替换身份验证

在 Capawesome Cloud 控制台中生成令牌，并将其保存为名为 CAPAWESOME_CLOUD_TOKEN 的 CI/CD 密钥。然后替换 Capgo API 密钥：

-- run: npx @capgo/cli@latest login "$CAPGO_API_KEY"
+- run: npx @capawesome/cli login --token ${{ secrets.CAPAWESOME_CLOUD_TOKEN }}

Capgo 命令通常会直接传入 --apikey（或 -a），而不是使用 login。请移除这些标志；Capawesome CLI 会使用通过 login --token 提供的令牌。

8.2 替换 CLI 命令

使用以下命令映射（Capgo 将应用的 bundle ID 作为位置参数；Capawesome 使用 --app-id <UUID>）：

Capgo CLI	Capawesome CLI 对应命令
npx @capgo/cli login <API_KEY>	npx @capawesome/cli login --token <TOKEN>
npx @capgo/cli init <API_KEY> <BUNDLE_ID>	无对应命令 — 请改为按照此技能中的步骤操作
npx @capgo/cli app add <BUNDLE_ID>	npx @capawesome/cli apps:create --name <NAME>
npx @capgo/cli app list	npx @capawesome/cli apps:list
npx @capgo/cli app delete <BUNDLE_ID>	npx @capawesome/cli apps:delete --app-id <APP_ID>
npx @capgo/cli bundle upload <BUNDLE_ID> --path <PATH> --channel <CH>	npx @capawesome/cli apps:liveupdates:upload --app-id <APP_ID> --path <PATH> --channel <CH>
bundle upload --delta / --delta-only	apps:liveupdates:upload --artifact-type manifest
bundle upload --key-v2 <KEY_PATH>	apps:liveupdates:upload --private-key <KEY_PATH>
bundle upload --rollout <PCT>	apps:liveupdates:upload --rollout-percentage <PCT>
bundle upload --min-update-version <V>	--android-min/--ios-min 标志（原生版本限制，而不是 bundle 版本）
bundle upload -e <URL>（外部/可自托管）	apps:liveupdates:register --url <URL>
bundle zip	apps:liveupdates:bundle
bundle list / bundle delete / bundle cleanup	在 Console 中管理 bundle；为每个频道设置 bundle 数量上限，以便自动清理
channel add <CH> <BUNDLE_ID>	apps:channels:create --app-id <APP_ID> --name <CH>
channel delete <CH> <BUNDLE_ID>	apps:channels:delete --app-id <APP_ID> --name <CH>
channel list <BUNDLE_ID>	apps:channels:list --app-id <APP_ID>
channel set <CH> <BUNDLE_ID> --bundle <V>	apps:liveupdates:rollback --app-id <APP_ID> --channel <CH>（上一版本 bundle），或重新上传所需的 bundle
channel set <CH> <BUNDLE_ID> --rollout-percentage <PCT>	apps:liveupdates:rollout --app-id <APP_ID> --channel <CH> --percentage <PCT>
key create	apps:liveupdates:generatesigningkey
build request（Capgo 原生构建）	apps:builds:create — 请参阅 capawesome-cloud 技能中的「Native Builds」部分
doctor	doctor

上传命令替换示例：

-npx @capgo/cli@latest bundle upload com.example.app --apikey "$CAPGO_API_KEY" --path ./dist --channel production
+npx @capawesome/cli apps:liveupdates:upload --app-id <APP_ID> --path ./dist --channel production

Capgo 的 --bundle <VERSION> 标志没有对应命令 — Capawesome Cloud 会自动分配 bundle ID。使用 --git-ref 关联 Git 引用，并使用 --custom-property key=value 添加自定义元数据。

第 9 步：测试和验证

9.1 验证 Live Updates

询问用户是否要测试 Live Update 功能。如果用户同意：

1. 在应用中进行一处细微且可见的更改（例如，在标题后追加“ - Migration Test”）。
2. 构建 Web 资源：npm run build。
3. 上传 bundle：

   npx @capawesome/cli apps:liveupdates:upload --app-id <APP_ID> --channel <CHANNEL_NAME>
   

4. 撤销可见更改，重新构建并同步：

   npm run build && npx cap sync
   

5. 打开原生项目（npx cap open ios 或 npx cap open android），并在设备或模拟器上运行。
6. 验证 Live Update 是否已应用。对于 autoUpdateStrategy: "background"，请强制关闭并重新打开应用；或者离开应用超过 15 分钟后再返回，以触发检查。

9.2 清理

验证完所有功能后：

1. 确认已从 package.json 中移除 @capgo/capacitor-updater 和 @capgo/cli。
2. 确认已从 capacitor.config.ts/capacitor.config.json 中移除 CapacitorUpdater 配置。
3. 从项目根目录删除 .capgo_key_v2 和 .capgo_key_v2.pub（如果存在）。
4. 移除 Capgo CI/CD 密钥（例如 CAPGO_API_KEY）以及任何剩余的 @capgo/cli 命令。
5. 提醒用户，在所有使用 Capgo 的应用版本都已停止使用后，取消其 Capgo 订阅。

错误处理

• 插件替换后，npx cap sync 失败 → 确认已安装的 @capawesome/capacitor-live-update 版本与 package.json 中的 Capacitor 版本匹配（8 使用 @latest，7 使用 @v7-lts，6 使用 @v6-lts）。
• 出现 CapacitorUpdater is not defined 或类似运行时错误 → 确保所有导入都已从 @capgo/capacitor-updater 更新为 @capawesome/capacitor-live-update，并且类名已从 CapacitorUpdater 改为 LiveUpdate。
• 更新后，应用恢复到之前的捆绑包 → LiveUpdate.ready() 调用得不够早（等效于 Capgo 的 notifyAppReady()）。将其作为应用初始化时的第一个调用，或增加 readyTimeout。
• 已上传捆绑包，但未应用更新 → 确认配置中的 appId 是 Capawesome Cloud UUID（而不是 Capgo 捆绑包 ID），并且上传目标是设备解析到的频道（通过 getChannel() 检查）。
• autoUpdateStrategy: "background" 未检测到更新 → 只有在距离上次检查超过 15 分钟时，才会检查更新。强制关闭并重启应用。
• 启用代码签名后，签名验证失败 → 重用了 Capgo 密钥对。使用 apps:liveupdates:generatesigningkey 生成新的密钥对，更新配置中的 publicKey，并使用 --private-key 重新上传。
• setConfig is not a function → 已安装的插件版本过旧。更新到匹配的 dist-tag 最新版本（Capacitor 8 使用 @latest，7 使用 @v7-lts，6 使用 @v6-lts）——所有当前标签版本都包含 setConfig()。
• fetchChannels() 返回错误 → 必须在 Capawesome Cloud Console 中为应用启用频道发现功能。
• 迁移后，CI/CD 流水线失败 → 确保已设置 CAPAWESOME_CLOUD_TOKEN 密钥，在运行其他命令前执行 login --token，并且每条命令都使用 Capawesome Cloud UUID 传入 --app-id。

相关技能

• capawesome-cloud — Live Updates、Native Builds 和 App Store Publishing 的详细 Capawesome Cloud 设置流程。
• capawesome-cli — 安装、配置和使用 Capawesome CLI。
• ionic-appflow-migration — 如果项目迁移自 Ionic Appflow，而非 Capgo，请改用此技能。
• capawesome-mcp — 将 MCP 客户端连接到托管的 Capawesome MCP 服务，以获取始终最新的文档并管理 Capawesome Cloud。