ionic-appflow-migration

Ionic Appflow 迁移

将现有的 Ionic Appflow 项目迁移到 Capawesome Cloud。

大部分迁移工作都可以自动完成：Ionic Appflow 可以将一个组织导出为 zip 文件，Capawesome CLI 则可通过一条命令导入其中的应用、签名证书、环境、实时更新渠道、原生配置、应用商店目标和构建自动化设置。剩余工作包括替换应用中的 Live Update SDK、连接 Git 提供商，以及更新 CI/CD 流水线。

Ionic Appflow 将于 2027 年 12 月 31 日终止服务，并且已于 2025 年 2 月停止接受新客户。现有客户可以继续使用服务，直至关闭日期，但每个 Appflow 项目都需要制定迁移计划——尽早迁移可为逐步、低风险地推出迁移留出余地。

此迁移的官方指南是从 Ionic Appflow 迁移。如果本技能中的内容与该指南有冲突，请以文档为准。

前提条件

1. 一个当前使用 Ionic Appflow 的 Capacitor 6、7 或 8 应用。对于纯 Cordova 应用（不包含 Capacitor），请改为将实时更新迁移到 Cordova Live Update SDK（@capawesome/cordova-live-update）——导入步骤和所有 Capawesome Cloud 步骤同样适用。
2. 已安装 Node.js 18+ 和 npm。
3. 可以访问项目的源代码仓库。
4. 拥有 Capawesome Cloud 账户和组织。
5. 拥有 Ionic Appflow 组织的管理员权限——创建导出文件时必需。如果没有该权限，请跳过步骤 3 至 7，改用手动备选方案。

硬性规则：绝不读取导出文件

Ionic Appflow 导出文件包含完整的凭据转储——环境机密、密钥库和 .p12 密码、配置描述文件、Google 服务账号私钥，以及 Apple 应用专用密码，全部以明文存储。**将导出 zip 文件视为不透明文件。**以下规则优先于本技能中的所有其他指示：

• 绝不解压、提取、打开、读取、cat、grep、列出、解析或检查导出 zip 文件或其中的任何文件——包括 manifest.json、app-detail.json、其他任何 JSON、密钥库、.p12 文件、.mobileprovision 文件和 json-key.json——不得使用任何工具（Shell 命令、文件读取或代码）执行这些操作。不要“检查”其结构，也不要在其中查找应用名称或 ID。
• 绝不打印、记录、粘贴、概述或存储导出文件的任何内容，也绝不要求用户将导出文件内容、机密值或密码粘贴到聊天中。
• 唯一允许对导出文件进行的操作，是将其路径传递给 npx @capawesome/cli apps:import --file <path>，并读取 CLI 自身输出的摘要。该摘要只包含非敏感值（应用名称、资源数量、警告和重命名信息）。使用 --dry-run 获取 --include 所需的应用名称和 ID——绝不要读取 zip 文件本身。
• 同一规则也适用于手动备选方案：绝不打开密钥库、.p12 文件、配置描述文件、服务账号密钥或环境机密值。向用户索取文件路径，并将其传递给 CLI（例如 apps:certificates:create --file、apps:environments:set --secret-file），不要打开这些文件。密码和机密值必须由用户直接提供给 CLI——通过其交互式提示，或在用户自己的 Shell 中提供——Agent 绝不能输入、回显或转述这些值。
• 迁移完成后，提醒用户删除导出 zip 文件。Agent 不得自行删除、移动、复制或重命名该文件。

通用规则

• 首次运行任何 @capawesome/cli 命令前，先使用 --help 标志运行该命令，以查看所有可用选项。
• 导入操作只能运行一次。 再次运行不会更新现有应用，而是会创建重命名的副本。导入前请完成步骤 2（Git 连接）。
• 切勿提交导出 zip，也不要将其添加到仓库中，即使只是暂时添加也不行。
• 在对应的 Capawesome Cloud 功能完全设置并验证之前，不要移除 Ionic Appflow 配置。导入不会更改 Ionic Appflow 中的任何内容，因此在迁移期间，两个平台可以并行运行。
• 进行任何更改前，请从 package.json（@capacitor/core）中确定 Capacitor 版本，因为这会影响要使用的插件版本和更新策略。

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：检测 Ionic Appflow 使用情况

扫描项目，确定正在使用哪些 Appflow 功能。这将决定后续哪些步骤适用——导入操作本身始终涵盖 Capawesome Cloud 这一侧。

1.1 检查 Live Updates

搜索以下标记：

1. package.json（dependencies 或 devDependencies）中的 @capacitor/live-updates。
2. package.json 中的 cordova-plugin-ionic——这是 Ionic Live Updates 的旧版 Cordova SDK。
3. capacitor.config.ts 或 capacitor.config.json 中 plugins 对象里的 LiveUpdates 键。
4. TypeScript/JavaScript 源文件中对 @capacitor/live-updates 或 cordova-plugin-ionic 的导入。

如果发现任何标记，则将 Live Updates 标记为正在使用。同时记录所用的 SDK（@capacitor/live-updates 或 cordova-plugin-ionic）。

记录当前配置值：appId（Ionic Appflow 应用 ID）、autoUpdateMethod（background、always 或 none）、channel、enabled 和 maxVersions。

1.2 检查 Native Builds

搜索以下标记：

1. CI/CD 配置文件（例如 .github/workflows/*.yml、.gitlab-ci.yml、bitrise.yml、Jenkinsfile、azure-pipelines.yml）中的 Appflow CLI 构建调用。Appflow CLI 二进制文件名为 appflow（旧版：ionic-cloud），因此请搜索 appflow build 和 ionic-cloud build。
2. CI/CD 文件或脚本中对 dashboard.ionicframework.com 或 appflow.ionic.io 的引用。
3. 项目根目录中的 appflow.config.json、.appflow.yaml 或类似的 Appflow 配置文件。

如果发现任何标记，则将 Native Builds 标记为正在使用。

1.3 检查是否使用 App Store 发布

搜索以下信号：

1. CI/CD 配置文件中是否调用了 Appflow CLI 商店部署命令——搜索 appflow deploy android、appflow deploy ios 和旧版 ionic-cloud deploy（注意：appflow deploy web 会将实时更新部署到某个频道，属于 Live Updates，而非 App Store 发布）。
2. 是否配置了用于提交到应用商店的 Appflow 部署目标（例如，appflow destination 命令，或通过 --destination 引用的商店目标）。

如果发现任何信号，则标记 App Store 发布 正在使用。

1.4 呈现检查结果

向用户呈现检测到的功能，并询问：

1. 要迁移哪些功能（所有检测到的功能，或其中一部分）。
2. 用户是否拥有 Ionic Appflow 组织的管理员访问权限。如果没有，请继续参阅手动备用方案。

步骤 2：准备 Capawesome Cloud

2.1 安装并验证 CLI 身份

npx @capawesome/cli login

apps:import 命令需要 Capawesome CLI 4.21.0 或更高版本。使用 npx @capawesome/cli --version 检查版本；如果已安装的版本较旧，请升级。

2.2 连接 Git 提供商（导入前）

导入会关联每个应用的 Git 仓库，但前提是目标组织已连接对应的提供商。如果没有连接，导入会发出警告并继续，但不会关联这些仓库；之后必须逐一手动关联。

请用户在Capawesome Cloud Console的组织级别连接应用仓库所用的提供商——GitHub、GitLab、Bitbucket、Azure DevOps、Gitea 或通过 HTTP/S 访问的 Git 服务器。有关各提供商的具体设置，请参阅集成。

请等待用户确认后再继续。导入后无法完成此操作，除非进行手动返工。

2.3 不要手动创建应用

不要运行 apps:create。导入会从导出文件中创建所有应用。如果提前创建应用，会导致名称冲突，导入的应用会被加上数字后缀重命名（例如 prod (2)）。

步骤 3：导出 Ionic Appflow 组织

无法通过 CLI 启动导出。请指示用户在 Appflow Dashboard 中执行以下步骤：

1. 打开 Ionic Appflow Dashboard 并选择组织。
2. 前往 Settings → Account。
3. 在 Organization export 部分，点击 Export。
4. 导出完成后，点击 Download 保存 zip 文件。

导出文件包含该组织的所有应用，而不仅是当前项目中的应用。

zip 文件包含明文敏感数据——环境密钥、带密码的签名证书以及商店凭据。请告知用户将文件存放在仓库之外，绝不要提交该文件，并在迁移完成后将其删除。

请用户提供下载的 zip 文件在本地的路径，并在下文将其用作 <EXPORT_ZIP>。

**硬性规定：**不要打开、解压、列出或检查 <EXPORT_ZIP>——只将路径传递给 CLI，不做其他操作。

步骤 4：预览导入

务必先运行试运行。它不会创建任何内容，只会准确打印实际导入将执行的操作：

npx @capawesome/cli apps:import --file <EXPORT_ZIP> --dry-run

硬性规则： 试运行是了解导出内容的唯一方式。切勿解压或读取导出文件来查找应用名称、ID 或任何其他值。

CLI 会提示选择目标组织。选项：

选项	用途
--file <path>	导出文件（.zip）的路径。省略时会提示输入。
--organization-id <id>	目标组织。省略时会提示输入；在非交互环境中为必需项。
--include <apps>	仅导入导出文件中的指定应用，可按名称或 ID 指定。可重复使用或以逗号分隔。默认导入所有应用。
--ionic-app-type <capacitor|cordova>	用于确定以模糊应用类型 ionic 导出的应用类型。省略时会针对每个应用提示输入；在非交互环境中为必需项，否则会跳过这些应用。
--dry-run	预览操作，不创建任何资源。
--json	以 JSON 格式打印摘要。

省略 --include 且导出文件包含多个应用时，CLI 会以交互方式提示选择要导入的应用（默认全选）。由于导出文件包含整个组织，如果用户只需要特定应用，建议使用 --include：

npx @capawesome/cli apps:import --file <EXPORT_ZIP> --include "My App,My Other App" --dry-run

继续之前，请与用户一起检查打印出的表格和警告。现在能轻松解决的问题，应尽早处理——尤其是缺少 Git 连接的情况（步骤 2.2）。

步骤 5：运行导入

重复步骤 4 中的准确命令——包括任何 --include、--organization-id 和 --ionic-app-type 值——只移除 --dry-run：

npx @capawesome/cli apps:import --file <EXPORT_ZIP> [--include <apps>] [--organization-id <id>] [--ionic-app-type <type>]

硬性规则： CLI 会读取导出文件，Agent 绝不会读取。只能依据打印出的摘要进行操作。

每个应用的导入内容如下：

Ionic Appflow	Capawesome Cloud	备注
应用	应用	名称冲突和仅大小写不同的重复项会添加数字后缀（例如 prod (2)）
Live 更新渠道	渠道	概念相同，命名方式同样灵活
环境（变量和机密）	环境	变量和机密都会导入
签名证书	签名证书	密钥库、.p12 文件和预配描述文件
原生配置	配置	应用名称和 bundle ID 覆盖项
目标	目标	商店凭据，包括 Google 服务账号密钥
原生和 Web 构建自动化	自动化	包含多个渠道的 Web 自动化会转换为每个渠道各一个自动化
代码库关联	Git 仓库链接	需要步骤 2.2 中已连接的 Git 提供商
最新构建编号	下一个构建编号	新构建会延续 Appflow 构建编号

此命令只运行一次。再次运行会创建第二组已重命名的应用，而不是更新现有应用。

步骤 6：查看导入摘要

CLI 会打印一张表，列出每个应用创建的资源，随后显示每个应用的备注、重命名情况、错误，以及每个已创建应用的 Console URL。如果任何资源导入失败，退出代码为 1。

与用户一起查看输出，并据此采取行动：

消息	操作
重命名（... was renamed to ...）	记录新名称。所有引用旧名称的 CI/CD 工作流、脚本或自动化都必须更新（见步骤 9）。
未导入自动化 Webhook	Capawesome Cloud 支持在应用级别配置 Webhook，而不是在每项自动化中配置。在步骤 7 中添加。
原生配置包含 Live Update 插件设置	这些设置应放在应用本身中（capacitor.config / config.xml），而非 Capawesome Cloud 配置中。在步骤 8 中处理。
不支持 Web 预览	Capawesome Cloud 没有对应的 Web 预览功能。告知用户并移除该功能。
未关联仓库	Git 提供商尚未连接。请先连接，然后在步骤 7 中手动关联仓库。
已跳过 React Native / Flutter 应用	即将支持。在此之前请保留导出文件，稍后使用 --include 仅对这些应用重新运行导入。
已跳过不支持的构建类型 / 未知引用	创建自动化时未包含该值。请在 Console 中手动设置。
单个资源的错误	在 Console 中手动创建导入失败的资源。不要重新运行整个导入。

步骤 7：完成后续手动操作

这些内容无法导入，需要一次性手动设置。向用户列出这些项目，并主动处理可通过 CLI 完成的部分：

1. 关联未关联的仓库 — 在组织级别连接 Git 提供商，然后在每个应用的 Git repository 页面中选择仓库。
2. 添加应用级 Webhook — 如果 Appflow 自动化使用了 Webhook，请在每个应用中单独设置（见 Webhooks）。
3. 添加 App Store Connect API 密钥 — 导入过程只会迁移 Apple ID 凭据。如需自动发布，请在导入的目标中添加 .p8 App Store Connect API 密钥。
4. 为 CI/CD 创建 API 令牌 — Appflow 个人访问令牌不可用。请改为创建 Capawesome Cloud API 令牌（见步骤 9）。
5. 重新创建团队和成员 — 在 Capawesome Cloud Console 中邀请团队成员。

根据设计，以下内容完全不会迁移：构建和部署历史记录、Live Update 部署历史记录、依赖项缓存设置以及 Web 预览。Ionic Appflow 中的应用保持不变。

步骤 8：替换 Live Update SDK

如果未检测到 Live Updates，或用户选择不迁移，则跳过此步骤。

8.1 替换软件包

如果项目使用 @capacitor/live-updates：

npm uninstall @capacitor/live-updates

如果项目使用旧版 Cordova SDK（cordova-plugin-ionic）：

npm uninstall cordova-plugin-ionic

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

• 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

对于纯 Cordova 应用，请跳过 8.2 和 8.3，改为遵循 capawesome-cloud skill 中的 references/live-updates-cordova.md：将插件作为 Cordova 插件（@capawesome/cordova-live-update）添加，通过 config.xml 中的 <preference> 条目进行配置（选项名称与 8.2 中的表格相同），在运行时 deviceready 之后通过 cordova.plugins.LiveUpdate 访问，并使用 cordova prepare 应用。然后继续执行步骤 9。

8.2 更新 Capacitor 配置

在 capacitor.config.ts（或 .json）中，将 LiveUpdates 插件配置替换为 LiveUpdate。使用导入摘要中的 Capawesome Cloud 应用 ID，而不是 Appflow 应用 ID。按以下方式映射选项：

Ionic Appflow（LiveUpdates）	Capawesome Cloud（LiveUpdate）	说明
appId	appId	替换为导入的 Capawesome Cloud 应用 ID
autoUpdateMethod: 'background'	autoUpdateStrategy: 'background'	行为相同
autoUpdateMethod: 'always'	autoUpdateStrategy: 'background'	还需添加 nextBundleSet 监听器
autoUpdateMethod: 'none'	（省略 autoUpdateStrategy）	改用手动同步代码
channel	defaultChannel	值相同
enabled	（移除）	不需要，由代码控制
maxVersions	autoDeleteBundles: true	使用布尔值而不是数字

 // 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,
+      autoBlockRolledBackBundles: true,
+      readyTimeout: 10000
+    }
   }
 };

如果导入结果显示原生配置中包含 Live Update 插件设置，请在此处应用这些值——Capawesome Cloud 配置仅涵盖应用名称和 Bundle ID。

8.3 更新源代码

在编辑任何源文件之前，请先阅读 references/live-update-sdk-migration.md。该文档涵盖导入和 API 变更、sync() 返回值、各策略的代码（background、always、none、强制更新）、回滚保护、原生版本兼容性，以及 iOS 隐私清单。

对于使用旧版 Cordova SDK 的项目，也请阅读 references/cordova-sdk-migration.md，了解完整的 Deploy → LiveUpdate 方法映射和原生配置清理。

最后，同步原生项目：

npx cap sync

第 9 步：更新 CI/CD 流水线

如果项目没有外部 CI/CD 流水线，请跳过此步骤——导入的自动化已会在相同分支上触发构建。

阅读 references/ci-cd-migration.md 并按其说明操作：其中包含完整的 Appflow → Capawesome CLI 命令映射、基于令牌的身份验证，以及移除 Appflow 依赖项的步骤。所有 --app-id 都需要更改；导入期间重命名的资源必须使用新名称引用。

第 10 步：测试和验证

10.1 验证 Live Updates（如已迁移）

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

1. 在应用中做一个小而明显的更改（例如，在标题末尾追加“ - Migration Test”）。
2. 构建 Web 资源：npm run build。
3. 检查现有通道：

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

4. 如果目标通道不存在，则创建该通道：

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

5. 上传 Bundle：

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

6. 撤销明显的更改，重新构建并同步：

   npm run build && npx cap sync
   

7. 打开原生项目（npx cap open ios 或 npx cap open android），并在设备或模拟器上运行。
8. 验证实时更新已应用。使用 autoUpdateStrategy: "background" 时，请等待更新提示，或强制关闭并重新打开应用；也可以切换离开应用，超过 15 分钟后再返回，以触发检查。

10.2 验证原生构建（如已迁移）

触发测试构建并验证是否生成了构建产物：

npx @capawesome/cli apps:builds:create --app-id <APP_ID> --platform ios --git-ref main

10.3 验证应用商店发布（如已迁移）

将测试构建部署到已配置的目标位置，并验证其是否出现在 TestFlight 或 Google Play Console 中：

npx @capawesome/cli apps:deployments:create --app-id <APP_ID> --build-number <BUILD_NUMBER> --destination "<DESTINATION_NAME>"

10.4 清理

验证所有功能后：

1. 确认 package.json 中已移除所有 Ionic Appflow SDK 软件包。
2. 确认已从 capacitor.config.ts/capacitor.config.json 中移除所有 Ionic Appflow 配置。
3. 确认已移除所有 Ionic Appflow CI/CD 命令和环境变量。
4. **提醒用户删除导出的 zip 文件及其所有副本。**Agent 不得自行删除、移动或重命名该文件。

手动回退：在没有组织导出文件的情况下迁移

仅当用户没有 Ionic Appflow 组织的管理员访问权限，或无法获取导出文件时，才使用此路径。所有内容都需要手动重新创建；步骤 1、8、9 和 10 保持不变。

硬性规定：此处同样不得打开凭据文件。请向用户索要密钥库、.p12 文件、配置描述文件和服务账号密钥的文件路径，并将这些路径传给 CLI（--file、--provisioning-profile、--google-service-account-key-file、--apple-api-key-file、--secret-file），不要打开这些文件。让用户在 CLI 的交互式提示中输入密码和机密值，或在自己的 shell 中运行命令——绝不要输入、回显或转发机密信息。

F.1 创建应用

npx @capawesome/cli apps:create

保存返回的应用 ID（UUID）——它将替代 capacitor.config 和所有 CI/CD 命令中的 Appflow 应用 ID。

F.2 重新创建 Live Update 通道

重新创建每个 Appflow Live Update 通道：

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

F.3 重新创建原生构建

连接 Git 仓库，上传签名证书，并配置环境和原生配置。使用 capawesome-cloud skill——按照 原生构建部分中的步骤，从“连接 Git 仓库”开始，并阅读其 references/native-builds.md 了解完整流程。原始值（密钥库和 .p12 密码、环境变量和机密信息）保存在 Appflow Dashboard 中——由用户查找并输入 CLI 提示中。绝不要在聊天中索要这些信息。

F.4 重新创建 App Store 发布

创建目标并配置 Apple App Store 和/或 Google Play Store 凭据。使用 capawesome-cloud skill——按照 App Store 发布部分中的步骤，并阅读其 references/app-store-publishing.md。

F.5 重新创建自动化

重新创建每个 Appflow 构建自动化：

npx @capawesome/cli apps:automations:create --app-id <APP_ID>

然后继续执行步骤 8。

错误处理

导入

• The provided file does not look like an Ionic Appflow export → 请用户确认该文件是从 Settings → Account 下载的组织导出文件，而不是重新压缩的文件夹或仓库归档；如有疑问，请重新下载。不要打开 zip 检查。
• The export file ... has an unexpected format / 格式版本警告 → 更新 CLI（npx @capawesome/cli@latest），然后重新运行试运行。
• No apps found in the export that match the provided filters → --include 的值必须与应用名称或 ID 完全一致。不使用 --include 运行试运行，CLI 会列出可用应用。
• 因应用类型 ionic 不明确而跳过应用 → 传入 --ionic-app-type capacitor 或 --ionic-app-type cordova，或以交互方式运行导入，以便逐个提示应用类型。
• 应用因“尚不支持”（React Native、Flutter）而被跳过 → 这是预期情况。保留导出文件；等支持上线后，使用 --include 重新导入这些应用。
• 导入结束但出现错误（退出代码 1）→ 个别资源创建失败。请在 Console 中手动创建。绝不要为了修复这些问题而重新运行完整导入——这会导致应用重复。
• 误将应用导入两次 → 在 Capawesome Cloud Console 中删除重复应用（apps:delete），然后保留原应用。
• 未关联仓库 → 导入时，组织中没有匹配的 Git 连接。连接提供商后，在每个应用的 Git repository 页面关联仓库。

实时更新

• 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 分钟才会检查更新。强制关闭并重启应用。检查设备日志中的 Live Update 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 或同步结果检查失败 → Capawesome SDK 返回 { nextBundleId }，而不是 { activeApplicationPathChanged }。更新所有同步结果检查。
• 出现 setConfig is not a function → 已安装的插件版本过旧。更新到匹配 dist-tag 的最新版本（Capacitor 8 使用 @latest，7 使用 @v7-lts，6 使用 @v6-lts）。

原生构建

• 构建因身份验证错误而失败 → 重新运行 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 发布

• 创建目标失败 → 确认凭据正确。阅读 capawesome-cloud 技能中的 references/apple-app-store-credentials.md 或 references/google-play-store-credentials.md。
• 部署因 "build not found" 而失败 → 确保构建成功完成后再部署。

CI/CD

• 迁移后流水线失败 → 并排比较新旧流水线配置。检查 --app-id 是否使用新的 Capawesome Cloud 应用 ID、重命名的资源是否通过新名称引用，以及 CAPAWESOME_CLOUD_TOKEN 是否作为密钥可用。

相关技能

• capawesome-cloud — 用于原生构建和 App Store 发布的设置，以及手动备用方案。
• capawesome-cli — 本技能中使用的 Capawesome CLI 的安装、身份验证和 CI/CD 用法。
• ionic-enterprise-sdk-migration — 如果项目还使用已停止维护的 Ionic Enterprise SDK 插件（Auth Connect、Identity Vault、Secure Storage），请使用此技能将它们迁移到 Capawesome 替代方案。
• capgo-cloud-migration — 如果项目是从 Capgo 而非 Ionic Appflow 迁移，请改用此技能。
• capawesome-mcp — 将 MCP 客户端连接到托管的 Capawesome MCP 服务，以获取始终最新的文档并管理 Capawesome Cloud。