capacitor-app-creation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Capacitor App Creation

Capacitor应用创建

Create a new Capacitor app from scratch, including project scaffolding, platform setup, and optional integrations.

从零开始创建全新的Capacitor应用，包含项目脚手架搭建、平台配置以及可选集成项。

Prerequisites

前提条件

Node.js 22+ installed. Verify with
```
node --version
```
.
For iOS: macOS with Xcode 26.0+ installed. Install Xcode Command Line Tools:
```
xcode-select --install
```
.
For Android: Android Studio 2025.2.1+ installed with Android SDK (API 24+).

已安装Node.js 22+，可通过
```
node --version
```
验证版本。
若开发iOS应用：需使用macOS系统，安装Xcode 26.0+，同时安装Xcode命令行工具：
```
xcode-select --install
```
。
若开发Android应用：需安装Android Studio 2025.2.1+，以及Android SDK（API 24+）。

Agent Behavior

Agent行为准则

Guide step-by-step. Walk the user through the process one step at a time. Never present multiple unrelated questions at once.
One decision at a time. When a step requires user input, ask that single question, wait for the answer, then continue.
Present clear options. Provide concrete choices (e.g., "Do you want to add the iOS platform? (yes/no)") instead of open-ended questions.

逐步引导：一次只带领用户完成一个步骤，切勿同时抛出多个不相关的问题。
单次决策：当某个步骤需要用户输入时，仅询问当前单个问题，等待用户答复后再继续后续流程。
提供明确选项：给出具体的选择（例如「你是否需要添加iOS平台？(yes/no)」），而非开放式问题。

Procedures

操作步骤

Step 1: Check for Ionic Framework

步骤1：确认是否使用Ionic Framework

Before creating the app, ask the user:

Do you want to use the Ionic Framework for UI components and theming? (yes/no)

If the user answers yes, stop this skill and switch to the ionic-app-creation
skill instead. If no, continue with Step 2.

创建应用之前，先询问用户：

你是否需要使用Ionic Framework提供UI组件和主题能力？(yes/no)

若用户回答yes，终止当前技能，切换到**

ionic-app-creation

技能。若回答no**，继续执行步骤2。

Step 2: Create the Web App

步骤2：创建Web应用

Ask the user which web framework they want to use. Present these options:

Angular
React
Vue
None (vanilla JS/TS or existing web app)

Based on the selection, scaffold the web project:

询问用户想要使用的Web框架，提供以下选项：

Angular
React
Vue
不使用框架（原生JS/TS 或已有Web应用）

根据用户选择搭建Web项目脚手架：

Angular

bash

npm install -g @angular/cli
ng new my-app
cd my-app

The default web asset directory for Angular is

dist/my-app/browser

. Adjust the directory name based on the actual project name.

bash

npm install -g @angular/cli
ng new my-app
cd my-app

Angular默认的Web资源目录是

dist/my-app/browser

，请根据实际项目名称调整目录名。

React

bash

npm create vite@latest my-app -- --template react-ts
cd my-app
npm install

The default web asset directory for React (Vite) is

dist

bash

npm create vite@latest my-app -- --template react-ts
cd my-app
npm install

React（Vite构建）默认的Web资源目录是

dist

。

Vue

bash

npm create vite@latest my-app -- --template vue-ts
cd my-app
npm install

The default web asset directory for Vue (Vite) is

dist

bash

npm create vite@latest my-app -- --template vue-ts
cd my-app
npm install

Vue（Vite构建）默认的Web资源目录是

dist

。

None (vanilla or existing web app)

不使用框架（原生JS或已有Web应用）

If the user has an existing web app, confirm it meets these requirements:

A
```
package.json
```
file exists at the project root.
A build output directory exists (e.g.,
```
dist
```
,
```
www
```
,
```
build
```
).
An
```
index.html
```
file exists at the root of the build output directory.
The
```
index.html
```
file contains a
```
<head>
```
tag (required for Capacitor plugins to work).

If the user wants a vanilla project:

bash

mkdir my-app && cd my-app
npm init -y
mkdir www

Then create

www/index.html

html

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>My App</title>
</head>
<body>
  <h1>My App</h1>
</body>
</html>

The web asset directory is

www

如果用户已有现成的Web应用，确认其满足以下要求：

项目根目录存在
```
package.json
```
文件。
存在构建输出目录（例如
```
dist
```
、
```
www
```
、
```
build
```
）。
构建输出目录的根路径下存在
```
index.html
```
文件。
```
index.html
```
文件包含
```
<head>
```
标签（Capacitor插件正常运行的必要条件）。

如果用户需要原生JS项目：

bash

mkdir my-app && cd my-app
npm init -y
mkdir www

然后创建

www/index.html

文件：

html

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>My App</title>
</head>
<body>
  <h1>My App</h1>
</body>
</html>

对应的Web资源目录为

www

。

Step 3: Install Capacitor

步骤3：安装Capacitor

Navigate to the project root directory and install the Capacitor core packages:

bash

npm install @capacitor/core
npm install -D @capacitor/cli

切换到项目根目录，安装Capacitor核心包：

bash

npm install @capacitor/core
npm install -D @capacitor/cli

Step 4: Initialize Capacitor

步骤4：初始化Capacitor

Run the Capacitor init command with the app name, app ID, and web asset directory:

bash

npx cap init <appName> <appID> --web-dir <webDir>

<appName>
: Ask the user for the display name of the app (e.g.,
```
"My App"
```
).
<appID>
: Ask the user for the app ID in reverse-domain format (e.g.,
```
com.example.myapp
```
).
<webDir>
: Use the web asset directory determined in Step 2 (e.g.,
```
dist
```
,
```
www
```
,
```
dist/my-app/browser
```
).

This creates a

capacitor.config.ts

file in the project root.

执行Capacitor初始化命令，传入应用名称、应用ID和Web资源目录：

bash

npx cap init <appName> <appID> --web-dir <webDir>

<appName>
：询问用户设置应用的显示名称（例如
```
"My App"
```
）。
<appID>
：询问用户设置反向域名格式的应用ID（例如
```
com.example.myapp
```
）。
<webDir>
：使用步骤2中确定的Web资源目录（例如
```
dist
```
、
```
www
```
、
```
dist/my-app/browser
```
）。

执行完成后会在项目根目录生成

capacitor.config.ts

文件。

Step 5: Build the Web App

步骤5：构建Web应用

Before adding native platforms, build the web app so the output directory exists:

添加原生平台之前，先构建Web应用，确保输出目录存在：

Angular

bash

ng build

bash

ng build

React / Vue (Vite)

bash

npm run build

bash

npm run build

Vanilla

原生JS项目

No build step needed if using a static

www/

directory.

如果使用静态

www/

目录则不需要构建步骤。

Step 6: Add Native Platforms

步骤6：添加原生平台

Ask the user which platforms to add:

Which platforms do you want to add? (android/ios/both)

询问用户需要添加的平台：

你想要添加哪些平台？(android/ios/both)

Add Android

添加Android平台

bash

npm install @capacitor/android
npx cap add android

This creates the

android/

directory with a native Android project.

bash

npm install @capacitor/android
npx cap add android

执行完成后会生成

android/

目录，包含原生Android项目。

Add iOS

添加iOS平台

bash

npm install @capacitor/ios
npx cap add ios

This creates the

ios/

directory with a native iOS project. By default, Capacitor 8 uses Swift Package Manager (SPM) for iOS dependency management.

bash

npm install @capacitor/ios
npx cap add ios

执行完成后会生成

ios/

目录，包含原生iOS项目。默认情况下，Capacitor 8使用Swift Package Manager (SPM)管理iOS依赖。

Step 7: Sync the Project

步骤7：同步项目

Sync the web assets and native dependencies:

bash

npx cap sync

This copies the built web assets into each native platform project and installs native dependencies (Gradle for Android, SPM for iOS).

同步Web资源和原生依赖：

bash

npx cap sync

该命令会将构建好的Web资源复制到每个原生平台项目中，同时安装原生依赖（Android使用Gradle，iOS使用SPM）。

Step 8: Run the App

步骤8：运行应用

Run the app on a connected device or emulator/simulator:

在连接的设备、模拟器上运行应用：

Android

bash

npx cap run android

This prompts for a target device (emulator or physical device).

bash

npx cap run android

执行后会提示选择目标设备（模拟器或物理设备）。

iOS

bash

npx cap run ios

This prompts for a target simulator or physical device.

bash

npx cap run ios

执行后会提示选择目标模拟器或物理设备。

Step 9: Post-Creation Options

步骤9：创建后可选配置

After the app is running, ask the user:

Do you want to set up Live Updates for over-the-air updates? (yes/no)

If yes, refer the user to the capawesome-cloud
skill for live update setup.

Then ask:

Do you want to set up CI/CD for native builds and app store publishing? (yes/no)

If yes, refer the user to the capawesome-cloud
skill for CI/CD setup.

应用成功运行后，询问用户：

你是否需要配置实时更新能力，实现空中升级？(yes/no)

若回答yes，引导用户使用**

capawesome-cloud

**技能完成实时更新配置。

之后再询问：

你是否需要配置CI/CD能力，实现原生构建和应用商店发布自动化？(yes/no)

若回答yes，引导用户使用**

capawesome-cloud

**技能完成CI/CD配置。

Error Handling

错误处理

npx cap init
fails with "already initialized": A
```
capacitor.config.ts
```
or
```
capacitor.config.json
```
file already exists. The project is already a Capacitor project. Delete the existing config file if re-initialization is intended.
npx cap add
fails with "platform already exists": The
```
android/
```
or
```
ios/
```
directory already exists. Remove the directory first:
```
rm -rf android
```
or
```
rm -rf ios
```
, then re-run
```
npx cap add
```
.
npx cap sync
fails with "could not find the web assets directory": The web app has not been built yet, or the
```
webDir
```
in
```
capacitor.config.ts
```
points to a non-existent directory. Run the web app build command first (e.g.,
```
npm run build
```
,
```
ng build
```
).
iOS build fails with "no such module": Run
```
npx cap sync ios
```
to ensure SPM dependencies are resolved.
Android build fails with SDK errors: Verify that Android SDK is installed and
```
ANDROID_HOME
```
or
```
ANDROID_SDK_ROOT
```
environment variable is set. Open Android Studio SDK Manager to install missing SDK versions.
index.html
missing
<head>
tag: Capacitor plugins inject scripts into the
```
<head>
```
tag. Ensure the
```
index.html
```
in the web asset directory contains a
```
<head>
```
element.

npx cap init
执行失败提示"already initialized"：项目中已存在
```
capacitor.config.ts
```
或
```
capacitor.config.json
```
文件，说明当前已经是Capacitor项目。如果需要重新初始化，请先删除现有配置文件。
npx cap add
执行失败提示"platform already exists"：
```
android/
```
或
```
ios/
```
目录已存在。请先删除对应目录：
```
rm -rf android
```
或
```
rm -rf ios
```
，再重新执行
```
npx cap add
```
命令。
npx cap sync
执行失败提示"could not find the web assets directory"：Web应用尚未构建，或者
```
capacitor.config.ts
```
中的
```
webDir
```
指向的目录不存在。请先执行Web应用构建命令（例如
```
npm run build
```
、
```
ng build
```
）。
iOS构建失败提示"no such module"：执行
```
npx cap sync ios
```
确保SPM依赖已正确解析。
Android构建失败提示SDK相关错误：确认已安装Android SDK，且
```
ANDROID_HOME
```
或
```
ANDROID_SDK_ROOT
```
环境变量已正确配置。可打开Android Studio SDK管理器安装缺失的SDK版本。
index.html
缺少
<head>
标签：Capacitor插件需要向
```
<head>
```
标签中注入脚本，请确保Web资源目录下的
```
index.html
```
包含
```
<head>
```
元素。

capacitor-app-creation

Original

Translation

Capacitor App Creation

Capacitor应用创建

Prerequisites

前提条件

Agent Behavior

Agent行为准则

Procedures

操作步骤

Step 1: Check for Ionic Framework

步骤1：确认是否使用Ionic Framework

Step 2: Create the Web App

步骤2：创建Web应用

Angular

Angular

React

React

Vue

Vue

None (vanilla or existing web app)

不使用框架（原生JS或已有Web应用）

Step 3: Install Capacitor

步骤3：安装Capacitor

Step 4: Initialize Capacitor

步骤4：初始化Capacitor

Step 5: Build the Web App

步骤5：构建Web应用

Angular

Angular

React / Vue (Vite)

React / Vue (Vite)

Vanilla

原生JS项目

Step 6: Add Native Platforms

步骤6：添加原生平台

Add Android

添加Android平台

Add iOS

添加iOS平台

Step 7: Sync the Project

步骤7：同步项目

Step 8: Run the App

步骤8：运行应用

Android

Android

iOS

iOS

Step 9: Post-Creation Options

步骤9：创建后可选配置

Error Handling

错误处理

Related Skills

相关技能