Capacitor 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 的实现中,添加流程为:
- 从内置资产解压平台模板(Android 对应
android-template.tar.gz,iOS 对应ios-spm-template.tar.gz,路径定义在 cli/src/config.ts 的loadCLIConfig); - 将应用名称、应用 ID 等写入原生工程(
editProjectSettingsIOS/editProjectSettingsAndroid); - 若
webDir目录已存在,自动执行一次sync,把 Web 资源拷入原生工程; - 为 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"。执行顺序为:
- 触发
capacitor:sync:before钩子; - 执行
copy:把webDir的构建产物复制到各原生工程; - 执行
update:更新原生插件与依赖; - 触发
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() 加载项目配置。其查找顺序是:
capacitor.config.ts(需项目安装 TypeScript,否则报错提示npm install -D typescript);capacitor.config.js;capacitor.config.json。
解析出的 Config 会聚合出 Android(minVersion: '24')、iOS(minVersion: '15.0')、Web 三端的路径信息与 buildOptions,并缓存为 CLI 上下文供各命令使用。这解释了为什么 init 之前必须存在(或由 init 创建)一个合法配置:几乎所有命令都依赖它计算原生工程路径。
五、本地开发:为 CLI 贡献代码
如果你要修改 CLI 源码或验证本地改动,README 给出了标准流程:
-
克隆仓库并安装依赖:
git clone https://github.com/ionic-team/capacitor.git cd cli npm install -
构建 CLI:
npm run build从 cli/package.json 的 scripts 可见,
build会先清空dist、打包内置模板资产(npm run assets),再执行tsc编译 TypeScript 到dist/。 -
创建本地链接,使
capacitor/cap命令指向本仓库编译产物:npm link -
进入开发循环:
- 运行
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 启动配置,操作步骤如下:
- 在 VS Code 中打开项目;
- 由于当前 TS 源码尚未直接支持断点调试,请选择
dist/下的某个编译产物.js文件(如dist/index.js)作为调试入口; - 在目标位置打上断点;
- 按
F5或通过 Run > Start Debugging 启动; - 在弹窗中选择一个 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 中的测试文件则展示了各命令行为被验证的方式,可作为贡献代码时的参考基线。