命令行界面（CLI）

本文介绍如何使用 命令行界面（CLI）创建应用程序，并将它们部署到各种原生移动平台。这个工具允许你创建新的项目，在不同的平台构建，并运行在实际设备或仿真器中。 CLI 是用于在概述中描述的跨平台的工作流的主要工具。当然，你也可以使用 CLI 来初始化项目代码，然后切换到不同的平台的SDK和 shell 工具作为后续发展。

前提

使用 CLI 前，需安装目标平台的 SDK 。（详见平台开发指南）

CLI 支持平台情况：

• iOS (Mac)
• Amazon Fire OS (Mac, Linux, Windows)
• Android (Mac, Linux, Windows)
• BlackBerry 10 (Mac, Linux, Windows)
• Windows Phone 8 (Windows)
• Windows (Windows)
• Firefox OS (Mac, Linux, Windows)

注：对于只支持 Windows 的平台，可以在 Mac 机子上运行 Windows 的虚拟机，或者双启动形式运行 Windows。详见 Windows Phone 8 平台指南 和 Windows 平台指南

安装 Cordova CLI

安装 Cordova CLI 步骤如下：

1. 下载安装 Node.js
2. 下载安装 git 客户端。由于被墙，国内用户从官网下载困难，可异步至 Git for Windows 国内下载站
3. 使用 npm 安装 cordova 模块。国内用户可以通过设置镜像来加速安装，详见加速 npm

对于 OS X 和 Linux:

$ sudo npm install -g cordova

对于 Windows:

C:\>npm install -g cordova

创建应用

切换到源代码的目录，然后运行命令，如下所示：

$ cordova create hello com.waylau.cordova.hello HelloWorld

这可能需要一些时间命令完成，请耐心等待。命令行 -d 选项会显示进度信息。

第一个参数 hello 指定你的项目要生成的一个目录。这个目录原来不存在，Cordova 会为您创建它。其子目录 www 容纳您的应用程序的主页，以及在css，js和img的各种资源，遵循共同的 Web 开发文件命名约定。这些资源将被存储在设备上的本地文件系统，而不是在远程服务上。该config.xml文件中包含有需要生成和分发应用程序的重要元数据。

第二个参数输入 com.waylau.cordova.hello 提供了一个项目的反向域名风格的标识。此参数是可选的，如果省略该参数，则必须省略第三个参数。您可以之后在config.xml文件编辑这个值，但建议您一开始就选择合适的值，因为 config.xml 生产代码会用到这个值，就像 Java 的包名一样。若不设置此值，则默认值是io.cordova.hellocordova。

第三个参数的 HelloWorld 提供了应用程序的显示标题。此参数是可选的。您可以之后在config.xml文件编辑这个值，但建议您一开始就选择合适的值，因为 config.xml 生产代码会用到这个值，就像 Java 的包名一样。若不设置此值，则默认值是io.cordova.hellocordova。默认值是 HelloCordova 。

添加平台

所有后续命令都需要在项目的目录下，或者在其范围内的任何子目录中运行：

$ cd hello

在您可以构建项目前，你需要指定一组目标平台。您运行这些命令的能力取决于你的机器是否支持每个 SDK，以及是否已经安装每个 SDK。在 Mac 运行：

$ cordova platform add ios
$ cordova platform add amazon-fireos
$ cordova platform add android
$ cordova platform add blackberry10
$ cordova platform add firefoxos

Windows 运行，其中 wp 是指不同版本的 Windows Phone 操作系统的：

$ cordova platform add wp8
$ cordova platform add windows
$ cordova platform add amazon-fireos
$ cordova platform add android
$ cordova platform add blackberry10
$ cordova platform add firefoxos

查看当前支持的平台：

$ cordova platforms ls

（注意 platform 和 platforms 的命令是同义的。）

运行下列命令的代名词，移除一个平台：

$ cordova platform remove blackberry10
$ cordova platform rm amazon-fireos
$ cordova platform rm android

（注意 remove 和 rm 的命令是同义的。）

运行命令添加或删除平台，会影响了项目的 platforms目录，该目录下为每个指定的平台显示其子目录的内容。 www 的源目录转载到每个平台的子目录中，例如platforms/ios/www 或 platforms/android/assets/www。由于 CLI 会不断地从源 www 复制文件，你应该只编辑这些源文件，而不是那些platforms下的子目录。如果您使用的版本控制软件，你应该把这个源 www 文件夹，随着merges文件夹一起添加到你的版本控制系统。 （关于merges文件夹的更多信息，可以在下面“使用 merges 自定义每个平台”中找到）

警告：当使用 CLI 来构建应用程序，你不应该在/platforms/目录编辑任何文件，除非你知道自己在做什么，或者说明文件另有说明。当应用程序构建或者插件准备重新安装时，该目录中的文件是经常会被覆盖的。

如果你意识到了这点，你可以使用一个 SDK，如用 Eclipse 或 Xcode 来打开你创建的项目。您将需要从/platforms/目录下打开资源来开发SDK。这是因为SDK特定的元数据文件存储在相应的/platforms/子目录中。 （请参阅平台开发指南了解如何在每个IDE中开发应用程序。）如果你只是想用 CLI 初始化一个项目，然后切换到 SDK 的原生工作，那么请使用此方法。

如果你想在整个开发周期使用跨平台的工作流方法（CLI），请继续往下阅读。

构建应用程序

默认的，cordova create脚本将会创建一个基于web 应用程序的骨架，主页是www/index.html 文件。

迭代的构建程序，运行

$ cordova build

可以制定构建的平台

$ cordova build ios

cordova build是下面命令的简化：

$ cordova prepare ios
$ cordova compile ios

在这种情况下，一旦运行了 prepare，你可以用苹果的 Xcode 的 SDK，以替代修改和编译 Cordova 生成的 platforms/ios 特定于平台的代码。您可以使用同样的做法在其他平台的 SDK 中。

在模拟器或者设备上测试应用

SDK 为移动平台往往捆绑模拟器来执行设备的图像，这样就可以从主屏幕启动应用程序，查看它是如何与众多平台功能进行交互的。运行如下命令，在特定平台构建应用，查看在模拟器中执行效果：

$ cordova emulate android

一些移动平台上在默认情况下会模拟一个特定的设备，比如 iOS 项目默认是 iPhone。对于其他平台，您可能需要首先将设备与模拟器相关联。

注：模拟器的支持目前不适用于 Amazon Fire OS。

（请参阅平台开发指南了解详细信息。）例如，您可以先运行 android 命令来启动Android SDK，然后运行特定设备的图像，而根据它的默认行为启动它：

接着用cordova emulate命令刷新模拟器图像显示最新的应用程序，现在是可以从主屏幕启动：

或者，你可以将手机插入电脑，并直接测试应用程序：

$ cordova run android

在执行上述命令前，先要在设备上做设置。在 Android 和 Amazon Fire OS 上, 需要先启用“USB debugging”选项。 请参阅平台开发指南了解各个平台的设置。

添加插件

插件，可以使应用获得与设备级别交流的能力，提供了原生组件的接口。你可以自己设计插件，如，设计一个混合了 Cordova WebView 和原生组件的 hybrid 应用（详见 * 嵌入 WebViews 和 插件开发指南）

3.0 版本后，创建一个 Cordova 是不会存在任何插件的，你需要按照需要显示的添加插件。

可以在 http://plugins.cordova.io/ 查找插件，其中也包含第三方的插件。CLI 也能支持插件的查找。例如使用关键字bar、code 进行查找。

$ cordova plugin search bar code

com.phonegap.plugins.barcodescanner - Scans Barcodes

如果只是使用关键字bar，则查找结果为

cordova-plugin-statusbar - Cordova StatusBar Plugin

cordova plugin add命令是用来添加插件的，比如

• 基本设备信息(设备 API):

$ cordova plugin add cordova-plugin-device

• 网络连接和电池事件:

$ cordova plugin add cordova-plugin-network-information
$ cordova plugin add cordova-plugin-battery-status

• 加速度计，指南针，和地理位置:

$ cordova plugin add cordova-plugin-device-motion
$ cordova plugin add cordova-plugin-device-orientation
$ cordova plugin add cordova-plugin-geolocation

• 相机，媒体播放和捕捉：

$ cordova plugin add cordova-plugin-camera
$ cordova plugin add cordova-plugin-media-capture
$ cordova plugin add cordova-plugin-media

• 在设备或者网络上访问文件(File API):

$ cordova plugin add cordova-plugin-file
$ cordova plugin add cordova-plugin-file-transfer

• 通过对话框或振动通知：

$ cordova plugin add cordova-plugin-dialogs
$ cordova plugin add cordova-plugin-vibration

• 联系方式:

$ cordova plugin add cordova-plugin-contacts

• 全球化:

$ cordova plugin add cordova-plugin-globalization

• 闪屏:

$ cordova plugin add cordova-plugin-splashscreen

• 打开一个新的浏览器窗口 (InAppBrowser):

$ cordova plugin add cordova-plugin-inappbrowser

• 控制台调试:

$ cordova plugin add cordova-plugin-console

注：CLI 增加适合各个平台的插件代码。如果你想开发具有较低级别的 shel l工具或平台的 SDK，你需要运行 Plugman 工具来为每个平台单独添加的插件。 （请参阅使用 Plugman 来管理插件。）

plugin ls (或 plugin list, 或 plugin）查看当前已安装的插件。以唯一标识做为显示：

$ cordova plugin ls    # or 'plugin list'
[ 'cordova-plugin-console' ]

移除时，也用唯一标识来移除

$ cordova plugin rm cordova-plugin-console
$ cordova plugin remove cordova-plugin-console    # same

可以批量添加或者移除：

$ cordova plugin add cordova-plugin-console cordova-plugin-device

高级插件选项

添加插件时，@制定版本：

$ cordova plugin add cordova-plugin-console@latest
$ cordova plugin add [email protected]

非 registry.cordova.io注册的插件，也从其他 git 库添加：

$ cordova plugin add https://github.com/apache/cordova-plugin-console.git

#来指定一个标签（tag）

$ cordova plugin add https://github.com/apache/cordova-plugin-console.git#r0.2.0

或者一个分支：

$ cordova plugin add https://github.com/apache/cordova-plugin-console.git#CB-8438cordova-plugin-console

或者是一个提交：

$ cordova plugin add https://github.com/apache/cordova-plugin-console.git#f055daec45575bf08538f885e09c85a0eba363ff

如果插件（以及 plugin.xml 文件 ），是在 git 库的子目录，使用:

$ cordova plugin add https://github.com/someone/aplugin.git#:/my/sub/dir

当然也能做如下合并：

$ cordova plugin add https://github.com/someone/aplugin.git#r0.0.1:/my/sub/dir

或者，指定一个包含 plugin.xml 文件的本地插件目录：

$ cordova plugin add ../my_plugin_dir

使用 merges 自定义每个平台

虽然 Cordova 让您可以轻松地部署应用程序在许多不同的平台上，有时你需要添加一些自定义功能。在这种情况下，你不希望修改各种platforms目录下的 www 目录中的源文件，因为他们经常会被顶级www目录的跨平台源所取代。

取而代之的是，顶层merges目录提供指定资源来部署在特定平台上的地方。merges镜像中的每个特定平台的子目录反映了www源代码树的目录结构，使您能够覆盖或根据需要添加文件。例如，下面演示了如何使用merges以提高 Android 和Amazon Fire OS 设备的默认字体大小：

• 编辑 www/index.html, 添加额外的 CSS 文件 overrides.css:

<link rel="stylesheet" type="text/css" href="css/overrides.css" />

• 可选创建一个空的www/css/overrides.css文件,应用于非 Android 的构建, 防止文件丢失的错误。

• 在merges/android 下创建一个css子目录，再加入相应的overrides.css文件。在www/css/index.css中指定的字体大小，例如：

body { font-size:14px; }

在重构项目中，Android 版本采用了自定义字体大小，而其他的维持不变。

还可以使用的merges来添加不存在于原始www目录中的文件。例如，一个应用程序可以将一个“后退按钮”图形插入iOS界面，存储在merges/ios/img/back_button.png，而 Android 版本，可以改为从相应的硬件按钮事件捕捉[backbutton](../../cordova/events/events.backbutton.html)。

帮助命令

遇到问题，请呼唤“帮助”。执行：

$ cordova help
$ cordova        # same

此外，你可以得到一个更详细的帮助。 例如

$ cordova run --help

info 命令产生的潜在有用的信息，如当前已安装的平台和插件，每个平台 SDK 版本，CLI 和 Node.js的版本信息列表：

$ cordova info

它既在屏幕上展示信息，并输出到本地info.txt。

注：目前，仅适用于 iOS 和 Android 平台的详细信息。

更新 Cordova 和你的项目

使用如下命令更新 cordova:

$ sudo npm update -g cordova

安装特定版本

$ sudo npm install -g [email protected]

运行cordova -v来查看当前运行的版本， to see which version is currently running. 运行 npm info 来获取当前版本以及可用版本的信息:

$ npm info cordova

Cordova 3.0 是支持本节所述的命令行界面的第一个版本。如果您是从之前的版本更新到 3.0，则需要如上所述创建一个新的项目，那么旧的应用程序的资源复制到顶层www目录。有关升级到 3.0 的进一步的细节，参考平台开发指南。一旦您升级到cordova 的命令行界面，并使用 npm update 保持同步。

Cordova 3.0+ 可能仍然会有各种变化，包括项目级目录结构和其他依赖。在运行 npm命令来更新 Cordova 本身后，你可能需要确保项目的资源是符合最新版本的要求。运行命令，如下：

$ cordova platform update android
$ cordova platform update ios
...etc.

源码

• 本文所用源码，见 https://github.com/waylau/cordova-dev-guide 的samples 目录下 hello