Cordova 命令行界面 (CLI) 命令

CLI 语法

cordova <command> [options] -- [platformOpts]

全局命令列表

这些命令始终可用。

项目命令列表

当当前工作目录是有效的 Cordova 项目时，支持这些命令。

常用选项

这些选项适用于所有 cordova-cli 命令。

平台特定选项

某些命令具有特定于特定平台的选项 (platformOpts)。它们可以通过 -- 分隔符提供给 cordova-cli，该分隔符会停止 cordova-lib 模块中的命令解析，并将剩余的选项传递给平台进行解析。

CLI 使用示例

以下示例说明了如何使用 Cordova CLI 执行各种任务，例如

• 创建项目
• 添加 camera 插件
• 在 android 平台上添加、构建和运行项目

此外，它还包括一个示例，展示了使用 Cordova-Android 平台提供的特定选项，例如 --keystore，它用于发布签名。

1. 创建 Cordova 项目

    cordova create myApp com.myCompany.myApp myApp
    cd myApp
   

2. 将相机插件添加到项目

    cordova plugin add cordova-plugin-camera
   

3. 将 Android 平台添加到项目

    cordova platform add android
   

4. 确认系统已配置为满足 Android 平台要求

    cordova requirements android
   

5. 使用启用详细日志记录的 Android 构建项目

    cordova build android --verbose
   

6. 在 Android 平台上运行项目

    cordova run android
   

7. 使用签名参数以发布模式构建 Android 项目

    cordova build android --release -- --keystore="..\android.keystore" --storePassword=android --alias=mykey
   

cordova create 命令

在指定路径中创建 Cordova 项目的目录结构。

命令语法

cordova create path [id [name]] [options]

参数

选项

目录结构

Cordova CLI 使用以下目录结构

myapp/
|-- config.xml
|-- merges/
| | |-- android/
| | |-- ios/
|-- www/
|-- platforms/
| |-- android/
| |-- ios/
|-- plugins/
  |-- cordova-plugin-camera/

config.xml

配置您的应用程序，并允许您自定义项目的行为。另请参见 config.xml 参考文档

www/

"www" 目录包含项目的 Web 工件，包括各种文件类型，其扩展名包括但不限于 .html、.css 和 .js。

作为 Cordova 应用程序开发人员，您的大部分代码和资产将放置在此目录中。在执行 cordova prepare 命令期间，"www" 目录的内容将复制到每个平台子目录中相应的 www 目录。例如，您可以在 platforms/ios/www 或 platforms/android/assets/www 中找到它。

需要注意的是，由于 CLI 定期从源 "www" 文件夹复制文件，因此您应该只对该目录中的文件进行编辑，并避免修改位于平台子目录中的文件。

如果您使用的是版本控制软件，建议将源 "www" 文件夹和 "merges" 文件夹都包含在您的版本控制系统中。

当使用需要转译过程的框架时，务必了解，最终输出（用于分发）应放置在 "www" 目录中。 "www" 目录的用途不是存储未转译的源代码。相反，建议将未转译的源代码保存在专门用于此目的的单独目录中。

platforms/

包含您添加到项目中的所有平台的源代码。

警告：当使用 CLI 构建应用程序时，除非您知道自己在做什么，或者文档另有说明，否则您不应编辑 /platforms/ 目录中的任何文件。此目录中的文件在准备应用程序进行构建或重新安装插件时会定期被覆盖。

plugins/

任何添加的插件都将被提取或复制到此目录中。

merges/

平台特定的 Web 资产（HTML、CSS 和 JavaScript 文件）包含在此目录中的适当子文件夹中。这些文件在 prepare 期间部署到相应的原生目录。放置在 merges/ 下的文件将覆盖相关平台的 www/ 文件夹中匹配的文件。一个简单的示例，假设项目结构为

merges/
|-- ios/
| -- app.js
|-- android/
| -- android.js
www/
-- app.js

构建 Android 和 iOS 项目后，Android 应用程序将同时包含 app.js 和 android.js。但是，iOS 应用程序将只包含 app.js，它将来自 merges/ios/app.js，覆盖位于 www/ 中的 "通用" app.js。

版本控制

为了确保更干净的版本控制设置，建议不要将 platforms/ 和 plugins/ 目录包含在您的版本控制系统中。这些目录被视为构建工件。相反，项目中使用的平台和插件会自动记录在 config.xml 和 package.json 文件中。当您调用 cordova prepare 命令时，将根据这些配置文件中指定的信息下载并设置必要的平台和插件。

通过将 platforms/ 和 plugins/ 目录从版本控制中排除，并依赖 config.xml 和 package.json 文件，您可以维护更简化的开发和持续集成工作流程。

示例

• 使用指定的 ID 和显示名称在 myapp 目录中创建一个 Cordova 项目

cordova create myapp com.mycompany.myteam.myapp MyApp

cordova platform 命令

管理 Cordova 平台 - 允许您添加、删除、更新和列出平台。运行添加或删除平台的命令会影响项目平台目录的内容。

命令语法

cordova {platform | platforms} [
    add <platform-spec> [...] {--save | link=<path> } |
    {remove | rm}  platform [...] {--save}|
    {list | ls}  |
    update ]

Platform-spec

有许多方法可以指定平台

<platform-spec> : platform[@version] | path | url[#commit-ish]

支持的平台

• android
• browser
• electron
• ios

示例

• 添加 android 和 ios 平台的锁定版本，并将下载的版本保存到 config.xml 和 package.json 中

cordova platform add android ios

• 使用 semver 版本 ^5.0.0 添加 android 平台，并将其保存到 config.xml 和 package.json 中

cordova platform add android@^5.0.0

• 通过克隆指定的 Git 存储库并检出到 4.0.0 标签来添加平台

cordova platform add https://github.com/myfork/cordova-android.git#4.0.0

• 使用名为 android 的本地目录添加平台

cordova platform add ../android

• 使用指定的压缩包添加平台

cordova platform add ../cordova-android.tgz

• 从项目中删除 android 平台，并从 config.xml 和 package.json 中删除

cordova platform rm android

• 从项目中删除 android 平台，但不要从 config.xml 和 package.json 中删除

cordova platform rm android --nosave

• 列出可用的和已安装的平台及其版本号。这在报告问题时很有用

cordova platform ls

cordova plugin 命令

管理项目插件

命令语法

cordova {plugin | plugins} [
    add <plugin-spec> [..] {--searchpath=<directory> | --noregistry | --link | --save | --force} |
    {remove | rm} {<pluginid> | <name>} --save |
    {list | ls}
]

Plugin-spec

有多种方法可以指定插件

<plugin-spec> : [@scope/]pluginID[@version]|directory|url[#commit-ish][:subdir]

解析插件的算法

将插件添加到项目时，CLI 将根据以下条件（按优先级顺序排列）解析插件

1. 命令中给出的 plugin-spec（例如 cordova plugin add pluginID@version）
2. 保存在 config.xml 和 package.json 中的 plugin-spec（即，如果插件之前是在没有 --nosave 的情况下添加的）
3. 从 Cordova 版本 6.1 开始，发布到 npm 的最新插件版本，当前项目可以支持（仅适用于在 package.json 中列出其 Cordova 依赖项 的插件）
4. 发布到 npm 的最新插件版本

示例

• 将 cordova-plugin-camera 和 cordova-plugin-file 添加到项目，并将其保存到 config.xml 和 package.json 中。使用 ../plugins 目录搜索插件。

    cordova plugin add cordova-plugin-camera cordova-plugin-file --searchpath ../plugins
  

• 使用 semver 版本 ^2.0.0 添加 cordova-plugin-camera，并将其保存到 config.xml 和 package.json 中

    cordova plugin add cordova-plugin-camera@^2.0.0
  

• 从指定的本地目录添加插件

    cordova plugin add ../cordova-plugin-camera
  

• 从指定的 tarball 文件添加插件

    cordova plugin add ../cordova-plugin-camera.tgz
  

• 从项目和 config.xml 和 package.json 中删除插件

    cordova plugin rm camera
  

• 从项目中删除插件，但不删除 config.xml 或 package.json

    cordova plugin rm camera --nosave
  

• 列出项目中安装的所有插件

    cordova plugin ls
  

冲突的插件

当添加在 plugin.xml 文件中使用 edit-config 标签的插件时，可能会出现冲突的插件。edit-config 允许插件添加或替换 XML 元素的属性。

如果多个插件尝试修改同一个 XML 元素，此功能会导致应用程序出现问题。已实施冲突检测以防止添加插件，从而避免一个插件尝试覆盖另一个插件的 edit-config 更改。当发现 edit-config 中的冲突时，将抛出错误，并且不会添加插件。错误消息将提到必须解决所有冲突才能添加插件。解决 edit-config 冲突的一种方法是对受影响的插件的 plugin.xml 进行更改，使其不再修改同一个 XML 元素。另一种方法是使用 --force 标志强制添加插件。此选项应谨慎使用，因为它会忽略冲突检测并覆盖与其他插件的所有冲突，因此可能会使其他插件处于不良状态。

有关管理 edit-config、解决冲突和示例，请参阅 plugin.xml 指南。

cordova prepare 命令

将 config.xml 元数据转换为特定于平台的清单文件，复制图标和启动画面，复制指定平台的插件文件，以便项目可以使用每个原生 SDK 进行构建。

命令语法

cordova prepare [<platform> [..]]

选项

cordova compile 命令

cordova compile 是 cordova build 命令 的一个子集。它只执行编译步骤，而不执行准备步骤。通常调用 cordova build 而不是此命令，但是，此阶段有助于使用 钩子 进行扩展。

命令语法

cordova compile [<platform> [...]]
    [--debug | --release]
    [--device | --emulator | --target=<targetName>]
    [--buildConfig=<configfile>]
    [-- <platformOpts>]

有关详细文档，请参阅下面的 cordova build 命令 文档。

cordova build 命令

对所有/指定平台执行 cordova prepare + cordova compile 的快捷方式。允许您为指定平台构建应用程序。

命令语法

cordova build [<platform> [...]]
    [--debug | --release]
    [--device | --emulator]
    [--buildConfig=<configfile>]
    [-- <platformOpts>]

示例

• 以 debug 模式为 android 和 ios 平台构建，以部署到设备

cordova build android ios --debug --device

• 以 release 模式为 android 平台构建，并使用指定的构建配置

cordova build android --release --buildConfig=..\myBuildConfig.json

• 以发布模式为 android 平台构建，并将自定义平台选项传递到 android 构建过程

cordova build android --release -- --keystore="..\android.keystore" --storePassword=android --alias=mykey

cordova run 命令

准备、构建和部署指定平台设备/模拟器上的应用程序。如果连接了设备，则将使用它，除非已运行合格的模拟器。

命令语法

cordova run [<platform> [...]]
    [--list | --debug | --release]
    [--noprepare]
    [--nobuild]
    [--device | --emulator | --target=<targetName>]
    [--buildConfig=<configfile>]
    [-- <platformOpts>]

示例

• 在名为 Nexus_5_API_23_x86 的 android 平台模拟器上运行当前 cordova 项目的发布构建。运行时使用指定的构建配置

cordova run android --release --buildConfig=..\myBuildConfig.json --target=Nexus_5_API_23_x86

• 使用设备或模拟器（如果未连接设备）运行当前 cordova 项目的调试构建。跳过构建

cordova run android --nobuild

• 在 ios 设备上运行当前 cordova 项目的调试构建

cordova run ios --device

• 枚举所有已连接设备和可用于运行此应用程序的可用模拟器的名称

cordova run ios --list

cordova emulate 命令

cordova run --emulator 的别名。启动模拟器而不是设备。有关更多详细信息，请参阅 cordova run 命令文档。

cordova clean 命令

通过运行特定于平台的构建清理，清理所有平台或指定平台的构建工件。

命令语法

cordova clean [<platform> [...]]

示例用法

• 清理 android 平台构建工件

cordova clean android

cordova requirements 命令

检查并打印出指定平台（或未指定则打印出添加到项目的所有平台）的所有要求。如果满足每个平台的所有要求，则退出代码为 0，否则退出代码为非零值。

这在为构建特定平台设置机器时非常有用。

命令语法

cordova requirements [platform?]

cordova info 命令

打印出有助于提交错误报告和获取帮助的有用信息。

命令语法

cordova info

cordova serve 命令

使用指定的 port 或默认的 8000 运行 www/ 资源的本地 Web 服务器。在以下位置访问项目：http://HOST_IP:PORT/PLATFORM/www

命令语法

cordova serve [port]

cordova telemetry 命令

打开或关闭遥测收集。

命令语法

cordova telemetry [State]

Details

第一次运行 cordova 时，会显示一个计时提示，要求用户选择加入或退出。它持续 30 秒，之后如果用户没有提供任何答案，则会自动选择退出。在 CI 环境中，可以设置 CI 环境变量，这将阻止提示出现。还可以使用 --no-telemetry 标志在单个命令上关闭遥测收集。

Usage Example

cordova telemetry on
cordova telemetry off
cordova build --no-telemetry

有关详细信息，请参阅我们的隐私声明：https://cordova.net.cn/privacy

cordova help 命令

显示语法摘要或特定命令的帮助。

命令语法

cordova help [command]
cordova [command] -h
cordova -h [command]

cordova config 命令

设置、获取、删除、编辑和列出全局 cordova 选项。

命令语法

cordova config [ls|edit|set|get|delete] <key?> <value?>

Usage Examples

cordova config ls
cordova config edit
cordova config set save-exact true
cordova config get save-exact
cordova config delete save-exact