Capacitor 是什么？

Capacitor 是一款轻量级跨平台运行时，可将 Web 项目（如 Framework7 开发的 H5）打包为 Android、iOS 原生 App，核心无需复杂原生开发，仅通过命令行和原生 IDE 完成打包，步骤如下：

一、 前置环境准备

需提前安装基础依赖，确保环境符合要求：

1. Node.js：要求 Node 18+（推荐 20+ LTS 版本）；

2. 原生环境：

   • Android：安装 Android Studio、Java JDK 21（Android Studio 自带，无需额外下载），配置 ANDROID_HOME 环境变量；

   • iOS（仅 MacOS）：安装 Xcode 16.0+，配置 Xcode 开发环境；

3. Web 项目：确保项目已完成构建（如 npm run build）。

二、 给现有 Web 项目集成 Capacitor

在已有的 Web 项目中，执行以下命令集成 Capacitor：

1. 安装 Capacitor 核心依赖和 CLI：
   npm install @capacitor/core @capacitor/cli

2. 初始化 Capacitor 配置：
   npx cap init执行初始化，初始化完成后自动生成 capacitor.config.ts 配置文件，如下：

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

const config: CapacitorConfig = {
  appId: 'com.example.app',
  appName: 'app-demo',
  webDir: 'dist' // Web构建产物目录
};

export default config;

3. 添加目标平台（Android/iOS）：

   • 添加 Android 平台
     npm i @capacitor/android
npx cap add android

   • 添加 iOS 平台（仅 macOS）
     npm i @capacitor/ios
npx cap add ios

     执行后会在项目根目录生成 android、ios 文件夹，对应原生项目目录。

三、 同步 Web 代码到原生项目

每次修改 Web 代码后，需先构建 Web 项目，再同步到原生项目：

1. 构建 Web 项目
   npm run build

2. 同步 Web 资源到原生项目
   npx cap sync

若同步时提示“找不到 Web 资源目录”，需检查 capacitor.config.ts 中的 webDir 配置是否与实际构建目录一致。

四、开发流程

安装好所有依赖后的开发流程：

1. 开发Web应用：npm run dev
2. 构建Web应用：npm run build
3. 同步到原生平台：npx cap sync
4. 打开原生IDE调试：npx cap open android 或 npx cap open ios

五、 打包生成 App 安装包

Capacitor 本身不提供直接打包命令，需通过原生 IDE 完成最终打包：

（1）Android 打包（生成 APK/APP Bundle）

1. 打开原生项目：
   npx cap open android自动启动 Android Studio 并加载项目，首次打开需等待 Gradle 同步完成（可能需要下载依赖，耐心等待）。

2. 配置构建参数：在 Android Studio 中，修改项目的版本号、图标、权限等（可在 build.gradle 或 AndroidManifest.xml 中配置），确保 minSdkVersion ≥ 23、compileSdkVersion ≥ 35（Capacitor 7 最低要求）。

3. 生成安装包：通过 Android Studio 菜单栏「Build → Generate Signed Bundle/APK」，按照提示创建密钥库（用于 App 签名），选择打包类型（APK 用于测试，APP Bundle 用于上架应用商店），完成打包。

（2）iOS 打包（生成 IPA）

1. 打开原生项目：
   npx cap open ios自动启动 Xcode 并加载项目，需先登录 Apple 开发者账号（用于签名）。

2. 配置项目：在 Xcode 中，设置项目的 Bundle ID（需与 capacitor.config.json 中的包名一致）、签名证书、设备适配（iOS 部署目标 ≥ 14.0）。

3. 生成 IPA：选择「Product → Archive」，归档完成后，通过「Distribute App」选择打包方式（Ad Hoc 用于测试，App Store 用于上架），完成打包。