capacitor-app-creation

Capacitor 应用创建

从头创建一个新的 Capacitor 应用，包括项目脚手架、平台设置和可选集成。

前置条件

1. 已安装 Node.js 22+。使用 node --version 验证。
2. iOS：使用 macOS，且已安装 Xcode 26.0+。安装 Xcode 命令行工具：xcode-select --install。
3. Android：已安装 Android Studio 2025.2.1+ 和 Android SDK（API 24+）。

Agent 行为

• 逐步引导。 一次带领用户完成一个步骤。切勿一次提出多个无关问题。
• 每次只做一个决定。 某个步骤需要用户输入时，只提出一个问题，等待回答后再继续。
• 提供明确选项。 提供具体选项（例如：“要添加 iOS 平台吗？（是/否）”），而不是开放式问题。

流程

步骤 1：检查是否使用 Ionic Framework

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

要使用 Ionic Framework 的 UI 组件和主题功能吗？（是/否）

如果用户回答是，则停止此技能并改用 ionic-app-creation 技能。如果回答否，则继续步骤 2。

步骤 2：创建 Web 应用

询问用户想使用哪种 Web 框架。提供以下选项：

1. Angular
2. React
3. Vue
4. 无（原生 JS/TS 或现有 Web 应用）

根据用户的选择，搭建 Web 项目：

Angular

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

Angular 的默认 Web 资源目录是 dist/my-app/browser。请根据实际项目名称调整目录名称。

React

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

React（Vite）的默认 Web 资源目录是 dist。

Vue

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

Vue（Vite）的默认 Web 资源目录是 dist。

无（原生或现有 Web 应用）

如果用户已有 Web 应用，请确认它满足以下要求：

1. 项目根目录中存在 package.json 文件。
2. 存在构建输出目录（例如 dist、www、build）。
3. 构建输出目录的根目录中存在 index.html 文件。
4. index.html 文件包含 <head> 标签（这是 Capacitor 插件正常工作的必要条件）。

如果用户想创建原生项目：

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

然后创建 www/index.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。

步骤 3：安装 Capacitor

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

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

步骤 4：初始化 Capacitor

运行 Capacitor 初始化命令，并指定应用名称、应用 ID 和 Web 资源目录：

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 文件。

步骤 5：构建 Web 应用

添加原生平台之前，先构建 Web 应用，以生成输出目录：

Angular

ng build

React / Vue（Vite）

npm run build

原生

如果使用静态 www/ 目录，则无需构建。

步骤 6：添加原生平台

询问用户要添加哪些平台：

要添加哪些平台？（android/ios/both）

添加 Android

npm install @capacitor/android
npx cap add android

此操作会创建包含原生 Android 项目的 android/ 目录。

添加 iOS

npm install @capacitor/ios
npx cap add ios

此操作会创建包含原生 iOS 项目的 ios/ 目录。默认情况下，Capacitor 8 使用 Swift Package Manager（SPM）管理 iOS 依赖项。

步骤 7：同步项目

同步 Web 资源和原生依赖项：

npx cap sync

此操作会将构建后的 Web 资源复制到各个原生平台项目中，并安装原生依赖项（Android 使用 Gradle，iOS 使用 SPM）。

步骤 8：运行应用

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

Android

npx cap run android

此操作会提示选择目标设备（模拟器或实体设备）。

iOS

npx cap run ios

此操作会提示选择目标模拟器或实体设备。

第 9 步：创建后的选项

应用运行后，询问用户：

是否要设置 Live Updates，以便通过无线方式更新？（是/否）

如果回答是，请引导用户参考 capawesome-cloud skill 设置 Live Updates。

然后询问：

是否要设置 CI/CD，以便进行原生构建并发布到应用商店？（是/否）

如果回答是，请引导用户参考 capawesome-cloud skill 设置 CI/CD。

错误处理

• 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 Manager，安装缺失的 SDK 版本。
• index.html 缺少 <head> 标签：Capacitor 插件会将脚本注入 <head> 标签。确保 Web 资源目录中的 index.html 包含 <head> 元素。

相关 Skills

• ionic-app-creation — 创建包含 UI 组件和主题的新 Ionic 应用，而不是普通的 Capacitor 应用。
• capacitor-app-development — 创建应用后有关 Capacitor 应用开发的一般指导。
• capacitor-angular — 适用于 Capacitor 应用的 Angular 专属模式和最佳实践。
• capacitor-react — 适用于 Capacitor 应用的 React 专属模式和最佳实践。
• capacitor-vue — 适用于 Capacitor 应用的 Vue 专属模式和最佳实践。
• capacitor-plugins — 创建应用后安装和配置 Capacitor 插件。
• capawesome-cloud — 为应用设置 Live Updates、原生构建和 CI/CD。