安装与配置 #

一、环境要求 #

1.1 基础环境 #

工具 最低版本 推荐版本 说明
Node.js 16.x 18.x LTS JavaScript运行时
npm 8.x 9.x+ 包管理器
Git 2.x 最新版 版本控制

1.2 iOS开发环境（仅macOS） #

工具 要求
操作系统 macOS 12+ (Monterey)
Xcode 14.x+
CocoaPods 1.10+
Xcode命令行工具 最新版

1.3 Android开发环境 #

工具 要求
JDK 17+
Android Studio Flamingo (2022.2.1)+
Android SDK API 22+
Gradle 7.x+

二、基础环境安装 #

2.1 Node.js安装 #

macOS/Linux #

bash 
# 使用nvm安装（推荐）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# 安装Node.js LTS版本
nvm install --lts
nvm use --lts

# 验证安装
node -v
npm -v

Windows #

bash 
# 使用官方安装包或winget
winget install OpenJS.NodeJS.LTS

# 或使用Chocolatey
choco install nodejs-lts

2.2 包管理器选择 #

bash 
# npm（默认）
npm -v

# yarn
npm install -g yarn
yarn -v

# pnpm（推荐，更快更节省空间）
npm install -g pnpm
pnpm -v

三、iOS环境配置 #

3.1 安装Xcode #

  1. 从Mac App Store安装Xcode
  2. 安装Xcode命令行工具
bash 
xcode-select --install

3.2 安装CocoaPods #

bash 
# 安装CocoaPods
sudo gem install cocoapods

# 验证安装
pod --version

3.3 Xcode配置 #

bash 
# 接受Xcode许可协议
sudo xcodebuild -license accept

# 设置Xcode命令行工具路径
sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer

3.4 创建模拟器 #

  1. 打开Xcode
  2. 进入 Window → Devices and Simulators
  3. 创建iOS模拟器（推荐iPhone 14 Pro）

四、Android环境配置 #

4.1 安装JDK #

macOS #

bash 
# 使用Homebrew安装
brew install openjdk@17

# 创建符号链接
sudo ln -sfn /opt/homebrew/opt/openjdk@17/libexec/openjdk.jdk /Library/Java/JavaVirtualMachines/openjdk-17.jdk

# 配置环境变量
echo 'export PATH="/opt/homebrew/opt/openjdk@17/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# 验证安装
java -version

Windows #

bash 
# 使用winget
winget install Microsoft.OpenJDK.17

# 或下载安装包
# https://adoptium.net/

4.2 安装Android Studio #

  1. 下载Android Studio：https://developer.android.com/studio
  2. 安装并启动Android Studio
  3. 完成初始设置向导

4.3 安装Android SDK #

在Android Studio中：

  1. 打开 Settings/Preferences → Appearance & Behavior → System Settings → Android SDK
  2. 安装以下组件：
    • Android SDK Platform 33 (或更高)
    • Android SDK Build-Tools 33
    • Android SDK Command-line Tools
    • Android Emulator
    • Android SDK Platform-Tools

4.4 配置环境变量 #

macOS/Linux (~/.zshrc 或 ~/.bashrc) #

bash 
# Android SDK路径
export ANDROID_HOME=$HOME/Library/Android/sdk
export PATH=$PATH:$ANDROID_HOME/emulator
export PATH=$PATH:$ANDROID_HOME/platform-tools
export PATH=$PATH:$ANDROID_HOME/cmdline-tools/latest/bin
export PATH=$PATH:$ANDROID_HOME/tools
export PATH=$PATH:$ANDROID_HOME/tools/bin

Windows（系统环境变量） #

bash 
# 新建系统变量
ANDROID_HOME = C:\Users\用户名\AppData\Local\Android\Sdk

# 添加到Path
%ANDROID_HOME%\platform-tools
%ANDROID_HOME%\emulator
%ANDROID_HOME%\tools
%ANDROID_HOME%\tools\bin

4.5 创建Android模拟器 #

  1. 打开Android Studio
  2. 进入 Tools → Device Manager
  3. 创建虚拟设备
  4. 推荐配置：
    • 设备：Pixel 6
    • 系统镜像：API 33 (Android 13)
    • RAM：至少2048MB

4.6 验证Android环境 #

bash 
# 检查adb
adb version

# 列出已连接设备
adb devices

# 检查模拟器
emulator -list-avds

五、创建Capacitor项目 #

5.1 方式一：全新项目 #

bash 
# 创建新项目
npm init @capacitor/app my-app

# 进入项目目录
cd my-app

# 安装依赖
npm install

# 安装Capacitor CLI
npm install @capacitor/cli

5.2 方式二：现有项目集成 #

bash 
# 在现有项目根目录
npm install @capacitor/core @capacitor/cli

# 初始化Capacitor
npx cap init

# 按提示输入：
# - App name: 应用名称
# - App ID: 应用包名（如 com.example.app）

5.3 方式三：配合前端框架 #

React + Vite #

bash 
# 创建React项目
npm create vite@latest my-app -- --template react-ts

cd my-app
npm install

# 添加Capacitor
npm install @capacitor/core @capacitor/cli
npx cap init

Vue + Vite #

bash 
# 创建Vue项目
npm create vite@latest my-app -- --template vue-ts

cd my-app
npm install

# 添加Capacitor
npm install @capacitor/core @capacitor/cli
npx cap init

Angular #

bash 
# 创建Angular项目
ng new my-app

cd my-app

# 添加Capacitor
npm install @capacitor/core @capacitor/cli
npx cap init

六、添加平台 #

6.1 添加iOS平台 #

bash 
# 添加iOS平台
npx cap add ios

# 打开Xcode项目
npx cap open ios

6.2 添加Android平台 #

bash 
# 添加Android平台
npx cap add android

# 打开Android Studio项目
npx cap open android

6.3 平台目录结构 #

text 
my-app/
├── ios/
│   └── App/
│       └── App.xcworkspace    # Xcode项目
├── android/
│   └── app/                   # Android Studio项目
├── src/                       # Web源码
├── dist/                      # Web构建输出
└── capacitor.config.json      # Capacitor配置

七、配置文件详解 #

7.1 capacitor.config.json #

json 
{
    "appId": "com.example.app",
    "appName": "My App",
    "webDir": "dist",
    "bundledWebRuntime": false,
    "server": {
        "iosScheme": "https",
        "androidScheme": "https",
        "url": "http://localhost:5173",
        "cleartext": true
    },
    "ios": {
        "contentInset": "automatic",
        "preferredContentMode": "mobile",
        "scrollEnabled": true
    },
    "android": {
        "allowMixedContent": true,
        "captureInput": true,
        "webContentsDebuggingEnabled": true
    },
    "plugins": {
        "SplashScreen": {
            "launchShowDuration": 2000,
            "backgroundColor": "#ffffff",
            "androidSplashResourceName": "splash",
            "androidScaleType": "CENTER_CROP",
            "showSpinner": false
        },
        "Keyboard": {
            "resize": "body",
            "resizeOnFullScreen": true
        }
    }
}

7.2 配置项说明 #

配置项 说明
appId 应用包名（反向域名格式）
appName 应用显示名称
webDir Web构建输出目录
bundledWebRuntime 是否打包Capacitor运行时
server 服务器配置
ios iOS特定配置
android Android特定配置
plugins 插件配置

7.3 开发服务器配置 #

json 
{
    "server": {
        "url": "http://192.168.1.100:5173",
        "iosScheme": "https",
        "androidScheme": "https",
        "cleartext": true
    }
}

八、常用命令 #

8.1 CLI命令一览 #

bash 
# 初始化项目
npx cap init [appName] [appId]

# 添加平台
npx cap add ios
npx cap add android

# 复制Web资源
npx cap copy
npx cap copy ios
npx cap copy android

# 同步（复制+更新）
npx cap sync
npx cap sync ios
npx cap sync android

# 更新原生依赖
npx cap update
npx cap update ios
npx cap update android

# 打开原生IDE
npx cap open ios
npx cap open android

# 运行应用
npx cap run ios
npx cap run android

# 查看信息
npx cap ls

8.2 package.json脚本配置 #

json 
{
    "scripts": {
        "dev": "vite",
        "build": "vite build",
        "preview": "vite preview",
        "cap:sync": "npx cap sync",
        "cap:ios": "npx cap open ios",
        "cap:android": "npx cap open android",
        "cap:run:ios": "npx cap run ios",
        "cap:run:android": "npx cap run android"
    }
}

九、环境验证 #

9.1 检查清单 #

bash 
# 检查Node.js
node -v        # 应显示v18.x或更高

# 检查npm
npm -v         # 应显示9.x或更高

# 检查Capacitor CLI
npx cap --version

# 检查iOS环境（仅macOS）
xcodebuild -version
pod --version

# 检查Android环境
java -version
adb version

9.2 创建测试项目 #

bash 
# 创建测试项目
npm init @capacitor/app test-env
cd test-env
npm install

# 添加平台
npx cap add ios
npx cap add android

# 检查平台
npx cap ls

十、常见问题 #

10.1 iOS问题 #

问题：CocoaPods安装失败

bash 
# 解决方案
sudo gem install cocoapods -n /usr/local/bin

问题：Xcode签名错误

text 
1. 打开Xcode项目
2. 选择App target
3. 在Signing & Capabilities中选择开发者账号

10.2 Android问题 #

问题：SDK路径未找到

bash 
# 设置ANDROID_HOME环境变量
export ANDROID_HOME=$HOME/Library/Android/sdk

问题：Gradle构建失败

bash 
# 清理Gradle缓存
cd android
./gradlew clean

10.3 网络问题 #

问题：npm安装慢

bash 
# 使用国内镜像
npm config set registry https://registry.npmmirror.com

# 或使用pnpm
npm install -g pnpm
pnpm config set registry https://registry.npmmirror.com

十一、总结 #

11.1 安装要点 #

步骤 说明
1 安装Node.js和包管理器
2 安装Xcode（iOS开发）
3 安装Android Studio和SDK
4 创建Capacitor项目
5 添加iOS/Android平台

11.2 下一步 #

环境配置完成后，让我们创建 第一个应用，体验Capacitor开发流程！

最后更新：2026-03-28