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/ 中的 “common” app.js。

版本控制

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

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

示例

• 在 myapp 目录中使用指定的 ID 和显示名称创建一个 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[@version] | path | url[#commit-ish]

支持的平台

• android
• browser
• electron
• ios

示例

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

cordova platform add android ios

• 添加 android 平台，使用 semver 版本 ^5.0.0 并将其保存到 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

• 使用指定的 tarball 添加平台

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

• 在 android 平台上使用设备或模拟器（如果未连接设备）运行当前 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]

详情

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

使用示例

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?>

使用示例

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