Cordova 命令列介面 (CLI) 命令

CLI 語法

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

全域命令列表

這些命令在任何時候都可用。

命令	描述
`create`	建立專案
`help <command>`	取得命令的說明
`telemetry`	開啟或關閉遙測資料收集
`config`	設定、取得、刪除、編輯和列出全域 Cordova 選項

專案命令列表

當目前的工作目錄是一個有效的 Cordova 專案時，支援這些命令。

命令	描述
`info`	產生專案資訊
`requirements`	檢查並列印出指定平台的所有安裝需求
`platform`	管理專案平台
`plugin`	管理專案外掛
`prepare`	複製檔案到平台以進行建置
`compile`	編譯平台的專案
`build`	建置平台的專案 (`prepare` + `compile`)
`clean`	清除專案的建置成品
`run`	執行專案 (包括 prepare && compile)
`serve`	使用本機 Web 伺服器執行專案 (包括 prepare)

常用選項

這些選項適用於所有 cordova-cli 命令。

選項	描述
-d 或 --verbose	將更詳細的輸出傳送到您的 shell。如果您將 `cordova-cli` 作為節點模組使用，也可以透過呼叫 `cordova.on('log', function() {})` 或 `cordova.on('warn', function() {})` 來訂閱 `log` 和 `warn` 事件。
-v 或 --version	列印出您安裝的 `cordova-cli` 版本。
--nohooks	抑制執行 Hook (將 RegExp Hook 模式作為參數)
--no-telemetry	停用目前命令的遙測資料收集。

平台特定選項

某些命令具有特定於特定平台的選項 (platformOpts)。它們可以使用 '--' 分隔符號提供給 cordova-cli，該分隔符號會停止 cordova-lib 模組內的命令解析，並將其餘選項傳遞給平台進行解析。

CLI 使用範例

以下範例說明如何使用 Cordova CLI 執行各種任務，例如

建立專案
新增 camera 外掛
在 android 平台上新增、建置和執行專案

此外，它還包含一個範例，展示了如何使用 Cordova-Android 平台提供的特定選項，例如用於發佈簽名的 --keystore。

建立 Cordova 專案

 cordova create myApp com.myCompany.myApp myApp
 cd myApp

將相機外掛新增到專案

 cordova plugin add cordova-plugin-camera

將 Android 平台新增到專案
```
 cordova platform add android
```
確認系統已設定 Android 平台需求
```
 cordova requirements android
```
啟用詳細記錄，為 Android 建置專案
```
 cordova build android --verbose
```
在 Android 平台上執行專案
```
 cordova run android
```

使用簽署參數以發佈模式為 Android 建置專案

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

`cordova create` 命令

在指定的路徑中建立 Cordova 專案的目錄結構。

命令語法

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

參數

值	描述
path	不應已存在的目錄。Cordova 將建立此目錄。有關目錄結構的更多詳細資訊，請參閱下方。
id	預設值：`io.cordova.hellocordova` 反向網域樣式的識別碼，對應於 `config.xml` 中 `widget` 元素的 `id` 屬性。這可以變更，但可能會使用此值產生程式碼，例如 Java 套件名稱。建議您選擇適當的值。
name	預設值：`HelloCordova` 應用程式的顯示標題，對應於 `config.xml` 檔案中的 `name` 元素。這可以變更，但可能會使用此值產生程式碼，例如 Java 類別名稱。預設值為 `HelloCordova`，但建議您選擇適當的值。

選項

選項	描述
--template	使用本機、NPM 或 GitHub 中自訂的範本。

目錄結構

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 ]

子命令	選項	描述
add `<platform-spec>` […]		新增指定的平台
	--nosave	在使用 `<engine>` 標籤安裝後，請勿將 `<platform-spec>` 儲存到 `config.xml` 和 `package.json` 中
	--link=`<path>`	當 `<platform-spec>` 是本機路徑時，直接連結平台程式庫，而不是複製它 (支援因平台而異；適用於平台開發)
remove `<platform>` […]		移除指定的平台
	--nosave	從 `config.xml` 和 `package.json` 中移除指定的平台後，請勿從它們中刪除指定的平台
update `<platform>` […]		更新指定的平台
	--save	更新 `config.xml` 中指定的版本
list		列出所有已安裝和可用的平台

平台規格

有許多方法可以指定平台

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

值	描述
platform	要新增到專案的平台名稱，例如 android、ios、electron 等。每個版本的 Cordova CLI 都會為每個平台釘選一個版本。當未指定版本時，會使用此版本新增平台。
version	使用 semver 的 Major.minor.patch 版本指定器
path	包含平台的目錄或 tarball 的路徑
url	包含平台的 Git 儲存庫或 tarball 的 URL
commit-ish	Commit/標籤/分支參考。如果未指定，則使用 'master'

支援的平台

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}
]

子命令	選項	描述
add `<plugin-spec>` […]		新增指定的外掛
	--searchpath `<directory>`	依 ID 查詢外掛時，在點擊登錄檔之前，先在此目錄及其每個子目錄中尋找。可以指定多個搜尋路徑。在以 `*nix` 為基礎的系統中使用 ':' 作為分隔符號，在 Windows 中使用 ';'。
	--noregistry	不要在登錄檔中搜尋外掛。
	--link	從本機路徑安裝時，建立符號連結而不是複製檔案。連結檔案的程度因平台而異。適用於外掛開發。
	--nosave	請勿將 `<plugin-spec>` 作為 `plugin` 元素的一部分儲存到 `config.xml` 或 `package.json` 中。
	--force	在 6.1 版本中引入。強制從外掛程式複製來源檔案，即使目標目錄中已存在相同檔案。
移除 `<pluginid>\\|<name>` […]		移除具有指定 ID/名稱的外掛程式。
	--nosave	請勿從 config.xml 或 package.json 中移除指定的外掛程式
list		列出目前已安裝的外掛程式

外掛程式規格 (Plugin-spec)

有多種方式可以指定外掛程式

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

值	描述
範圍 (scope)	發佈為 scoped npm 套件的外掛程式範圍
plugin	外掛程式 ID (npm 註冊表或 --searchPath 中的外掛程式 ID)
version	使用 semver 的 Major.minor.patch 版本指定器
目錄 (directory)	包含 plugin.xml 的目錄
url	包含 plugin.xml 的 git 儲存庫 URL
commit-ish	Commit/標籤/分支參考。如果未指定，則使用 'master'

解析外掛程式的演算法

當向專案新增外掛程式時，CLI 將根據以下條件解析外掛程式（依優先順序排列）

命令中給定的 plugin-spec (例如 cordova plugin add pluginID@version)
儲存在 config.xml & package.json 中的 plugin-spec (也就是說，如果外掛程式先前已新增但未使用 --nosave)
自 Cordova 6.1 版本起，發佈到 npm 且目前專案可以支援的最新外掛程式版本 (僅適用於在其 package.json 中列出 Cordova 依賴項的外掛程式)
發佈到 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> [..]]

選項

選項	描述
`<platform> [..]`	要準備的平台名稱。如果未指定，則準備所有平台。

`cordova compile` 命令

cordova compile 是 cordova build 命令的子集。它僅執行編譯步驟，而不進行準備。通常會叫用 cordova build 而不是此命令 - 但是，此階段對於使用 hook 進行擴充很有用。

命令語法

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

選項	描述
`<platform> [..]`	要建置的平台名稱。如果未指定，則建置所有平台。
--debug	執行偵錯建置。這通常轉換為正在建置的基礎平台的偵錯模式。
--release	執行發行建置。這通常轉換為正在建置的基礎平台的發行模式。
--device	為裝置建置
--emulator	為模擬器建置。特別是，裝置與模擬器的平台架構可能不同。
--buildConfig=`<configFile>`	預設值：cordova 根目錄中的 build.json。使用指定的建置組態檔案。`build.json` 檔案用於指定自訂應用程式建置程序（特別是與簽署套件相關）的參數。
`<platformOpts>`	若要提供平台特定的選項，您必須將它們包含在 `--` 分隔符號之後。請檢閱平台指南文件以取得更多詳細資訊。

範例

為 android 和 ios 平台以 debug 模式建置，以便部署到裝置

cordova build android ios --debug --device

為 android 平台以 release 模式建置，並使用指定的建置組態

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

選項	描述
`<platform> [..]`	要執行的平台名稱。如果未指定，則執行所有平台。
--list	列出可用的目標。除非指定，否則會顯示裝置和模擬器部署目標
--debug	部署偵錯建置。除非指定 `--release`，否則這是預設行為。
--release	部署發行建置
--noprepare	略過準備 (在 Cordova v6.2 或更高版本中可用)
--nobuild	略過建置
--device	部署到裝置
--emulator	部署到模擬器
--target	部署到特定的目標模擬器/裝置。使用 `--list` 顯示目標選項
--buildConfig=`<configFile>`	預設值：cordova 根目錄中的 build.json。使用指定的建置組態檔案。`build.json` 檔案用於指定自訂應用程式建置程序（特別是與簽署套件相關）的參數。
`<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/ 資產執行本機網頁伺服器。在以下位置存取專案：http://HOST_IP:PORT/PLATFORM/www

命令語法

cordova serve [port]

`cordova telemetry` 命令

開啟或關閉遙測收集。

命令語法

cordova telemetry [State]

狀態	描述
on	開啟遙測收集。
off	關閉遙測收集。

詳細資料

第一次執行 cordova 時，會顯示一個定時提示，要求使用者選擇加入或退出。它會持續 30 秒，之後如果使用者未提供任何答案，則會自動退出。在 CI 環境中，可以設定 CI 環境變數，這將防止顯示提示。也可以使用 --no-telemetry 旗標在單一命令中關閉遙測收集。

用法範例

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

有關詳細資訊，請參閱我們的隱私權聲明：https://cordova.dev.org.tw/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

Cordova 命令列介面 (CLI) 命令

CLI 語法

全域命令列表

專案命令列表

常用選項

平台特定選項

CLI 使用範例

cordova create 命令

目錄結構

config.xml

www/

platforms/

plugins/

merges/

版本控制

範例

cordova platform 命令

平台規格

支援的平台

範例

cordova plugin 命令

外掛程式規格 (Plugin-spec)

解析外掛程式的演算法

範例

衝突的外掛程式

cordova prepare 命令

選項

cordova compile 命令

cordova build 命令

範例

cordova run 命令

範例

cordova emulate 命令

cordova clean 命令

cordova requirements 命令

cordova info 命令

cordova serve 命令

cordova telemetry 命令

詳細資料

cordova help 命令

cordova config 命令

`cordova create` 命令

`cordova platform` 命令

`cordova plugin` 命令

`cordova prepare` 命令

`cordova compile` 命令

`cordova build` 命令

`cordova run` 命令

`cordova emulate` 命令

`cordova clean` 命令

`cordova requirements` 命令

`cordova info` 命令

`cordova serve` 命令

`cordova telemetry` 命令

`cordova help` 命令

`cordova config` 命令