🧭 一眼入口

安装命令

npm install @capacitor/core @capacitor/cli
npx cap init

核心组件

⚡ 最小工作流

# 1. 初始化（已有 Web 项目）
npx cap init "MyApp" "com.example.myapp"

# 2. 添加平台
npm install @capacitor/ios @capacitor/android
npx cap add ios
npx cap add android

# 3. 构建 Web 产物
npm run build

# 4. 同步到原生项目
npx cap sync

# 5. 打开 IDE 运行
npx cap open ios    # Xcode
npx cap open android  # Android Studio

目录结构

项目根/
├── Web 应用代码/
│   ├── src/
│   └── dist/          # 构建产物目录
├── ios/               # 原生 iOS 项目
├── android/           # 原生 Android 项目
└── capacitor.config.ts

📦 高频场景 Recipes

场景1：日常开发（Live Reload）

# 启动开发服务器 + 实时刷新
npx cap run ios --livereload
npx cap run android --livereload

# 指定设备
npx cap run ios --target "iPhone 16"

场景2：正式打包

# 构建 Web 产物
npm run build

# 同步并打包（iOS 需要签名配置）
npx cap sync ios
npx cap build ios

# Android 生成 APK/AAB
npx cap sync android
npx cap build android

场景3：插件安装

# 安装官方插件
npm install @capacitor/camera @capacitor/geolocation

# 同步插件到原生项目
npx cap sync

场景4：环境隔离

// capacitor.config.ts
const isDev = process.env.NODE_ENV === 'development';

const config: CapacitorConfig = {
  appId: isDev ? 'com.example.dev' : 'com.example.prod',
  server: {
    hostname: isDev ? 'localhost' : 'production.example.com',
  },
};

export default config;

🔧 CLI 命令速查

cap init

# 交互式初始化
npx cap init

# 参数方式
npx cap init "AppName" "com.example.app" --web-dir=dist

cap sync vs cap copy vs cap update

cap run 常用选项

--livereload       # 启用实时刷新
--external        # 允许外部访问（手机可访问开发服务器）
--target <id>     # 指定目标设备
--dark-mode       # 启用暗色模式

⚙️ 配置速查 >>>

顶层配置

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.example.myapp',
  appName: 'MyApp',
  webDir: 'dist',
  loggingBehavior: 'debug',
};

export default config;

平台特定配置

const config: CapacitorConfig = {
  // iOS 配置
  ios: {
    scheme: 'myapp',
    allowsLinkPreview: true,
    scrollEnabled: false,
  },

  // Android 配置
  android: {
    flavor: 'prod',
    minVersion: 22,
    backgroundColor: '#ffffff',
  },

  // 本地开发服务器
  server: {
    hostname: 'localhost',
    iosScheme: 'https',
    androidScheme: 'https',
  },
};

插件配置示例

const config: CapacitorConfig = {
  plugins: {
    SplashScreen: {
      launchShowDuration: 2000,
      backgroundColor: '#ffffffff',
    },
    StatusBar: {
      style: 'LIGHT',
      backgroundColor: '#20861e',
    },
  },
};

🔌 常用插件速查 >>>

Camera

import { Camera, CameraResultType, CameraSource } from '@capacitor/camera';

const image = await Camera.getPhoto({
  quality: 90,
  resultType: CameraResultType.DataUrl,
  source: CameraSource.Camera,
});

Preferences（轻量存储）

import { Preferences } from '@capacitor/preferences';

// 存储
await Preferences.set({ key: 'username', value: 'john' });

// 读取
const { value } = await Preferences.get({ key: 'username' });

Geolocation

import { Geolocation } from '@capacitor/geolocation';

const position = await Geolocation.getCurrentPosition({
  timeout: 5000,
  enableHighAccuracy: true,
});

Filesystem

import { Filesystem, Directory, Encoding } from '@capacitor/filesystem';

await Filesystem.writeFile({
  path: 'note.txt',
  data: 'Hello',
  directory: Directory.Documents,
  encoding: Encoding.UTF8,
});

插件与存储选型

🚨 排障与收尾

环境诊断

# 检查开发环境
npx cap doctor

# 常见问题
# - Node.js 版本不兼容
# - 原生平台工具缺失（Xcode/Android SDK）
# - 端口被占用

清理与重置

# 卸载平台
npx cap remove ios
npx cap remove android

# 重新添加
npx cap add ios
npx cap add android

# 强制同步
npx cap sync --force

权限问题（iOS）

<!-- Info.plist -->
<key>NSCameraUsageDescription</key>
<string>需要访问相机</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>需要访问位置</string>

权限问题（Android）

<!-- AndroidManifest.xml -->
<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

WebView 文件路径

import { Capacitor } from '@capacitor/core';

// 转换文件路径（iOS/Android 必须）
const fileSrc = Capacitor.convertFileSrc(originalPath);

📚 核心对比