capawesome-cloud

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Capawesome Cloud

Set up and manage native builds, live updates, and app store publishing for Capacitor apps using Capawesome Cloud.

为Capacitor应用设置并管理原生构建、实时更新及应用商店发布，使用Capawesome Cloud即可实现。

Prerequisites

前提条件

A Capawesome Cloud account and organization.
A Capacitor 6, 7, or 8 app.
Node.js and npm installed.
For Native Builds: The app must be in a Git repository (GitHub, GitLab, Bitbucket, or Azure DevOps).
For Apple App Store Publishing: An active Apple Developer Program membership and an app created in App Store Connect.
For Google Play Store Publishing: A Google Play Developer account and an app created in Google Play Console with at least one version uploaded manually.

拥有Capawesome Cloud账号及组织。
一个Capacitor 6、7或8版本的应用。
已安装Node.js和npm。
若使用原生构建：应用需托管在Git仓库中（GitHub、GitLab、Bitbucket或Azure DevOps均可）。
若使用Apple App Store发布：拥有有效的Apple Developer Program会员资格，且已在App Store Connect中创建应用。
若使用Google Play Store发布：拥有Google Play Developer账号，且已在Google Play Console中创建应用并至少手动上传过一个版本。

General Rules

通用规则

Before running any

@capawesome/cli

command for the first time, run it with the

--help

flag to review all available options.

首次运行任何

@capawesome/cli

命令前，请添加

--help

参数查看所有可用选项。

Procedures

操作步骤

Step 1: Authenticate with Capawesome Cloud

步骤1：登录Capawesome Cloud

bash

npx @capawesome/cli login

For CI/CD, use token-based auth:

bash

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

bash

npx @capawesome/cli login

对于CI/CD环境，使用基于令牌的认证：

bash

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

Step 2: Create an App in Capawesome Cloud

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

Skip if the user already has an app ID.

bash

npx @capawesome/cli apps:create

The CLI prompts for organization and app name, then outputs the app ID (UUID). Save for subsequent steps.

若用户已有应用ID，可跳过此步骤。

bash

npx @capawesome/cli apps:create

CLI会提示输入组织名称和应用名称，之后输出应用ID（UUID格式）。请保存该ID用于后续步骤。

Step 3: Identify Required Feature(s)

步骤3：确定所需功能

Ask the user which Capawesome Cloud feature(s) to set up:

Native Builds — Build iOS and Android apps in the cloud.
Live Updates — Push OTA web updates to deployed apps.
App Store Publishing — Automate submissions to Apple App Store or Google Play Store.

The user may select one or more features. Proceed to the corresponding sections below.

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

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

用户可选择一个或多个功能，之后进入对应章节操作。

Native Builds

原生构建

Read

references/native-builds.md

for the full native builds setup and usage procedure. This covers:

Connecting a Git repository
Uploading signing certificates (Android keystores, iOS .p12 + provisioning profiles)
Configuring environments and secrets
Configuring build settings (monorepos, custom build commands)
Triggering builds
Monitoring and downloading build artifacts
Configuring native configuration overwriting with Trapeze
Setting up CI/CD pipelines

完整的原生构建设置及使用流程请查看

references/native-builds.md

。内容包括：

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

Live Updates

实时更新

Read

references/live-updates.md

for the full live updates setup and usage procedure. This covers:

Installing the
```
@capawesome/capacitor-live-update
```
plugin
Configuring the plugin in Capacitor config
Adding rollback protection
Adding update logic (Always Latest, Manual Sync, Force Update)
Configuring iOS Privacy Manifest
Configuring version handling (versioned channels, versioned bundles)
Testing the setup

完整的实时更新设置及使用流程请查看

references/live-updates.md

。内容包括：

安装
```
@capawesome/capacitor-live-update
```
插件
在Capacitor配置中配置该插件
添加回滚保护
添加更新逻辑（始终获取最新版本、手动同步、强制更新）
配置iOS隐私清单
配置版本管理（版本化渠道、版本化包）
测试设置

App Store Publishing

应用商店发布

Read

references/app-store-publishing.md

for the full app store publishing setup and usage procedure. This covers:

Creating Apple App Store destinations (API Key or Apple ID auth)
Creating Google Play Store destinations
Deploying builds to destinations
Building and deploying in one step

完整的应用商店发布设置及使用流程请查看

references/app-store-publishing.md

。内容包括：

创建Apple App Store发布目标（API密钥或Apple ID认证）
创建Google Play Store发布目标
将构建版本部署至目标平台
一键完成构建与部署

Error Handling

错误处理

Native Builds

原生构建

invalid source release: 21

→ Set

JAVA_VERSION

env var to

. Read

references/build-troubleshooting.md

JavaScript heap out of memory

→ Set

NODE_OPTIONS

env var to

--max-old-space-size=4096

. Read

references/build-troubleshooting.md

Authentication errors → Re-run
```
npx @capawesome/cli login
```
. For CI/CD, verify the token.

Missing signing certificate → Upload via

apps:certificates:create

. Read

references/certificates-android.md

references/certificates-ios.md

Expired provisioning profile → Regenerate in Apple Developer Portal and re-upload. Read
```
references/certificates-ios.md
```
.

Web build step fails → Ensure

package.json

has

capawesome:build

build

script. Read

references/build-configuration.md

invalid source release: 21

→ 将

JAVA_VERSION

环境变量设置为

或

。请查看

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开发者中心重新生成并上传。请查看
```
references/certificates-ios.md
```
。
网页构建步骤失败 → 确保
```
package.json
```
中包含
```
capawesome:build
```
或
```
build
```
脚本。请查看
```
references/build-configuration.md
```
。

Live Updates

实时更新

```
npx cap sync
```
fails → Verify plugin version matches Capacitor version in
```
package.json
```
.
Bundles not applied → Ensure
```
LiveUpdate.ready()
```
is called before
```
readyTimeout
```
expires.
App reverts to default bundle after restart →
```
ready()
```
likely not called. Add it early in app init.
Upload auth errors → Re-run
```
npx @capawesome/cli login
```
.
Updates not detected with
```
autoUpdateStrategy: "background"
```
→ Updates only checked if last check was >15 min ago. Force-close and restart.
Read
```
references/live-update-plugin-api.md
```
for the full SDK API reference.
Read
```
references/live-update-faq.md
```
for compliance, billing, and limitations.

```
npx cap sync
```
执行失败 → 验证
```
package.json
```
中插件版本与Capacitor版本是否匹配。
包未生效 → 确保在
```
readyTimeout
```
过期前调用了
```
LiveUpdate.ready()
```
。
应用重启后恢复至默认包 → 可能未调用
```
ready()
```
，请在应用初始化早期添加该调用。
上传认证错误 → 重新运行
```
npx @capawesome/cli login
```
。
使用
```
autoUpdateStrategy: "background"
```
时未检测到更新 → 仅当上次检查时间超过15分钟时才会检查更新，可强制关闭并重启应用。
完整SDK API参考请查看
```
references/live-update-plugin-api.md
```
。
合规性、计费及限制相关问题请查看
```
references/live-update-faq.md
```
。

App Store Publishing

应用商店发布

Authentication errors → Re-run
```
npx @capawesome/cli login
```
.

Destination creation fails → Verify credentials. Read

references/apple-app-store-credentials.md

references/google-play-store-credentials.md

iOS build not appearing in TestFlight → Build processing may take time. Common causes: build number not incremented, missing Privacy Descriptions in
```
Info.plist
```
, insufficient permissions.
Google Play deployment fails → Ensure first version was uploaded manually. Verify service account has Release permissions.
Deployment timeout → Use
```
--detached
```
flag and check logs with
```
apps:deployments:logs
```
.
```
apps:deployments:create
```
fails with "build not found" → Ensure the build completed successfully.

Cancel a stuck deployment →

npx @capawesome/cli apps:deployments:cancel --app-id <APP_ID> --deployment-id <DEPLOYMENT_ID>

认证错误 → 重新运行
```
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>

。