capawesome-cloud

Capawesome Cloud

使用 Capawesome Cloud 为 Capacitor 和 Cordova 应用设置和管理原生构建、实时更新和应用商店发布。

前提条件

1. 拥有 Capawesome Cloud 账户和组织。
2. 拥有一个 Capacitor 6/7/8 或 Cordova 应用。注意：
   • 实时更新：Capacitor（Android、iOS，以及仅限 Capacitor 8 的 Electron 桌面平台 @capawesome/capacitor-electron）和 Cordova 均支持。
   • 原生构建：支持 Capacitor、Cordova 和原生 iOS/Android 项目。
   • 应用商店发布：与框架无关，可用于通过原生构建生成的任何原生构建产物。
3. 已安装 Node.js 和 npm。
4. 对于原生构建：应用必须位于 Git 仓库中（GitHub、GitLab、Bitbucket 或 Azure DevOps）。
5. 对于 Apple App Store 发布：拥有有效的 Apple Developer Program 会员资格，并在 App Store Connect 中创建了应用。
6. 对于 Google Play Store 发布：拥有 Google Play Developer 账户，并在 Google Play Console 中创建应用，且至少手动上传了一个版本。

通用规则

首次运行任何 @capawesome/cli 命令前，请先使用 --help 标志运行，以查看所有可用选项。

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：通过 Capawesome Cloud 进行身份验证

npx @capawesome/cli login

对于 CI/CD，请使用基于令牌的身份验证：

npx @capawesome/cli login --token <token>

步骤 2：在 Capawesome Cloud 中创建应用

如果用户已有应用 ID，则跳过此步骤。

npx @capawesome/cli apps:create

CLI 会提示输入组织和应用名称，然后输出应用 ID（UUID）。请保存此 ID，以便在后续步骤中使用。

应用类型默认为 capacitor。对于 Cordova 应用，请传入 --type cordova（允许的值：android、capacitor、cordova、ios）：

npx @capawesome/cli apps:create --type cordova

步骤 3：确定所需功能

询问用户要设置哪些 Capawesome Cloud 功能：

1. 原生构建 — 在云端构建 iOS 和 Android 应用。
2. 实时更新 — 向已部署的应用推送 OTA Web 更新。
3. 应用商店发布 — 自动提交到 Apple App Store 或 Google Play Store。

用户可以选择一项或多项功能。继续查看下方相应章节。

原生构建

请阅读 references/native-builds.md，了解完整的原生构建设置和使用流程。内容包括：

• 连接 Git 仓库
• 上传签名证书（Android 密钥库、iOS .p12 和配置描述文件）
• 配置环境和密钥
• 配置构建设置（monorepo、自定义构建命令）
• 触发构建
• 监控和下载构建产物
• 使用 Trapeze 配置原生配置覆盖
• 设置 CI/CD 流水线

实时更新

先阅读 references/live-updates.md——它会检测所用框架（Capacitor 或 Cordova），并引导至相应的流程（live-updates-capacitor.md 或 live-updates-cordova.md）。这两份流程文档都涵盖：

• 安装实时更新插件（Capacitor 对应 @capawesome/capacitor-live-update，Cordova 对应 @capawesome/cordova-live-update）
• 配置插件（Capacitor 配置或 Cordova config.xml 首选项）
• 添加回滚保护
• 添加更新逻辑（始终使用最新版本、手动同步、强制更新）
• 配置 iOS 隐私清单
• 配置版本处理（版本化频道、版本化捆绑包）
• 在 Electron 桌面平台启用实时更新（仅限 Capacitor）
• 测试设置

应用商店发布

阅读 references/app-store-publishing.md，了解完整的应用商店发布设置和使用流程。内容包括：

• 创建 Apple App Store 目标（使用 API Key 或 Apple ID 认证）
• 创建 Google Play Store 目标
• 将构建部署到目标
• 一步完成构建和部署

错误处理

原生构建

• invalid source release: 21 → 将 JAVA_VERSION 环境变量设为 17 或 21。请阅读 references/build-troubleshooting.md。
• JavaScript heap out of memory → 将 NODE_OPTIONS 环境变量设为 --max-old-space-size=4096。请阅读 references/build-troubleshooting.md。
• 认证错误 → 重新运行 npx @capawesome/cli login。对于 CI/CD，请验证令牌。
• 缺少签名证书 → 通过 apps:certificates:create 上传。请阅读 references/certificates-android.md 或 references/certificates-ios.md。
• 配置描述文件过期 → 在 Apple Developer Portal 中重新生成并重新上传。请阅读 references/certificates-ios.md。
• Web 构建步骤失败 → 确保 package.json 中包含 capawesome:build 或 build 脚本。请阅读 references/build-configuration.md。

实时更新

• npx cap sync 失败（Capacitor）→ 确认插件版本与 package.json 中的 Capacitor 版本匹配。
• 未应用捆绑包 → 确保在 readyTimeout/READY_TIMEOUT 超时前调用 ready()。
• 重启后应用恢复到默认捆绑包 → 可能未调用 ready()。请在应用初始化早期添加该调用（在 Cordova 中，放在 deviceready 监听器内）。
• 上传认证错误 → 重新运行 npx @capawesome/cli login。
• 使用 autoUpdateStrategy: "background" / AUTO_UPDATE_STRATEGY=background 时未检测到更新 → 仅当距离上次检查超过 15 分钟时才会检查更新。请强制关闭应用并重新启动。
• **Cordova：**首选项更改无效 → Cordova 只会在添加平台时读取首选项。请运行 cordova platform rm <platform>，然后运行 cordova platform add <platform>。
• **Cordova：**更新始终无法应用 / WebView 错误 → 该插件需要默认的自定义 WebView 方案。确保 config.xml 未设置 Scheme=file 或 AndroidInsecureFileModeEnabled=true。
• Electron：npx cap sync electron 无效 → 该命令解析到了无关的 electron npm 包。请运行 npx cap sync @capawesome/capacitor-electron。
• **Electron：**未交付 manifest 捆绑包 → Electron 设备只会接收 zip 捆绑包。请使用默认的 --artifact-type zip 上传。
• **Electron：**每次发布报告的应用版本都是 0.0.0 → 每次桌面版发布时都要递增 electron/package.json 中的 version；该版本号用于版本约束和版本化频道。
• 请阅读 references/live-update-plugin-api.md，查看完整的 SDK API 参考。
• 请阅读 references/live-update-faq.md，了解合规、计费和限制。

App Store 发布

• 身份验证错误 → 重新运行 npx @capawesome/cli login。
• 创建目标失败 → 验证凭据。请阅读 references/apple-app-store-credentials.md 或 references/google-play-store-credentials.md。
• iOS 构建未显示在 TestFlight 中 → 构建处理可能需要一些时间。常见原因：未递增构建号、Info.plist 中缺少隐私描述、权限不足。
• Google Play 部署失败 → 确保已手动上传首个版本。验证服务账号是否具有发布权限。
• 部署超时 → 使用 --detached 标志，并通过 apps:deployments:logs 查看日志。
• apps:deployments:create 失败并显示“build not found” → 确保构建已成功完成。
• 取消卡住的部署 → npx @capawesome/cli apps:deployments:cancel --app-id <APP_ID> --deployment-id <DEPLOYMENT_ID>。

相关技能

• capacitor-app-development — 适用于 Capacitor 开发常见主题、CI/CD 模式和故障排除。
• capawesome-cli — 适用于 Capawesome CLI 完整命令参考、项目配置和 CI/CD 集成详情。
• capacitor-plugins — 适用于安装和配置 Capacitor 插件，包括 @capawesome/capacitor-live-update 插件。
• capacitor-platforms — 适用于添加和配置接收 Live Updates 的 @capawesome/capacitor-electron 桌面平台。
• ionic-appflow-migration — 适用于将现有 Ionic Appflow 项目迁移到 Capawesome Cloud。
• capgo-cloud-migration — 适用于将现有 Capgo 项目迁移到 Capawesome Cloud。
• capacitor-in-app-purchases — 适用于在发布到应用商店前设置应用内购买和订阅。
• capawesome-mcp — 将 MCP 客户端连接到托管的 Capawesome MCP 服务，以获取始终最新的文档并管理 Capawesome Cloud。