capgo-cloud-migration

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Capgo Cloud Migration

Capgo 迁移至 Capawesome Cloud

Migrate an existing Capacitor project from Capgo to Capawesome Cloud.

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

Prerequisites

前提条件

A Capacitor 6, 7, or 8 app currently using Capgo for live updates.
Node.js 18+ and npm installed.
Access to the project's source code repository.
A Capawesome Cloud account and organization.

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

General Rules

通用规则

Before running any
```
@capawesome/cli
```
command for the first time, run it with the
```
--help
```
flag to review all available options.
Do not remove Capgo configuration, packages, or signing keys until the corresponding Capawesome Cloud feature is fully set up and verified.
Determine the Capacitor version from
```
package.json
```
(
```
@capacitor/core
```
) before making any changes — it affects which plugin version and update strategy to use.
The Capgo app ID is a native bundle ID (e.g.
```
com.example.app
```
), while the Capawesome Cloud app ID is a UUID. Never copy the Capgo app ID into the Capawesome configuration.

首次运行任何
```
@capawesome/cli
```
命令前，先添加
```
--help
```
参数查看所有可用选项。
在对应的Capawesome Cloud功能完全设置并验证通过前，请勿删除Capgo的配置、包或签名密钥。
在进行任何更改前，从
```
package.json
```
的
```
@capacitor/core
```
中确认Capacitor版本——这会影响插件版本和更新策略的选择。
Capgo的应用ID是原生Bundle ID（例如
```
com.example.app
```
），而Capawesome Cloud的应用ID是UUID。切勿将Capgo的应用ID复制到Capawesome的配置中。

MCP Server

MCP服务器

The Capawesome MCP server serves the current Capawesome documentation, so it is always ahead of the guidance bundled with this skill. With an API token it also exposes the Capawesome Cloud management API.

If the Capawesome MCP tools are available, call
```
search_docs
```
for the topic and read the matching page with
```
get_doc_page
```
before applying the guidance below. Where the two disagree, follow the documentation. The
```
cloud_*
```
tools can carry out the Capawesome Cloud steps in this skill directly — creating apps, triggering builds, deploying to channels and stores, rolling back, and diagnosing failed jobs — as an alternative to the Capawesome CLI.
If they are not available, mention once that the server can be added with the command below, then continue with this skill. Never block on it.

bash

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

The documentation tools need no account and no token. See the

capawesome-mcp

skill for full setup, including the Capawesome Cloud tools.

Capawesome MCP服务器提供最新的Capawesome文档，因此其内容始终比本技能内置的指南更超前。通过API令牌，它还能暴露Capawesome Cloud管理API。

如果Capawesome MCP工具可用，先调用
```
search_docs
```
查询相关主题，再使用
```
get_doc_page
```
读取匹配页面，然后再应用下方的指南。若两者内容不一致，请以文档为准。
```
cloud_*
```
工具可直接执行本技能中的Capawesome Cloud步骤——创建应用、触发构建、部署到渠道和商店、回滚以及诊断失败任务——作为Capawesome CLI的替代方案。
如果不可用，只需提及一次可通过以下命令添加服务器，然后继续使用本技能。无需在此步骤阻塞。

bash

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

文档工具无需账户和令牌。如需完整设置（包括Capawesome Cloud工具），请查看

capawesome-mcp

技能。

Procedures

迁移流程

Step 1: Detect Capgo Usage

步骤1：检测Capgo使用情况

Scan the project to determine which Capgo features are in use.

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

1.1 Check for the Capgo Updater Plugin

1.1 检查Capgo更新器插件

Search for these signals:

```
@capgo/capacitor-updater
```
in
```
package.json
```
(dependencies or devDependencies).

CapacitorUpdater

key inside the

plugins

object in

capacitor.config.ts

capacitor.config.json

Imports of
```
@capgo/capacitor-updater
```
in TypeScript/JavaScript source files.

If any signal is found, mark Live Updates as in use.

Record the current configuration values from the

CapacitorUpdater

config (all optional):

```
appId
```
(Capgo app ID, a bundle ID like
```
com.example.app
```
)

autoUpdate

(

true

false

'off'

'atBackground'

'atInstall'

'onLaunch'

'always'

, or

'onlyDownload'

; default

true

)

directUpdate

(

true

'atInstall'

'onLaunch'

, or

'always'

; default

false

)

```
defaultChannel
```
```
appReadyTimeout
```
(milliseconds; default
```
10000
```
)
```
autoDeletePrevious
```
(default
```
true
```
)
```
publicKey
```
(indicates end-to-end encryption is in use)
```
periodCheckDelay
```
(seconds)
```
responseTimeout
```
(seconds; default
```
20
```
)
```
updateUrl
```
/
```
statsUrl
```
/
```
channelUrl
```
(indicates a self-hosted Capgo backend)
```
autoSplashscreen
```
(default
```
false
```
)

搜索以下特征：

```
package.json
```
中（dependencies或devDependencies）的
```
@capgo/capacitor-updater
```
。

capacitor.config.ts

或

capacitor.config.json

中

plugins

对象内的

CapacitorUpdater

配置项。

TypeScript/JavaScript源文件中对
```
@capgo/capacitor-updater
```
的导入。

如果发现任一特征，标记实时更新为已启用。

记录

CapacitorUpdater

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

```
appId
```
（Capgo应用ID，类似
```
com.example.app
```
的Bundle 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 Check for the Capgo CLI in CI/CD

1.2 检查CI/CD中的Capgo CLI

Search for these signals:

```
@capgo/cli
```
in
```
package.json
```
(usually devDependencies).

capgo

@capgo/cli

commands (e.g.

bundle upload

channel set

) in CI/CD configuration files (e.g.,

.github/workflows/*.yml

.gitlab-ci.yml

bitrise.yml

Jenkinsfile

azure-pipelines.yml

) and npm scripts.

A
```
CAPGO_API_KEY
```
(or similar) secret referenced in CI/CD files.

If any signal is found, mark CI/CD as in use and record every Capgo CLI command with its options.

搜索以下特征：

```
package.json
```
中（通常在devDependencies）的
```
@capgo/cli
```
。

CI/CD配置文件（如

.github/workflows/*.yml

、

.gitlab-ci.yml

、

bitrise.yml

、

Jenkinsfile

、

azure-pipelines.yml

）和npm脚本中的

capgo

或

@capgo/cli

命令（例如

bundle upload

、

channel set

）。

CI/CD文件中引用的
```
CAPGO_API_KEY
```
（或类似）密钥。

如果发现任一特征，标记CI/CD为已启用，并记录所有Capgo CLI命令及其选项。

1.3 Check for Code Signing / Encryption

1.3 检查代码签名/加密

Search for these signals:

.capgo_key_v2

.capgo_key_v2.pub

files in the project root (created by

npx @capgo/cli key create

A
```
publicKey
```
value in the
```
CapacitorUpdater
```
config.
```
--key-v2
```
or
```
--key-data-v2
```
flags on
```
bundle upload
```
commands in CI/CD.

If any signal is found, mark Code Signing as in use.

搜索以下特征：

项目根目录中的

.capgo_key_v2

或

.capgo_key_v2.pub

文件（由

npx @capgo/cli key create

生成）。

```
CapacitorUpdater
```
配置中的
```
publicKey
```
值。
CI/CD中
```
bundle upload
```
命令的
```
--key-v2
```
或
```
--key-data-v2
```
参数。

如果发现任一特征，标记代码签名为已启用。

1.4 Check for Capgo Native Builds

1.4 检查Capgo原生构建

Search for

capgo build

commands (e.g.

build request

build credentials

) in CI/CD files or npm scripts. If found, mark Native Builds as in use.

在CI/CD文件或npm脚本中搜索

capgo build

命令（例如

build request

、

build credentials

）。如果找到，标记原生构建为已启用。

1.5 Record Channels

1.5 记录渠道信息

List the existing Capgo channels so they can be recreated in Capawesome Cloud:

bash

npx @capgo/cli channel list <CAPGO_APP_ID>

If the command fails (e.g. no API key available), ask the user to list their channels from the Capgo Console instead.

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

bash

npx @capgo/cli channel list <CAPGO_APP_ID>

如果命令失败（例如无可用API密钥），请用户从Capgo控制台手动列出渠道。

1.6 Present Findings

1.6 展示检测结果

Present the detected features (Live Updates, CI/CD, Code Signing, Native Builds) and recorded configuration to the user. Ask the user to confirm which features to migrate.

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

Step 2: Set Up Capawesome Cloud

步骤2：设置Capawesome Cloud

2.1 Authenticate

2.1 身份验证

bash

npx @capawesome/cli login

bash

npx @capawesome/cli login

2.2 Create an App

2.2 创建应用

Skip if the user already has a Capawesome Cloud app ID.

bash

npx @capawesome/cli apps:create

Save the returned app ID (UUID) for subsequent steps. This replaces the Capgo app ID everywhere, but has a different format — it is not the native bundle ID.

如果用户已有Capawesome Cloud应用ID，可跳过此步骤。

bash

npx @capawesome/cli apps:create

保存返回的应用ID（UUID），用于后续步骤。它将替代所有场景中的Capgo应用ID，但格式不同——不是原生Bundle ID。

2.3 Recreate Channels

2.3 重新创建渠道

Create one Capawesome Cloud channel for each Capgo channel recorded in Step 1.5:

bash

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

Capgo channel settings like

--self-assign

--disable-auto-update

, or device targeting (

--ios

--android

) have no channel-level equivalent in Capawesome Cloud:

Device self-assignment is not required — the Live Update SDK can request any channel via
```
sync({ channel })
```
or
```
setChannel()
```
without a server-side opt-in.
Update blocking by native version is configured per bundle at upload time (
```
--android-min
```
,
```
--ios-min
```
, and related flags).

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

bash

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

Capgo渠道的设置（如

--self-assign

、

--disable-auto-update

或设备目标选择

--ios

--android

）在Capawesome Cloud中没有渠道级别的对应项：

无需设备自分配——Live Update SDK可通过
```
sync({ channel })
```
或
```
setChannel()
```
请求任意渠道，无需服务器端授权。
按原生版本阻止更新的配置在上传包时设置（
```
--android-min
```
、
```
--ios-min
```
及相关参数）。

Step 3: Replace the Plugin

步骤3：替换插件

Skip this step if Live Updates was not detected or the user chose not to migrate it.

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

3.1 Remove the Capgo Updater Plugin

3.1 移除Capgo更新器插件

bash

npm uninstall @capgo/capacitor-updater

bash

npm uninstall @capgo/capacitor-updater

3.2 Install the Capawesome Live Update Plugin

3.2 安装Capawesome实时更新插件

Install the version matching the project's Capacitor version:

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

安装与项目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

Step 4: Update the Capacitor Configuration

步骤4：更新Capacitor配置

Replace the

CapacitorUpdater

plugin config with

LiveUpdate

capacitor.config.ts

(or

.json

). Map the configuration options as follows:

Capgo ( `CapacitorUpdater` )	Capawesome ( `LiveUpdate` )	Notes
`appId`	`appId`	Different value — use the Capawesome Cloud app ID (UUID) from Step 2
`appReadyTimeout`	`readyTimeout`	Both in milliseconds. Capgo defaults to `10000` , Capawesome to `0` (disabled) — set `readyTimeout: 10000` explicitly to keep rollback protection
`autoDeletePrevious`	`autoDeleteBundles`	Capgo defaults to `true` , Capawesome to `false` — set `autoDeleteBundles: true` explicitly
`autoDeleteFailed`	(remove)	Use `autoBlockRolledBackBundles: true` to prevent re-installing bundles that caused a rollback
`autoUpdate`	`autoUpdateStrategy` or code	See Step 6 for the strategy mapping
`autoSplashscreen` (+ `autoSplashscreenLoader` , `autoSplashscreenTimeout` )	(remove)	Handled in code — see the Force Update pattern in Step 6
`defaultChannel`	`defaultChannel`	Same value
`directUpdate`	(remove)	Handled in code — see Step 6
`periodCheckDelay`	(remove)	Handled in code — sync on the App `resume` event instead (Step 6)
`publicKey`	`publicKey`	New value required — generate a new key pair in Step 7. Do not reuse the Capgo key
`resetWhenUpdate`	(remove)	Handled automatically by the SDK
`responseTimeout`	`httpTimeout`	Unit change: Capgo uses seconds (default `20` ), Capawesome uses milliseconds (default `60000` ) — multiply by 1000
`statsUrl`	(remove)	Not needed
`updateUrl` / `channelUrl`	`serverDomain`	Only set for EU hosting ( `api.cloud.capawesome.eu` ). Domain only, without scheme or path. Default is `api.cloud.capawesome.io`
`version`	(remove)	The native version code is used by the SDK

All other Capgo options (

allowModifyUrl

allowModifyAppId

allowManualBundleError

allowPreview

persistCustomId

persistModifyUrl

allowSetDefaultChannel

keepUrlPathAfterReload

disableJSLogging

osLogging

shakeMenu

shakeMenuGesture

allowShakeChannelSelector

localS3

localHost

localWebHost

localSupa

localSupaAnon

localApi

localApiFiles

) have no equivalent — remove them.

Example:

diff

 // 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
+    }
   }
 };

在

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` 防止重新安装导致回滚的包
`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`	仅在使用欧盟托管时设置（ `api.cloud.capawesome.eu` ）。仅需域名，无需协议或路径。默认值为 `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

）均无对应项——直接移除。

示例：

diff

 // 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
+    }
   }
 };

Step 5: Update Imports and API Calls

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

Search all TypeScript/JavaScript files for imports of

@capgo/capacitor-updater

and replace:

diff

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

Replace all references to the

CapacitorUpdater

class with

LiveUpdate

, applying the method mapping below. Read

references/api-mapping.md

for the complete method, event, and result-field mapping. The most common replacements:

App ready notification —

notifyAppReady()

becomes

ready()

. Keep it as early as possible in app startup:

diff

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

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

Check for updates —

getLatest()

becomes

fetchLatestBundle()

. The result fields change (

version

→

bundleId

url

→

downloadUrl

diff

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

Download a bundle —

download()

becomes

downloadBundle()

diff

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

Set the next bundle —

next()

becomes

setNextBundle()

. Capgo's

set()

(apply immediately) becomes

setNextBundle()

followed by

reload()

diff

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

diff

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

Channel switching — prefer passing the channel directly to

sync(...)

fetchLatestBundle(...)

instead of persisting it with

setChannel()

diff

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

Use

setChannel({ channel })

only if the channel assignment must persist across app restarts, and

setChannel({ channel: null })

as the replacement for Capgo's

unsetChannel()

搜索所有TypeScript/JavaScript文件中对

@capgo/capacitor-updater

的导入并替换：

diff

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

将所有对

CapacitorUpdater

类的引用替换为

LiveUpdate

，并应用以下方法映射。完整的方法、事件和结果字段映射请查看

references/api-mapping.md

。最常见的替换如下：

应用就绪通知——

notifyAppReady()

改为

ready()

。请在应用启动时尽早调用：

diff

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

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

检查更新——

getLatest()

改为

fetchLatestBundle()

。结果字段变更（

version

→

bundleId

，

url

→

downloadUrl

）：

diff

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

下载包——

download()

改为

downloadBundle()

：

diff

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

设置下一个包——

next()

改为

setNextBundle()

。Capgo的

set()

（立即应用）改为

setNextBundle()

后调用

reload()

：

diff

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

diff

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

切换渠道——建议直接将渠道传递给

sync(...)

或

fetchLatestBundle(...)

，而非使用

setChannel()

持久化：

diff

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

仅当渠道分配需要跨应用重启持久化时，才使用

setChannel({ channel })

；使用

setChannel({ channel: null })

替代Capgo的

unsetChannel()

。

Step 6: Migrate the Update Strategy

步骤6：迁移更新策略

Map the recorded

autoUpdate

and

directUpdate

values to a Capawesome update strategy.

将记录的

autoUpdate

和

directUpdate

值映射到Capawesome更新策略。

6.1 Background Updates (Capgo default)

6.1 后台更新（Capgo默认）

For

autoUpdate: true

'atBackground'

'atInstall'

, or

'onLaunch'

without

directUpdate

, use the background strategy: set

autoUpdateStrategy: 'background'

in the config (already done in Step 4) — no sync code is needed. Downloaded updates are applied on the next app start.

对于

autoUpdate: true

、

'atBackground'

、

'atInstall'

或

'onLaunch'

且未设置

directUpdate

的情况，使用后台策略：在配置中设置

autoUpdateStrategy: 'background'

（步骤4已完成）——无需同步代码。下载的更新将在下次应用启动时应用。

6.2 Always Latest (Capgo

autoUpdate: 'always'

)

6.2 始终保持最新（Capgo

autoUpdate: 'always'

）

Combine the background strategy with a

nextBundleSet

listener that prompts the user to apply the update immediately. Add this code early in the app's initialization:

typescript

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

Copy this snippet exactly. Do not simplify or omit the

confirm()

dialog.

将后台策略与

nextBundleSet

监听器结合，提示用户立即应用更新。在应用初始化早期添加以下代码：

typescript

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 Force Update (Capgo

directUpdate

autoSplashscreen

)

6.3 强制更新（Capgo

directUpdate

autoSplashscreen

）

If Capgo was configured with

directUpdate

(any non-

false

value), replicate it by extending the splash screen until the sync completes. Omit

autoUpdateStrategy

from the config and add:

typescript

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();

This replaces both

directUpdate

and

autoSplashscreen

— no separate splash screen config is needed. This pattern may impact user experience on slow connections; consider the background strategy instead.

如果Capgo配置了

directUpdate

（任何非

false

值），可通过延长启动屏显示时间直到同步完成来实现。从配置中移除

autoUpdateStrategy

并添加以下代码：

typescript

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 Manual / Download-Only (Capgo

autoUpdate: 'off'

'onlyDownload'

)

6.4 手动/仅下载（Capgo

autoUpdate: 'off'

或

'onlyDownload'

）

Keep

autoUpdateStrategy

unset and migrate the existing manual

getLatest()

download()

next()

flow using the method mapping from Step 5, or replace the whole flow with a single

sync()

call. A common pattern is to sync on the App

resume

event:

typescript

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

void LiveUpdate.ready();

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

With this pattern, downloaded updates are applied on the next app start.

不设置

autoUpdateStrategy

，使用步骤5中的方法映射迁移现有的手动

getLatest()

download()

next()

流程，或用单次

sync()

调用替换整个流程。常见模式是在App

resume

事件时同步：

typescript

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

void LiveUpdate.ready();

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

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

6.5 Periodic Checks (Capgo

periodCheckDelay

)

6.5 定期检查（Capgo

periodCheckDelay

）

There is no interval-based check option. The background strategy already checks for updates on app start and resume (throttled to once every 15 minutes). For a custom interval, sync on the App

resume

event (see 6.4) or implement a JavaScript timer that calls

sync()

Capawesome没有基于间隔的检查选项。后台策略已在应用启动和恢复时检查更新（限制为每15分钟一次）。如需自定义间隔，可在App

resume

事件时同步（见6.4）或实现JavaScript定时器调用

sync()

。

6.6 Sync the Capacitor Project

6.6 同步Capacitor项目

bash

npx cap sync

bash

npx cap sync

Step 7: Migrate Code Signing

步骤7：迁移代码签名

Skip this step if Code Signing was not detected.

Capgo's key system (

.capgo_key_v2

) provides end-to-end encryption, while Capawesome Cloud uses RSA signing for bundle integrity verification. The keys are not interchangeable — generate a new key pair:

bash

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

This prints the

publicKey

config snippet for

capacitor.config.ts

. Store the private key securely (e.g. as a CI/CD secret) and never commit it. Sign every upload by passing

--private-key

(see Step 8).

Keep the

.capgo_key_v2

files until the migration is verified, then delete them (Step 9).

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

Capgo的密钥系统（

.capgo_key_v2

）提供端到端加密，而Capawesome Cloud使用RSA签名进行包完整性验证。密钥不可互换——需生成新的密钥对：

bash

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

这将打印

capacitor.config.ts

中

publicKey

的配置片段。请安全存储私钥（例如作为CI/CD密钥），切勿提交到仓库。每次上传时需传递

--private-key

参数（见步骤8）进行签名。

在迁移验证完成前保留

.capgo_key_v2

文件，之后再删除（步骤9）。

Step 8: Update CI/CD Pipelines

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

Skip this step if CI/CD was not detected.

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

8.1 Replace Authentication

8.1 替换身份验证方式

Generate a token in the Capawesome Cloud Console and store it as a CI/CD secret named

CAPAWESOME_CLOUD_TOKEN

. Then replace the Capgo API key:

diff

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

Capgo commands often pass

--apikey

(or

-a

) inline instead of using

login

— remove those flags; the Capawesome CLI uses the token from

login --token

在Capawesome Cloud控制台生成令牌，并将其存储为名为

CAPAWESOME_CLOUD_TOKEN

的CI/CD密钥。然后替换Capgo API密钥：

diff

-- 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 Replace CLI Commands

8.2 替换CLI命令

Use the following command mapping (Capgo identifies apps by bundle ID as a positional argument; Capawesome uses

--app-id <UUID>

Capgo CLI	Capawesome CLI Equivalent
`npx @capgo/cli login <API_KEY>`	`npx @capawesome/cli login --token <TOKEN>`
`npx @capgo/cli init <API_KEY> <BUNDLE_ID>`	No equivalent — follow this skill's steps instead
`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` flags (native version constraints, not bundle versions)
`bundle upload -e <URL>` (external/self-hosted)	`apps:liveupdates:register --url <URL>`
`bundle zip`	`apps:liveupdates:bundle`
`bundle list` / `bundle delete` / `bundle cleanup`	Manage bundles in the Console; set a bundle limit per channel for automatic cleanup
`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>` (previous bundle) or re-upload the desired 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 native builds)	`apps:builds:create` — use the `capawesome-cloud` skill's Native Builds section
`doctor`	`doctor`

Example upload replacement:

diff

-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

There is no equivalent for Capgo's

--bundle <VERSION>

flag — Capawesome Cloud assigns a bundle ID automatically. Use

--git-ref

to associate a Git reference and

--custom-property key=value

for custom metadata instead.

使用以下命令映射（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 upload -e <URL>` （外部/自托管）	`apps:liveupdates:register --url <URL>`
`bundle zip`	`apps:liveupdates:bundle`
`bundle list` / `bundle delete` / `bundle cleanup`	在控制台中管理包；为每个渠道设置包数量限制以自动清理
`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>` （回滚到上一个包）或重新上传所需包
`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` 技能中的原生构建部分
`doctor`	`doctor`

上传命令替换示例：

diff

-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会自动分配包ID。可使用

--git-ref

关联Git引用，使用

--custom-property key=value

添加自定义元数据。

Step 9: Test and Verify

步骤9：测试与验证

9.1 Verify Live Updates

9.1 验证实时更新

Ask the user whether to test live update functionality. If accepted:

Make a small, visible change in the app (e.g., append " - Migration Test" to a heading).
Build the web assets:
```
npm run build
```
.

Upload the bundle:

bash

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

Revert the visible change, rebuild, and sync:
bash
```
npm run build && npx cap sync
```
Open the native project (
```
npx cap open ios
```
or
```
npx cap open android
```
) and run on a device or emulator.
Verify the live update is applied. With
```
autoUpdateStrategy: "background"
```
, force-close and reopen the app, or switch away from the app and return after more than 15 minutes to trigger a check.

询问用户是否测试实时更新功能。如果同意：

在应用中进行一个小的可见更改（例如，在标题后添加" - 迁移测试"）。
构建Web资源：
```
npm run build
```
。

上传包：

bash

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

撤销可见更改，重新构建并同步：
bash
```
npm run build && npx cap sync
```
打开原生项目（
```
npx cap open ios
```
或
```
npx cap open android
```
）并在设备或模拟器上运行。
验证实时更新已应用。如果设置了
```
autoUpdateStrategy: "background"
```
，请强制关闭并重新打开应用，或切换出应用后等待15分钟以上再返回以触发检查。

9.2 Clean Up

9.2 清理工作

After all features are verified:

Confirm

@capgo/capacitor-updater

and

@capgo/cli

are removed from

package.json

Confirm the

CapacitorUpdater

config is removed from

capacitor.config.ts

capacitor.config.json

Delete
```
.capgo_key_v2
```
and
```
.capgo_key_v2.pub
```
from the project root (if present).
Remove Capgo CI/CD secrets (e.g.
```
CAPGO_API_KEY
```
) and any remaining
```
@capgo/cli
```
commands.
Remind the user to cancel their Capgo subscription once all app versions using Capgo have been phased out.

所有功能验证通过后：

确认

@capgo/capacitor-updater

和

@capgo/cli

已从

package.json

中移除。

确认

capacitor.config.ts

capacitor.config.json

中的

CapacitorUpdater

配置已移除。

删除项目根目录中的
```
.capgo_key_v2
```
和
```
.capgo_key_v2.pub
```
文件（如果存在）。
移除Capgo CI/CD密钥（如
```
CAPGO_API_KEY
```
）和所有剩余的
```
@capgo/cli
```
命令。
提醒用户，当所有使用Capgo的应用版本都已淘汰后，可取消Capgo订阅。

Error Handling

错误处理

```
npx cap sync
```
fails after the plugin swap → Verify the installed
```
@capawesome/capacitor-live-update
```
version matches the Capacitor version in
```
package.json
```
(
```
@latest
```
for 8,
```
@v7-lts
```
for 7,
```
@v6-lts
```
for 6).

CapacitorUpdater is not defined

or similar runtime errors → Ensure all imports were updated from

@capgo/capacitor-updater

@capawesome/capacitor-live-update

and the class name changed from

CapacitorUpdater

LiveUpdate

App reverts to the previous bundle after an update →
```
LiveUpdate.ready()
```
is not called early enough (Capgo's
```
notifyAppReady()
```
equivalent). Add it as the first call in app initialization, or increase
```
readyTimeout
```
.
No update is applied although a bundle was uploaded → Verify the
```
appId
```
in the config is the Capawesome Cloud UUID (not the Capgo bundle ID) and that the upload targeted the channel the device resolves (check with
```
getChannel()
```
).
Updates not detected with
```
autoUpdateStrategy: "background"
```
→ Updates are only checked if the last check was more than 15 minutes ago. Force-close and restart the app.
Signature verification fails after enabling code signing → The Capgo key pair was reused. Generate a new key pair with
```
apps:liveupdates:generatesigningkey
```
, update
```
publicKey
```
in the config, and re-upload with
```
--private-key
```
.
```
setConfig is not a function
```
→ The installed plugin release is outdated. Update to the latest release of the matching dist-tag (
```
@latest
```
for Capacitor 8,
```
@v7-lts
```
for 7,
```
@v6-lts
```
for 6) — all current tag releases include
```
setConfig()
```
.
```
fetchChannels()
```
returns an error → Channel discovery must be enabled for the app in the Capawesome Cloud Console.
CI/CD pipeline fails after migration → Ensure the
```
CAPAWESOME_CLOUD_TOKEN
```
secret is set,
```
login --token
```
runs before other commands, and every command passes
```
--app-id
```
with the Capawesome Cloud UUID.

替换插件后
```
npx cap sync
```
失败 → 确认安装的
```
@capawesome/capacitor-live-update
```
版本与
```
package.json
```
中的Capacitor版本匹配（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的Bundle 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控制台中为应用启用渠道发现功能。
迁移后CI/CD流水线失败 → 确保已设置
```
CAPAWESOME_CLOUD_TOKEN
```
密钥，
```
login --token
```
在其他命令前运行，且每个命令都通过
```
--app-id
```
传递Capawesome Cloud的UUID。

capgo-cloud-migration

Original

Translation

Capgo Cloud Migration

Capgo 迁移至 Capawesome Cloud

Prerequisites

前提条件

General Rules

通用规则

MCP Server

MCP服务器

Procedures

迁移流程

Step 1: Detect Capgo Usage

步骤1：检测Capgo使用情况

1.1 Check for the Capgo Updater Plugin

1.1 检查Capgo更新器插件

1.2 Check for the Capgo CLI in CI/CD

1.2 检查CI/CD中的Capgo CLI

1.3 Check for Code Signing / Encryption

1.3 检查代码签名/加密

1.4 Check for Capgo Native Builds

1.4 检查Capgo原生构建

1.5 Record Channels

1.5 记录渠道信息

1.6 Present Findings

1.6 展示检测结果

Step 2: Set Up Capawesome Cloud

步骤2：设置Capawesome Cloud

2.1 Authenticate

2.1 身份验证

2.2 Create an App

2.2 创建应用

2.3 Recreate Channels

2.3 重新创建渠道

Step 3: Replace the Plugin

步骤3：替换插件

3.1 Remove the Capgo Updater Plugin

3.1 移除Capgo更新器插件

3.2 Install the Capawesome Live Update Plugin

3.2 安装Capawesome实时更新插件

Step 4: Update the Capacitor Configuration

步骤4：更新Capacitor配置

Step 5: Update Imports and API Calls

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

Step 6: Migrate the Update Strategy

步骤6：迁移更新策略

6.1 Background Updates (Capgo default)

6.1 后台更新（Capgo默认）

6.2 Always Latest (Capgo autoUpdate: 'always')

6.2 始终保持最新（Capgo autoUpdate: 'always'）

6.3 Force Update (Capgo directUpdate / autoSplashscreen)

6.3 强制更新（Capgo directUpdate / autoSplashscreen）

6.4 Manual / Download-Only (Capgo autoUpdate: 'off' or 'onlyDownload')

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

6.5 Periodic Checks (Capgo periodCheckDelay)

6.5 定期检查（Capgo periodCheckDelay）

6.6 Sync the Capacitor Project

6.6 同步Capacitor项目

Step 7: Migrate Code Signing

步骤7：迁移代码签名

Step 8: Update CI/CD Pipelines

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

8.1 Replace Authentication

8.1 替换身份验证方式

8.2 Replace CLI Commands

8.2 替换CLI命令

Step 9: Test and Verify

步骤9：测试与验证

9.1 Verify Live Updates

9.1 验证实时更新

9.2 Clean Up

9.2 清理工作

Error Handling

错误处理

Related Skills

相关技能

6.2 Always Latest (Capgo
`autoUpdate: 'always'`
)

6.2 始终保持最新（Capgo
`autoUpdate: 'always'`
）

6.3 Force Update (Capgo
`directUpdate`
/
`autoSplashscreen`
)

6.3 强制更新（Capgo
`directUpdate`
/
`autoSplashscreen`
）

6.4 Manual / Download-Only (Capgo
`autoUpdate: 'off'`
or
`'onlyDownload'`
)

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

6.5 Periodic Checks (Capgo
`periodCheckDelay`
)

6.5 定期检查（Capgo
`periodCheckDelay`
）