ionic-appflow-migration

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Ionic Appflow Migration

Ionic Appflow 迁移指南

Migrate an existing Ionic/Capacitor project from Ionic Appflow to Capawesome Cloud.

将现有Ionic/Capacitor项目从Ionic Appflow迁移至Capawesome Cloud。

Prerequisites

前提条件

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

当前使用Ionic Appflow的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 Ionic Appflow configuration 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.

首次运行任何
```
@capawesome/cli
```
命令前，先添加
```
--help
```
参数查看所有可用选项。
在对应的Capawesome Cloud功能完全设置并验证通过前，请勿删除Ionic Appflow配置。
在进行任何更改前，先从
```
package.json
```
的
```
@capacitor/core
```
字段确认Capacitor版本——这会影响插件版本选择及更新策略。

Procedures

迁移步骤

Step 1: Detect Ionic Appflow Usage

步骤1：检测Ionic Appflow功能使用情况

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

扫描项目以确定正在使用的Appflow功能。

1.1 Check for Live Updates

1.1 检查实时更新功能

Search for these signals:

```
@capacitor/live-updates
```
in
```
package.json
```
(dependencies or devDependencies).
```
cordova-plugin-ionic
```
in
```
package.json
```
— this is the legacy Cordova SDK for Ionic Live Updates.

LiveUpdates

key inside the

plugins

object in

capacitor.config.ts

capacitor.config.json

Imports of
```
@capacitor/live-updates
```
or
```
cordova-plugin-ionic
```
in TypeScript/JavaScript source files.

If any signal is found, mark Live Updates as in use. Also record which SDK is in use (

@capacitor/live-updates

cordova-plugin-ionic

Record the current configuration values:

```
appId
```
(Ionic Appflow app ID)
```
autoUpdateMethod
```
(
```
background
```
,
```
always
```
, or
```
none
```
)
```
channel
```
```
enabled
```
```
maxVersions
```

查找以下特征：

```
package.json
```
的依赖或开发依赖中包含
```
@capacitor/live-updates
```
。
```
package.json
```
中包含
```
cordova-plugin-ionic
```
——这是Ionic实时更新的旧版Cordova SDK。

capacitor.config.ts

或

capacitor.config.json

的

plugins

对象中存在

LiveUpdates

配置项。

TypeScript/JavaScript源文件中导入了
```
@capacitor/live-updates
```
或
```
cordova-plugin-ionic
```
。

如果发现以上任一特征，标记实时更新为已使用。同时记录所使用的SDK类型（

@capacitor/live-updates

或

cordova-plugin-ionic

）。

记录当前配置值：

```
appId
```
（Ionic Appflow应用ID）
```
autoUpdateMethod
```
（
```
background
```
、
```
always
```
或
```
none
```
）
```
channel
```
```
enabled
```
```
maxVersions
```

1.2 Check for Native Builds

1.2 检查原生构建功能

Search for these signals:

References to

ionic appflow build

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

.github/workflows/*.yml

.gitlab-ci.yml

bitrise.yml

Jenkinsfile

azure-pipelines.yml

References to

dashboard.ionicframework.com

appflow.ionic.io

in CI/CD files or scripts.

An
```
appflow.config.json
```
or similar Appflow build configuration file in the project root.

If any signal is found, mark Native Builds as in use.

查找以下特征：

CI/CD配置文件（如

.github/workflows/*.yml

、

.gitlab-ci.yml

、

bitrise.yml

、

Jenkinsfile

、

azure-pipelines.yml

）中存在

ionic appflow build

引用。

CI/CD文件或脚本中存在

dashboard.ionicframework.com

或

appflow.ionic.io

引用。

项目根目录下存在
```
appflow.config.json
```
或类似的Appflow构建配置文件。

如果发现以上任一特征，标记原生构建为已使用。

1.3 Check for App Store Publishing

1.3 检查应用商店发布功能

Search for these signals:

References to
```
ionic appflow deploy
```
in CI/CD configuration files.
Appflow deploy destinations or channels configured for app store submission.

If any signal is found, mark App Store Publishing as in use.

查找以下特征：

CI/CD配置文件中存在
```
ionic appflow deploy
```
引用。
已配置用于应用商店提交的Appflow发布目标或渠道。

如果发现以上任一特征，标记应用商店发布为已使用。

1.4 Present Findings

1.4 呈现检测结果

Present the detected features to the user. Ask the user to confirm which features to migrate. The user may choose to migrate all detected features or only a subset.

向用户展示检测到的功能，询问用户确认需要迁移的功能。用户可选择迁移所有检测到的功能或仅迁移部分功能。

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.

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

bash

npx @capawesome/cli apps:create

保存返回的应用ID（UUID），供后续步骤使用。

Step 3: Migrate Live Updates

步骤3：迁移实时更新功能

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

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

3.1 Remove the Ionic Live Updates SDK

3.1 移除Ionic实时更新SDK

If the project uses

@capacitor/live-updates

bash

npm uninstall @capacitor/live-updates

If the project uses the legacy Cordova SDK (

cordova-plugin-ionic

bash

npm uninstall cordova-plugin-ionic

Read

references/cordova-sdk-migration.md

for the native configuration cleanup steps (removing legacy keys from

Info.plist

strings.xml

, and Capacitor config).

如果项目使用

@capacitor/live-updates

：

bash

npm uninstall @capacitor/live-updates

如果项目使用旧版Cordova SDK（

cordova-plugin-ionic

）：

bash

npm uninstall cordova-plugin-ionic

阅读

references/cordova-sdk-migration.md

了解原生配置清理步骤（从

Info.plist

、

strings.xml

及Capacitor配置中移除旧版配置项）。

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@^7.3.0

Capacitor 6:

npm install @capawesome/capacitor-live-update@^6.0.0

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

Capacitor 8：

npm install @capawesome/capacitor-live-update@latest

Capacitor 7：

npm install @capawesome/capacitor-live-update@^7.3.0

Capacitor 6：

npm install @capawesome/capacitor-live-update@^6.0.0

3.3 Update the Capacitor Configuration

3.3 更新Capacitor配置

Replace the

LiveUpdates

plugin config with

LiveUpdate

capacitor.config.ts

(or

.json

). Map the configuration options as follows:

Ionic Appflow ( `LiveUpdates` )	Capawesome Cloud ( `LiveUpdate` )	Notes
`appId`	`appId`	Replace with the Capawesome Cloud app ID from Step 2
`autoUpdateMethod: 'background'`	`autoUpdateStrategy: 'background'`	Capacitor 7/8 only. Omit for Capacitor 6
`autoUpdateMethod: 'always'`	`autoUpdateStrategy: 'background'`	Capacitor 7/8 only. Also add `nextBundleSet` listener (see Step 3.5)
`autoUpdateMethod: 'none'`	(omit `autoUpdateStrategy` )	Use manual sync code instead (see Step 3.6)
`channel`	`defaultChannel`	Same value
`enabled`	(remove)	Not needed — controlled in code
`maxVersions`	`autoDeleteBundles: true`	Boolean instead of number

Example — Capacitor 7/8 with background strategy:

diff

 // capacitor.config.ts
 const config: CapacitorConfig = {
   plugins: {
-    LiveUpdates: {
-      appId: 'abc12345',
-      autoUpdateMethod: 'background',
-      channel: 'production',
-      maxVersions: 3
-    }
+    LiveUpdate: {
+      appId: '<CAPAWESOME_APP_ID>',
+      autoUpdateStrategy: 'background',
+      defaultChannel: 'production',
+      autoDeleteBundles: true
+    }
   }
 };

Example — Capacitor 6 (no autoUpdateStrategy):

diff

 // capacitor.config.ts
 const config: CapacitorConfig = {
   plugins: {
-    LiveUpdates: {
-      appId: 'abc12345',
-      channel: 'production',
-      maxVersions: 3
-    }
+    LiveUpdate: {
+      appId: '<CAPAWESOME_APP_ID>',
+      defaultChannel: 'production',
+      autoDeleteBundles: true
+    }
   }
 };

将

capacitor.config.ts

（或

.json

）中的

LiveUpdates

插件配置替换为

LiveUpdate

。配置项映射如下：

Ionic Appflow（ `LiveUpdates` ）	Capacitor Cloud（ `LiveUpdate` ）	说明
`appId`	`appId`	替换为步骤2中获取的Capawesome Cloud应用ID
`autoUpdateMethod: 'background'`	`autoUpdateStrategy: 'background'`	仅适用于Capacitor 7/8，Capacitor 6无需配置
`autoUpdateMethod: 'always'`	`autoUpdateStrategy: 'background'`	仅适用于Capacitor 7/8，同时需添加 `nextBundleSet` 监听器（见步骤3.5）
`autoUpdateMethod: 'none'`	（省略 `autoUpdateStrategy` ）	改用手动同步代码（见步骤3.6）
`channel`	`defaultChannel`	值保持不变
`enabled`	（移除）	无需配置，由代码控制
`maxVersions`	`autoDeleteBundles: true`	布尔值替代数字

示例——Capacitor 7/8（background策略）：

diff

 // capacitor.config.ts
 const config: CapacitorConfig = {
   plugins: {
-    LiveUpdates: {
-      appId: 'abc12345',
-      autoUpdateMethod: 'background',
-      channel: 'production',
-      maxVersions: 3
-    }
+    LiveUpdate: {
+      appId: '<CAPAWESOME_APP_ID>',
+      autoUpdateStrategy: 'background',
+      defaultChannel: 'production',
+      autoDeleteBundles: true
+    }
   }
 };

示例——Capacitor 6（无autoUpdateStrategy）：

diff

 // capacitor.config.ts
 const config: CapacitorConfig = {
   plugins: {
-    LiveUpdates: {
-      appId: 'abc12345',
-      channel: 'production',
-      maxVersions: 3
-    }
+    LiveUpdate: {
+      appId: '<CAPAWESOME_APP_ID>',
+      defaultChannel: 'production',
+      autoDeleteBundles: true
+    }
   }
 };

3.4 Update Import Statements and API Calls

3.4 更新导入语句及API调用

Search all TypeScript/JavaScript files for imports of

@capacitor/live-updates

(or

cordova-plugin-ionic

) and replace. The Ionic SDK uses two import styles — replace both:

diff

-import * as LiveUpdates from '@capacitor/live-updates';
+import { LiveUpdate } from '@capawesome/capacitor-live-update';

diff

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

If the project uses the legacy Cordova SDK (

cordova-plugin-ionic

), read

references/cordova-sdk-migration.md

for the complete

Deploy

→

LiveUpdate

method mapping, including the granular check-download-extract-reload pattern and native config cleanup.

Replace all references to the

LiveUpdates

class (or

Deploy

class) with

LiveUpdate

(singular).

sync()
return value has changed. The Ionic Capacitor SDK returns

{ activeApplicationPathChanged: boolean }

. The Capawesome SDK returns

{ nextBundleId: string | null }

. Update all code that checks the sync result:

diff

 const result = await LiveUpdate.sync();
-if (result.activeApplicationPathChanged) {
+if (result.nextBundleId) {
   await LiveUpdate.reload();
 }

reload()
has the same signature — no changes needed beyond the class name.

setConfig()
,
getConfig()
, and
resetConfig()
exist but have different signatures (Capacitor 7/8 only, since v7.4.0). The Capawesome SDK splits config and channel management into separate methods:

diff

 // Setting config at runtime
-await LiveUpdates.setConfig({ appId: '456', channel: 'staging', maxVersions: 5 });
+await LiveUpdate.setConfig({ appId: '456' });
+await LiveUpdate.setChannel({ channel: 'staging' });

diff

 // Getting config at runtime
-const config = await LiveUpdates.getConfig();
-console.log(config.channel);
+const config = await LiveUpdate.getConfig();   // { appId, autoUpdateStrategy }
+const { channel } = await LiveUpdate.getChannel(); // { channel }

diff

 // Resetting config
-await LiveUpdates.resetConfig();
+await LiveUpdate.resetConfig();

maxVersions

has no runtime equivalent — use

autoDeleteBundles: true

in the static Capacitor config instead.

在所有TypeScript/JavaScript文件中查找

@capacitor/live-updates

（或

cordova-plugin-ionic

）的导入语句并替换。Ionic SDK有两种导入方式，均需替换：

diff

-import * as LiveUpdates from '@capacitor/live-updates';
+import { LiveUpdate } from '@capawesome/capacitor-live-update';

diff

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

如果项目使用旧版Cordova SDK（

cordova-plugin-ionic

），请阅读

references/cordova-sdk-migration.md

了解完整的

Deploy

→

LiveUpdate

方法映射，包括细粒度的检查-下载-提取-重载流程及原生配置清理步骤。

将所有

LiveUpdates

类（或

Deploy

类）的引用替换为

LiveUpdate

（单数形式）。

sync()
返回值已变更：Ionic Capacitor SDK返回

{ activeApplicationPathChanged: boolean }

，而Capawesome SDK返回

{ nextBundleId: string | null }

。更新所有检查sync结果的代码：

diff

 const result = await LiveUpdate.sync();
-if (result.activeApplicationPathChanged) {
+if (result.nextBundleId) {
   await LiveUpdate.reload();
 }

reload()
方法签名一致：除类名变更外，无需其他修改。

setConfig()
、
getConfig()
及
resetConfig()
方法存在但签名不同（仅适用于Capacitor 7/8，插件版本v7.4.0+）。Capawesome SDK将配置与渠道管理拆分为独立方法：

diff

 // 运行时设置配置
-await LiveUpdates.setConfig({ appId: '456', channel: 'staging', maxVersions: 5 });
+await LiveUpdate.setConfig({ appId: '456' });
+await LiveUpdate.setChannel({ channel: 'staging' });

diff

 // 运行时获取配置
-const config = await LiveUpdates.getConfig();
-console.log(config.channel);
+const config = await LiveUpdate.getConfig();   // { appId, autoUpdateStrategy }
+const { channel } = await LiveUpdate.getChannel(); // { channel }

diff

 // 重置配置
-await LiveUpdates.resetConfig();
+await LiveUpdate.resetConfig();

maxVersions

无运行时等效配置——改用静态Capacitor配置中的

autoDeleteBundles: true

。

3.5 Add Always-Latest Update Logic (Capacitor 7/8 Only)

3.5 添加始终最新更新逻辑（仅适用于Capacitor 7/8）

If the previous Ionic Appflow

autoUpdateMethod

was

always

, add a

nextBundleSet

listener to prompt the user when an update is ready. 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.

如果之前Ionic Appflow的

autoUpdateMethod

设置为

always

，添加

nextBundleSet

监听器，在更新就绪时提示用户。在应用初始化早期添加以下代码：

typescript

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

LiveUpdate.addListener('nextBundleSet', async (event) => {
  if (event.bundleId) {
    const shouldReload = confirm('有新更新可用，是否立即安装？');
    if (shouldReload) {
      await LiveUpdate.reload();
    }
  }
});

请完全复制此代码片段，请勿简化或省略

confirm()

对话框。

3.6 Migrate Force Update Logic (If Applicable)

3.6 迁移强制更新逻辑（如适用）

If the project implements a "Force Update" pattern (extending the splash screen until the update completes), migrate it as follows:

diff

 import { SplashScreen } from '@capacitor/splash-screen';
-import * as LiveUpdates from '@capacitor/live-updates';
+import { LiveUpdate } from '@capawesome/capacitor-live-update';

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

This pattern may impact user experience on slow connections. Consider migrating to the background update strategy instead.

如果项目实现了“强制更新”模式（在更新完成前保持启动页显示），按以下方式迁移：

diff

 import { SplashScreen } from '@capacitor/splash-screen';
-import * as LiveUpdates from '@capacitor/live-updates';
+import { LiveUpdate } from '@capawesome/capacitor-live-update';

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

此模式可能在网络连接缓慢时影响用户体验，建议改用后台更新策略。

3.7 Add Manual Update Logic (Capacitor 6 Only)

3.7 添加手动更新逻辑（仅适用于Capacitor 6）

Capacitor 6 does not support

autoUpdateStrategy

. If the project uses Capacitor 6, add manual sync logic:

typescript

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

void LiveUpdate.ready();

App.addListener('resume', async () => {
  const { nextBundleId } = await LiveUpdate.sync();
  if (nextBundleId) {
    const shouldReload = confirm('A new update is available. Install now?');
    if (shouldReload) {
      await LiveUpdate.reload();
    }
  }
});

Capacitor 6不支持

autoUpdateStrategy

。如果项目使用Capacitor 6，添加手动同步逻辑：

typescript

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

void LiveUpdate.ready();

App.addListener('resume', async () => {
  const { nextBundleId } = await LiveUpdate.sync();
  if (result.nextBundleId) {
    const shouldReload = confirm('有新更新可用，是否立即安装？');
    if (shouldReload) {
      await LiveUpdate.reload();
    }
  }
});

3.8 Add Rollback Protection (Recommended)

3.8 添加回滚保护（推荐）

Add

readyTimeout

and

autoBlockRolledBackBundles

to the

LiveUpdate

config:

typescript

LiveUpdate: {
  appId: '<CAPAWESOME_APP_ID>',
  autoUpdateStrategy: 'background', // Capacitor 7/8 only
  readyTimeout: 10000,
  autoBlockRolledBackBundles: true,
}

Call

ready()

as early as possible in app startup:

typescript

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

void LiveUpdate.ready();

在

LiveUpdate

配置中添加

readyTimeout

和

autoBlockRolledBackBundles

：

typescript

LiveUpdate: {
  appId: '<CAPAWESOME_APP_ID>',
  autoUpdateStrategy: 'background', // 仅适用于Capacitor 7/8
  readyTimeout: 10000,
  autoBlockRolledBackBundles: true,
}

在应用启动早期调用

ready()

：

typescript

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

void LiveUpdate.ready();

3.9 Configure iOS Privacy Manifest

3.9 配置iOS隐私清单

Add to

ios/App/PrivacyInfo.xcprivacy

inside the

NSPrivacyAccessedAPITypes

array:

xml

<dict>
  <key>NSPrivacyAccessedAPIType</key>
  <string>NSPrivacyAccessedAPICategoryUserDefaults</string>
  <key>NSPrivacyAccessedAPITypeReasons</key>
  <array>
    <string>CA92.1</string>
  </array>
</dict>

在

ios/App/PrivacyInfo.xcprivacy

的

NSPrivacyAccessedAPITypes

数组中添加以下内容：

xml

<dict>
  <key>NSPrivacyAccessedAPIType</key>
  <string>NSPrivacyAccessedAPICategoryUserDefaults</string>
  <key>NSPrivacyAccessedAPITypeReasons</key>
  <array>
    <string>CA92.1</string>
  </array>
</dict>

3.10 Sync the Capacitor Project

3.10 同步Capacitor项目

bash

npx cap sync

bash

npx cap sync

Step 4: Migrate Native Builds

步骤4：迁移原生构建功能

Skip this step if Native Builds was not detected or the user chose not to migrate it.

Native build setup in Capawesome Cloud requires connecting a Git repository, uploading signing certificates, configuring environments, and triggering builds. Use the

capawesome-cloud

skill — follow the Native Builds section starting from "Connect Git Repository." Specifically, read the

capawesome-cloud

skill's

references/native-builds.md

for the full procedure.

Remove any Ionic Appflow build commands from CI/CD configuration files after verifying that Capawesome Cloud builds work correctly (see Step 6 for CI/CD migration).

如果未检测到原生构建功能，或用户选择不迁移该功能，可跳过此步骤。

Capawesome Cloud中的原生构建设置需要连接Git仓库、上传签名证书、配置环境并触发构建。请使用

capawesome-cloud

技能，遵循原生构建章节中从“连接Git仓库”开始的流程。具体请阅读

capawesome-cloud

技能中的

references/native-builds.md

获取完整步骤。

在验证Capawesome Cloud构建功能正常工作后，从CI/CD配置文件中移除所有Ionic Appflow构建命令（CI/CD迁移见步骤6）。

Step 5: Migrate App Store Publishing

步骤5：迁移应用商店发布功能

Skip this step if App Store Publishing was not detected or the user chose not to migrate it.

App store publishing setup requires creating destinations and configuring credentials for Apple App Store and/or Google Play Store. Use the

capawesome-cloud

skill — follow the App Store Publishing section. Specifically, read the

capawesome-cloud

skill's

references/app-store-publishing.md

for the full procedure.

Remove any Ionic Appflow deploy commands from CI/CD configuration files after verifying that Capawesome Cloud deployments work correctly (see Step 6 for CI/CD migration).

如果未检测到应用商店发布功能，或用户选择不迁移该功能，可跳过此步骤。

应用商店发布设置需要创建发布目标，并为Apple App Store和/或Google Play Store配置凭据。请使用

capawesome-cloud

技能，遵循应用商店发布章节的流程。具体请阅读

capawesome-cloud

技能中的

references/app-store-publishing.md

获取完整步骤。

在验证Capawesome Cloud发布功能正常工作后，从CI/CD配置文件中移除所有Ionic Appflow发布命令（CI/CD迁移见步骤6）。

Step 6: Update CI/CD Pipelines

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

Skip this step if the project has no CI/CD pipeline or uses Ionic Appflow's built-in build/deploy features without external CI/CD.

Use the following CLI command mapping as a reference when replacing Appflow commands:

Appflow CLI Command	Capawesome CLI Equivalent
`appflow live-update upload-artifact`	`npx @capawesome/cli apps:liveupdates:upload`
`appflow live-update create-channel`	`npx @capawesome/cli apps:channels:create`
`appflow live-update delete-channel`	`npx @capawesome/cli apps:channels:delete`
`appflow live-update list-channels`	`npx @capawesome/cli apps:channels:list`
`appflow live-update download-artifact`	`npx @capawesome/cli apps:liveupdates:download`
`appflow live-update set-native-versions`	Use versioned channels or `--android-min` / `--ios-min` flags on upload
`appflow build`	`npx @capawesome/cli apps:builds:create`
`appflow deploy`	`npx @capawesome/cli apps:deployments:create`

如果项目没有CI/CD流水线，或仅使用Ionic Appflow内置的构建/发布功能而无外部CI/CD，可跳过此步骤。

替换Appflow命令时，可参考以下CLI命令映射：

Appflow CLI命令	Capawesome CLI等效命令
`appflow live-update upload-artifact`	`npx @capawesome/cli apps:liveupdates:upload`
`appflow live-update create-channel`	`npx @capawesome/cli apps:channels:create`
`appflow live-update delete-channel`	`npx @capawesome/cli apps:channels:delete`
`appflow live-update list-channels`	`npx @capawesome/cli apps:channels:list`
`appflow live-update download-artifact`	`npx @capawesome/cli apps:liveupdates:download`
`appflow live-update set-native-versions`	使用版本化渠道，或在上传时添加 `--android-min` / `--ios-min` 参数
`appflow build`	`npx @capawesome/cli apps:builds:create`
`appflow deploy`	`npx @capawesome/cli apps:deployments:create`

6.1 Replace Authentication

6.1 替换身份验证方式

Replace Ionic Appflow authentication with Capawesome Cloud token-based auth:

diff

-# Ionic Appflow authentication
-IONIC_TOKEN: ${{ secrets.IONIC_TOKEN }}
+# Capawesome Cloud authentication
+- run: npx @capawesome/cli login --token ${{ secrets.CAPAWESOME_CLOUD_TOKEN }}

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

CAPAWESOME_CLOUD_TOKEN

将Ionic Appflow身份验证替换为Capawesome Cloud基于令牌的身份验证：

diff

-# Ionic Appflow身份验证
-IONIC_TOKEN: ${{ secrets.IONIC_TOKEN }}
+# Capawesome Cloud身份验证
+- run: npx @capawesome/cli login --token ${{ secrets.CAPAWESOME_CLOUD_TOKEN }}

在Capawesome Cloud控制台生成令牌，并将其存储为CI/CD密钥，命名为

CAPAWESOME_CLOUD_TOKEN

。

6.2 Replace Build Commands

6.2 替换构建命令

diff

-ionic appflow build android --type release
+npx @capawesome/cli apps:builds:create --app-id <APP_ID> --platform android --type release --git-ref main --certificate "<CERTIFICATE_NAME>" --yes

diff

-ionic appflow build ios --type app-store
+npx @capawesome/cli apps:builds:create --app-id <APP_ID> --platform ios --type app-store --git-ref main --certificate "<CERTIFICATE_NAME>" --yes

Add

--detached

for non-blocking builds in CI/CD pipelines.

diff

-ionic appflow build android --type release
+npx @capawesome/cli apps:builds:create --app-id <APP_ID> --platform android --type release --git-ref main --certificate "<CERTIFICATE_NAME>" --yes

diff

-ionic appflow build ios --type app-store
+npx @capawesome/cli apps:builds:create --app-id <APP_ID> --platform ios --type app-store --git-ref main --certificate "<CERTIFICATE_NAME>" --yes

在CI/CD流水线中添加

--detached

参数实现非阻塞构建。

6.3 Replace Live Update Upload Commands

6.3 替换实时更新上传命令

diff

-ionic appflow deploy web --channel production
+npx @capawesome/cli apps:liveupdates:upload --app-id <APP_ID> --channel production

diff

-ionic appflow deploy web --channel production
+npx @capawesome/cli apps:liveupdates:upload --app-id <APP_ID> --channel production

6.4 Replace App Store Deploy Commands

6.4 替换应用商店发布命令

diff

-ionic appflow deploy android --destination "Google Play"
+npx @capawesome/cli apps:deployments:create --app-id <APP_ID> --build-number <BUILD_NUMBER> --destination "<DESTINATION_NAME>"

diff

-ionic appflow deploy android --destination "Google Play"
+npx @capawesome/cli apps:deployments:create --app-id <APP_ID> --build-number <BUILD_NUMBER> --destination "<DESTINATION_NAME>"

6.5 Remove Ionic Appflow Dependencies

6.5 移除Ionic Appflow依赖

After verifying the new CI/CD pipeline works:

Remove any
```
@ionic/appflow
```
or Appflow-related npm packages from
```
package.json
```
.
Remove Ionic Appflow environment variables from CI/CD secrets (e.g.,
```
IONIC_TOKEN
```
).
Remove
```
appflow.config.json
```
or similar Appflow configuration files from the project root.

在验证新CI/CD流水线正常工作后：

从
```
package.json
```
中移除所有
```
@ionic/appflow
```
或与Appflow相关的npm包。
从CI/CD密钥中移除Ionic Appflow环境变量（如
```
IONIC_TOKEN
```
）。
从项目根目录中移除
```
appflow.config.json
```
或类似的Appflow配置文件。

Step 7: Test and Verify

步骤7：测试与验证

7.1 Verify Live Updates (if migrated)

7.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
```
.

Check existing channels:

bash

npx @capawesome/cli apps:channels:list --app-id <APP_ID> --json

Create the target channel if missing:

bash

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

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. For Capacitor 7/8 with
```
autoUpdateStrategy: "background"
```
, wait for the update prompt or force-close and reopen the app. For Capacitor 6, switch away from the app and return to trigger a check.

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

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

检查现有渠道：

bash

npx @capawesome/cli apps:channels:list --app-id <APP_ID> --json

如果目标渠道不存在，创建该渠道：

bash

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

上传构建包：

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"
```
的Capacitor 7/8应用，等待更新提示，或强制关闭并重新打开应用。对于Capacitor 6应用，切换出应用再返回以触发更新检查。

7.2 Verify Native Builds (if migrated)

7.2 验证原生构建功能（如已迁移）

Trigger a test build via the Capawesome CLI and verify the build artifact is produced.

通过Capawesome CLI触发测试构建，验证是否生成构建产物。

7.3 Verify App Store Publishing (if migrated)

7.3 验证应用商店发布功能（如已迁移）

Deploy a test build to the configured destination and verify it appears in TestFlight or Google Play Console.

将测试构建部署至配置的发布目标，验证其是否出现在TestFlight或Google Play控制台中。

7.4 Clean Up

7.4 清理工作

After all features are verified:

Confirm all Ionic Appflow SDK packages are removed from
```
package.json
```
.
Confirm all Ionic Appflow configuration is removed from
```
capacitor.config.ts
```
/
```
capacitor.config.json
```
.
Confirm all Ionic Appflow CI/CD commands and environment variables are removed.

在所有功能验证通过后：

确认
```
package.json
```
中已移除所有Ionic Appflow SDK包。
确认
```
capacitor.config.ts
```
/
```
capacitor.config.json
```
中已移除所有Ionic Appflow配置。
确认已移除所有Ionic Appflow CI/CD命令及环境变量。

Error Handling

错误处理

Live Updates

实时更新功能

```
npm uninstall @capacitor/live-updates
```
fails → The package may be listed under a different name. Search
```
package.json
```
for any package containing
```
live-updates
```
from
```
@capacitor
```
scope.
```
npx cap sync
```
fails after plugin swap → Verify the installed
```
@capawesome/capacitor-live-update
```
version matches the Capacitor version in
```
package.json
```
.
App reverts to default bundle after restart →
```
LiveUpdate.ready()
```
is likely not called early enough. Add it as the first call in app initialization.
Updates not detected with
```
autoUpdateStrategy: "background"
```
→ Updates only checked if last check was >15 minutes ago. Force-close and restart the app. Check device logs for Live Update SDK output.

LiveUpdates is not defined

or similar runtime errors → Ensure all imports were updated from

@capacitor/live-updates

@capawesome/capacitor-live-update

and the class name changed from

LiveUpdates

LiveUpdate

```
Deploy is not defined
```
→ The project uses the legacy Cordova SDK (
```
cordova-plugin-ionic
```
). Read
```
references/cordova-sdk-migration.md
```
for the full method mapping.
```
activeApplicationPathChanged is not a property
```
or sync result checks fail → The Capawesome SDK returns
```
{ nextBundleId }
```
instead of
```
{ activeApplicationPathChanged }
```
. Update all sync result checks.
```
setConfig is not a function
```
→
```
setConfig()
```
requires
```
@capawesome/capacitor-live-update
```
v7.4.0+ (Capacitor 7/8 only). For Capacitor 6, remove runtime config calls and set configuration statically in
```
capacitor.config.ts
```
.

```
npm uninstall @capacitor/live-updates
```
执行失败 → 该包可能以其他名称存在。在
```
package.json
```
中搜索
```
@capacitor
```
范围内所有包含
```
live-updates
```
的包。
替换插件后
```
npx cap sync
```
执行失败 → 验证安装的
```
@capawesome/capacitor-live-update
```
版本是否与
```
package.json
```
中的Capacitor版本匹配。
应用重启后恢复至默认构建包 → 可能是
```
LiveUpdate.ready()
```
调用时机过晚。将其添加为应用初始化的第一个调用。
使用
```
autoUpdateStrategy: "background"
```
时未检测到更新 → 更新仅在上次检查超过15分钟后才会触发。强制关闭并重新打开应用，检查设备日志中的实时更新SDK输出。

运行时出现

LiveUpdates is not defined

或类似错误 → 确保所有导入已从

@capacitor/live-updates

替换为

@capawesome/capacitor-live-update

，且类名已从

LiveUpdates

改为

LiveUpdate

。

```
Deploy is not defined
```
→ 项目使用旧版Cordova SDK（
```
cordova-plugin-ionic
```
）。阅读
```
references/cordova-sdk-migration.md
```
了解完整的方法映射。
出现
```
activeApplicationPathChanged is not a property
```
或sync结果检查失败 → Capawesome SDK返回
```
{ nextBundleId }
```
而非
```
{ activeApplicationPathChanged }
```
。更新所有检查sync结果的代码。
```
setConfig is not a function
```
→
```
setConfig()
```
需要
```
@capawesome/capacitor-live-update
```
v7.4.0+（仅适用于Capacitor 7/8）。对于Capacitor 6，移除运行时配置调用，改用
```
capacitor.config.ts
```
中的静态配置。

Native Builds

原生构建功能

Build fails with authentication error → Re-run
```
npx @capawesome/cli login
```
. For CI/CD, verify the
```
CAPAWESOME_CLOUD_TOKEN
```
secret is set correctly.

Build fails with missing signing certificate → Upload certificates via

npx @capawesome/cli apps:certificates:create

. Read the

capawesome-cloud

skill's

references/certificates-android.md

references/certificates-ios.md

Build fails with
```
invalid source release
```
→ Set
```
JAVA_VERSION
```
environment variable in the build environment. Read the
```
capawesome-cloud
```
skill's
```
references/build-troubleshooting.md
```
.

构建因身份验证错误失败 → 重新运行
```
npx @capawesome/cli login
```
。对于CI/CD，验证
```
CAPAWESOME_CLOUD_TOKEN
```
密钥是否正确设置。

构建因缺少签名证书失败 → 通过

npx @capawesome/cli apps:certificates:create

上传证书。阅读

capawesome-cloud

技能中的

references/certificates-android.md

或

references/certificates-ios.md

了解详情。

构建因
```
invalid source release
```
失败 → 在构建环境中设置
```
JAVA_VERSION
```
环境变量。阅读
```
capawesome-cloud
```
技能中的
```
references/build-troubleshooting.md
```
了解详情。

App Store Publishing

应用商店发布功能

Destination creation fails → Verify credentials are correct. Read the

capawesome-cloud

skill's

references/apple-app-store-credentials.md

references/google-play-store-credentials.md

Deployment fails with "build not found" → Ensure the build completed successfully before deploying.

发布目标创建失败 → 验证凭据是否正确。阅读

capawesome-cloud

技能中的

references/apple-app-store-credentials.md

或

references/google-play-store-credentials.md

了解详情。

发布因“构建未找到”失败 → 确保构建已成功完成后再进行发布。

CI/CD

CI/CD流水线

CI/CD pipeline fails after migration → Compare the old and new pipeline configurations side by side. Ensure all Appflow command replacements use the correct Capawesome CLI flags. Check that
```
CAPAWESOME_CLOUD_TOKEN
```
is available as a secret in the CI/CD environment.

迁移后CI/CD流水线失败 → 对比新旧流水线配置，确保所有Appflow命令替换时使用了正确的Capawesome CLI参数。检查CI/CD环境中是否已设置
```
CAPAWESOME_CLOUD_TOKEN
```
密钥。