Capacitor CLI 完全指南:安装、命令体系与本地开发调试

原创2026-10-02 15:54:221,667 阅读
文章标签:跨平台移动开发原生移动插件系统CLI前端

Capacitor CLI 完全指南:安装、命令体系与本地开发调试

Capacitor CLI(@capacitor/cli)是 Capacitor 跨平台应用开发的核心命令行工具,负责初始化项目、添加原生平台(iOS / Android)、同步 Web 代码以及构建发布。本文基于当前仓库 cli/README.md 展开,结合 cli/src/index.ts 等源码,完整讲解 CLI 的安装方式、命令参数、底层配置加载机制,以及面向 CLI 贡献者的本地开发与调试流程。

一、Capacitor CLI 是什么

Capacitor 是一个面向 iOS、Android 与 Web 的跨平台原生应用框架,而 CLI 是围绕它构建的"命令中枢"。它承担两类职责:

  • 面向应用开发者:初始化项目、注册原生平台、把构建好的 Web 资源复制进原生工程、更新原生依赖、在真机/模拟器上运行与构建发布。
  • 面向 CLI 贡献者:提供可 watch 的编译流程、Jest 测试套件和 VS Code 调试配置,方便在仓库内直接开发与验证。

CLI 的实际命令是通过 commander 库在 cli/src/index.ts 中注册的。仓库中 cli/package.json 声明了它的 bin 入口:capacitor 与 cap 两个命令名指向同一个 ./bin/capacitor 脚本,因此下面两种写法完全等价。

二、安装 CLI

2.1 项目本地安装(推荐)

在项目根目录执行:

npm install @capacitor/cli --save-dev

使用 --save-dev 是因为 CLI 只在开发期使用,构建发布由各平台原生工具完成。本地安装后,通过项目自身的 npm scripts 或 npx 调用,保证每个项目使用与自身版本匹配的 CLI,避免全局版本错位。

2.2 全局安装(不推荐)

npm install -g @capacitor/cli

全局安装方便随手执行 cap 命令,但不推荐用于项目开发:不同项目可能依赖不同版本的 Capacitor,全局版本可能与之不兼容。README 明确建议项目级安装。

2.3 版本与运行时要求

从 cli/package.json 可以看到两个值得注意的事实:

  • 当前仓库中 CLI 版本为 8.4.2;
  • engines.node 声明 node >= 22.0.0,即要求 Node.js 22 及以上版本才能运行该版本 CLI。

CLI 还依赖 commander(参数解析)、fs-extra(文件操作)、native-run(管理模拟器/真机目标)、prompts(交互式提问)等库,这些依赖会在安装时一并处理。

三、CLI 命令体系详解

CLI 通过 capacitor 或 cap 命令调用。README 列出的三个核心命令是:

  • cap init:初始化新的 Capacitor 项目
  • cap add:添加原生平台(ios、android)
  • cap sync:将 Web 代码同步到原生项目

实际上,cli/src/index.ts 中注册的命令远不止这些。下表汇总了完整命令与作用:

命令 作用
init [appName] [appId] 初始化 Capacitor 配置
add [platform] 添加原生平台工程
sync [platform] copy + update 的组合
copy [platform] 将 Web 应用构建产物复制进原生应用
update [platform] 按 package.json 更新原生插件与依赖
run [platform] 先 sync,再构建并部署原生应用
open [platform] 打开原生工程(iOS 打开 Xcode workspace)
build <platform> 构建所选平台的发布版本
ls [platform] 列出已安装的 Cordova 与 Capacitor 插件
doctor [platform] 检查当前环境常见错误
migrate 将现有 Capacitor 应用迁移到最新主版本
spm-migration-assistant 移除 CocoaPods,切换到 Swift Package Manager
telemetry [on|off] 开启/关闭遥测(隐藏命令)
config 打印解析后的 Capacitor 配置(隐藏命令)
create [directory] [name] [id] 创建新的 Capacitor 项目(隐藏命令)
serve 在浏览器中运行 Capacitor PWA(隐藏命令)
plugin:generate 生成新的 Capacitor 插件(隐藏命令)

下面按实际开发流程逐一展开。

3.1 cap init:初始化项目

npx cap init
# 或带参数直接指定
npx cap init appName appId

不带参数时,cli/src/tasks/init.ts 会通过交互式提示依次询问:

  • 应用名称:人类可读的名称,如商店里显示的名字;
  • Package ID:即 iOS 的 Bundle ID 和 Android 的 Application ID,必须是反域名记法(如 com.example.myapp);
  • Web 资源目录:存放最终 index.html 的目录,默认 www,若检测到前端框架会自动采用其约定目录(见 detectFramework)。

init 支持以下选项:

选项 说明
--web-dir <value> 指定 Web 构建资源目录
--skip-appid-validation 跳过 iOS/Android 兼容性校验

执行成功后,CLI 会在项目根目录生成 capacitor.config.json。这里有一个值得注意的细节:如果项目中已安装 TypeScript,init 会生成 capacitor.config.ts(源码 isNewConfig && tsInstalled ? 'ts' : 'json');若项目使用非 JSON 的配置且未安装 TypeScript,则会直接报错,要求安装 typescript 或删除既有配置后重试。

3.2 cap add:添加原生平台

npx cap add android
npx cap add ios

不带平台参数时,CLI 会列出可添加的平台供选择。在 cli/src/tasks/add.ts 的实现中,添加流程为:

  1. 从内置资产解压平台模板(Android 对应 android-template.tar.gz,iOS 对应 ios-spm-template.tar.gz,路径定义在 cli/src/config.ts 的 loadCLIConfig);
  2. 将应用名称、应用 ID 等写入原生工程(editProjectSettingsIOS / editProjectSettingsAndroid);
  3. 若 webDir 目录已存在,自动执行一次 sync,把 Web 资源拷入原生工程;
  4. 为 Android 额外生成 local.properties(用于 Gradle 同步)。

add 还有一个面向 iOS 的选项:

选项 说明
--packagemanager <packageManager> 依赖安装方式:CocoaPods 或 SPM

选择 CocoaPods 时,CLI 会切换到 ios-pods-template.tar.gz 模板(见 cli/src/index.ts 中 getPackageManager 的逻辑)。若平台已存在,命令会直接报错并提示先删除既有原生目录——因为原生工程将被完全重建。

3.3 cap sync:同步 Web 代码与原生依赖

npx cap sync
# 或指定平台
npx cap sync android

sync 本质上是 copy 与 update 的组合,cli/src/tasks/sync.ts 的注释直接写明:"Sync is a copy and an update in one"。执行顺序为:

  1. 触发 capacitor:sync:before 钩子;
  2. 执行 copy:把 webDir 的构建产物复制到各原生工程;
  3. 执行 update:更新原生插件与依赖;
  4. 触发 capacitor:sync:after 钩子。

支持选项:

选项 说明
--deployment 传入 pod install --deployment,用于 CocoaPods 锁定版本部署
--inline 将所有 source map 内联,便于在移动设备上调试

同步完成后会输出耗时统计(如 Sync finished in 2.3s)。

3.4 cap copy:复制 Web 资源

npx cap copy
npx cap copy ios

copy 只负责把 Web 构建产物复制进原生工程,不更新依赖。从 cli/src/tasks/copy.ts 可以看到它在复制的同时还会:

  • 在原生工程中生成一份 capacitor.config.json(删除 buildOptions 后的配置);
  • 处理 Cordova 插件的 JS 与 AndroidManifest 合并;
  • 若检测到 @ionic-enterprise/federated-capacitor、@capacitor/live-updates、SSL Pinning 等特殊插件,会执行对应的密钥/证书复制逻辑;
  • 传入 --inline 时对 source map 做内联处理。

一个重要行为:当配置中设置了 server.url 且 webDir 不存在时,copy 不会报错,只输出警告——因为此时应用内容直接来自远程服务器。

3.5 cap update:更新原生依赖

npx cap update

update 依据项目的 package.json 中声明的 Capacitor 相关依赖版本,更新原生工程的插件与依赖(iOS 端会执行 pod install 或 SPM 解析,Android 端更新 Gradle 依赖),同样支持 --deployment 选项。若 iOS 缺少 Bundler 或 CocoaPods,会先给出环境检查提示。

3.6 cap run:运行到真机/模拟器

npx cap run android
npx cap run ios

run 会先执行 sync,再构建并部署到目标设备(使用 native-run 管理设备目标)。这是日常开发最高频的命令之一,cli/src/tasks/run.ts 定义了丰富的选项:

选项 说明
--scheme <name> 指定 iOS scheme
--flavor <name> 指定 Android flavor(尚不支持 flavor dimensions)
--list 列出可用目标设备后退出
--target <id> 使用指定 ID 的目标设备
--target-name <name> 按名称选择目标设备
--target-name-sdk-version <version> 配合 --target-name 指定 SDK 版本
--no-sync 跳过 sync 步骤
--forwardPorts <port:port> 自动执行 adb reverse,提升 live-reload 支持
-l, --live-reload 通过 CLI 设置 live-reload URL
--host <host> 配置 live-reload 的 host
--port <port> 配置 live-reload 的端口(默认 3000)
--https live-reload URL 使用 https://
--configuration <name> 指定 iOS scheme 的 configuration

live-reload 模式下,CLI 会临时改写 capacitor.config.json 的 server.url,在 Ctrl+C 退出时自动还原(对应源码中的 CapLiveReloadHelper 与 SIGINT 处理),并输出形如 App running with live reload listing for: http://192.168.x.x:3000 的提示。

3.7 cap open:打开原生 IDE

npx cap open ios
npx cap open android
  • iOS:打开 Xcode workspace(App.xcworkspace);
  • Android:打开 Android Studio(各平台 Studio 路径的探测逻辑见 cli/src/config.ts 的 determineAndroidStudioPath,也支持通过环境变量 CAPACITOR_ANDROID_STUDIO_PATH 覆盖)。

3.8 cap build:构建发布版本

npx cap build android
npx cap build ios

build 会构建所选平台的发布版本,不支持 web 平台。它提供了完整的 Android 签名与 iOS 导出选项,未指定时回落到 capacitor.config.json 中的 buildOptions 配置,再取默认值。完整选项如下:

选项 可选值 / 默认值 说明
--scheme <schemeToBuild> — 要构建的 iOS Scheme
--flavor <flavorToBuild> — 要构建的 Android Flavor
--keystorepath <path> — keystore 路径
--keystorepass <pass> — keystore 密码
--keystorealias <alias> — keystore 中的 Key Alias
--keystorealiaspass <pass> — Key Alias 的密码
--androidreleasetype <type> AAB(默认)/ APK Android 发布类型
--signing-type <type> jarsigner(默认)/ apksigner 签名程序
--configuration <name> Release(默认) iOS Scheme 的 configuration 名
--xcode-team-id <id> — 构建与导出归档所用的开发者团队
--xcode-export-method <method> app-store-connect(默认) 导出方式,可选 release-testing、enterprise、debugging、developer-id、mac-application、validation
--xcode-signing-style <style> automatic(默认)/ manual iOS 签名方式
--xcode-signing-certificate <cert> — 证书名称、SHA-1 哈希或自动选择器
--xcode-provisioning-profile <profile> — provisioning profile 名称或 UUID

Android 侧对应的 buildOptions(keystorePath、keystorePassword、keystoreAlias、keystoreAliasPassword、signingType、releaseType)在 cli/src/config.ts 的 loadAndroidConfig 中会被解析并合并进构建流程;build 命令本身也会把 CLI 参数与配置值合并(见 cli/src/tasks/build.ts)。

3.9 cap doctor:环境体检

npx cap doctor

doctor 会先对比 npm 上 @capacitor/cli、@capacitor/core、@capacitor/android、@capacitor/ios 的最新版本与项目本地安装版本,再按平台检查 Java、Gradle、Xcode、CocoaPods 等依赖是否就绪,输出诊断信息,是排查环境问题的最直接手段(实现见 cli/src/tasks/doctor.ts)。

3.10 其他命令

  • cap ls:列出已安装的 Cordova 与 Capacitor 插件;
  • cap migrate:把应用迁移到 Capacitor 最新主版本,支持 --noprompt 跳过确认、--packagemanager <npm|pnpm|yarn> 指定安装器;
  • cap spm-migration-assistant:把 iOS 工程从 CocoaPods 迁移到 Swift Package Manager;
  • cap telemetry on|off:开启或关闭遥测(隐藏命令)。

四、配置加载机制:CLI 如何读取项目配置

所有命令执行前,CLI 都会通过 cli/src/config.ts 的 loadConfig() 加载项目配置。其查找顺序是:

  1. capacitor.config.ts(需项目安装 TypeScript,否则报错提示 npm install -D typescript);
  2. capacitor.config.js;
  3. capacitor.config.json。

解析出的 Config 会聚合出 Android(minVersion: '24')、iOS(minVersion: '15.0')、Web 三端的路径信息与 buildOptions,并缓存为 CLI 上下文供各命令使用。这解释了为什么 init 之前必须存在(或由 init 创建)一个合法配置:几乎所有命令都依赖它计算原生工程路径。

五、本地开发:为 CLI 贡献代码

如果你要修改 CLI 源码或验证本地改动,README 给出了标准流程:

  1. 克隆仓库并安装依赖:

    git clone https://github.com/ionic-team/capacitor.git
    cd cli
    npm install
    
  2. 构建 CLI:

    npm run build
    

    从 cli/package.json 的 scripts 可见,build 会先清空 dist、打包内置模板资产(npm run assets),再执行 tsc 编译 TypeScript 到 dist/。

  3. 创建本地链接,使 capacitor / cap 命令指向本仓库编译产物:

    npm link
    
  4. 进入开发循环:

    • 运行 npm run watch:监听源码变更并自动重新编译(tsc -w);
    • 使用 capacitor 或 cap 命令验证改动;
    • 运行 npm test 执行 Jest 测试套件(测试用例位于 cli/test,如 add.android.spec.ts、init.spec.ts、update.ios.spec.ts 等)。

需要注意的是:watch 只负责编译,若新增或改动了打包资产(模板 tar 包),仍需先运行 npm run assets 重新生成。

六、调试:使用 VS Code Launch 配置

仓库为 CLI 调试提供了 VS Code 启动配置,操作步骤如下:

  1. 在 VS Code 中打开项目;
  2. 由于当前 TS 源码尚未直接支持断点调试,请选择 dist/ 下的某个编译产物 .js 文件(如 dist/index.js)作为调试入口;
  3. 在目标位置打上断点;
  4. 按 F5 或通过 Run > Start Debugging 启动;
  5. 在弹窗中选择一个 launch 配置,填写要运行 CLI 的目录路径以及要执行的命令(如 cap sync android)。

若要扩展调试场景,可以复制 .vscode/launch.json 中现有的配置项进行修改,新增自己的配置。调试时先确保 npm run build 或 npm run watch 已把最新改动编译进 dist/,否则断点不会命中新代码。

七、常见问题与要点小结

  • 本地安装 vs 全局安装:项目开发务必使用本地安装 + npx cap 或 npm scripts,避免版本漂移;全局安装仅适合快速试用。
  • Node 版本:本仓库的 CLI 8.x 要求 Node.js ≥ 22,升级或降级 Node 前先核对 cli/package.json 的 engines 字段。
  • sync 与 copy、update 的关系:sync = copy + update,日常增删插件或改 Web 代码后跑 sync 即可;只想推送 Web 代码则用 copy。
  • 配置优先级:CLI 参数 > capacitor.config.* 中的 buildOptions > 默认值,这在 build 命令中体现得最明显。
  • 发布构建:Android 走 cap build android(APK/AAB + 签名),iOS 走 cap build ios(scheme + 导出方式 + 签名),发布前可用 cap doctor 校验环境。

通过 cli/src/index.ts 的命令注册表、cli/src/tasks 下各命令实现与 cli/src/config.ts 的配置加载器,你可以进一步深入阅读每个命令的完整执行链路;而 cli/test 中的测试文件则展示了各命令行为被验证的方式,可作为贡献代码时的参考基线。

登录后查看全文
capacitor