跳至主要內容
版本：v8

設定

檔案​

設定值儲存在 JSON 檔案中。Ionic CLI 維護一個全域設定檔，通常位於 ~/.ionic/config.json，以及專案設定檔，通常位於專案的根目錄中，名為 ionic.config.json。

CLI 提供指令來設定和列印專案設定檔和全域 CLI 設定檔中的設定值。請參閱 ionic config --help 或參閱 ionic config get 和 ionic config set 的文件以了解用法。

專案設定檔​

每個 Ionic 專案都有一個專案設定檔，通常位於專案的根目錄中。以下是一個附帶註解的 ionic.config.json 檔案。

{
  // The human-readable name of the app.
  "name": "My App",

  // The project type of the app. The CLI uses this value to determine which
  // commands and command options are available, what to output for help
  // documentation, and what to use for web asset builds and the dev server.
  "type": "angular",

  // The App ID for Appflow.
  "id": "abc123",

  // Configuration object for integrations such as Cordova and Capacitor.
  "integrations": {
    "cordova": {
      ...
    }
  },

  // Hook configuration--see the Hooks section below for details.
  "hooks": {
    ...
  }
}

環境變數​

CLI 將尋找以下環境變數

  • IONIC_CONFIG_DIRECTORY：全域 CLI 設定的目錄。預設為 ~/.ionic。
  • IONIC_HTTP_PROXY：設定一個 URL 以透過該 URL 代理所有 CLI 請求。請參閱使用 Proxy。
  • IONIC_TOKEN：自動使用 Appflow 驗證。

旗標​

CLI 旗標是全域選項，可變更 CLI 命令的行為。

  • --help：檢視命令的幫助頁面，而不是執行命令。
  • --verbose：顯示所有除錯用的記錄訊息。
  • --quiet：僅顯示 WARN 和 ERROR 記錄訊息。
  • --no-interactive：關閉互動式提示和精美輸出。如果偵測到 CI 或非 TTY 終端機，CLI 會自動進入非互動式模式。
  • --confirm：開啟自動確認提示的自動確認功能。注意：CLI 在執行可能有害的操作之前會提示。自動確認可能會產生意想不到的結果。

Hook​

CLI 可以在特定事件期間執行腳本，例如在建置之前和之後。若要掛鉤 CLI，可以在 package.json 中使用以下 npm 腳本

  • ionic:serve:before：在開發伺服器啟動之前執行
  • ionic:serve:after：在開發伺服器終止後執行
  • ionic:build:before：在 Web 資源建置開始之前執行
  • ionic:build:after：在 Web 資源建置完成後執行
  • ionic:capacitor:run:before：在 ionic capacitor run 期間，在執行 capacitor open 之前執行
  • ionic:capacitor:build:before：在 ionic capacitor build 期間，在執行 capacitor open 之前執行
  • ionic:capacitor:sync:after：在 ionic capacitor sync 期間，在同步之後執行

當針對任何 Hook 使用 Shell 腳本時，Hook 內容會在環境變數中定義，並以 IONIC_CLI_HOOK_CTX_ 作為前綴。

以下範例顯示為 ionic:capacitor:build Hook 設定的環境變數。

IONIC_CLI_HOOK_CTX_NAME=capacitor:build:before
IONIC_CLI_HOOK_CTX_BUILD_CORDOVA_ASSETS=true
IONIC_CLI_HOOK_CTX_BUILD_ENGINE=browser
IONIC_CLI_HOOK_CTX_BUILD_PROJECT=app
IONIC_CLI_HOOK_CTX_BUILD_TYPE=angular
IONIC_CLI_HOOK_CTX_BUILD_VERBOSE=false
IONIC_CLI_HOOK_CTX_CAPACITOR_APP_ID=io.ionic.starter
IONIC_CLI_HOOK_CTX_CAPACITOR_APP_NAME=ionic-starter-app
IONIC_CLI_HOOK_CTX_CAPACITOR_VERBOSE=false

也可以在 ionic.config.json 中定義 Hook。在專案中定義一個 hooks 物件，其中每個鍵是 Hook 的名稱（不含 ionic: 前綴），而值是 JavaScript 檔案的路徑或路徑陣列。

在以下範例中，檔案會在 ionic:build:before Hook 期間匯入並執行。

"hooks": {
  "build:before": "./scripts/build-before.js"
},

JavaScript Hook 檔案應該匯出一個單一函式，每當 Hook 執行時，該函式會傳遞一個單一引數 (ctx)。

引數是提供給 Hook 檔案的內容，該內容因 Hook 而異，且因不同的叫用而異。

./scripts/build-before.js:

module.exports = function (ctx) {
  console.log(ctx);
};

多應用程式專案​

適用於 CLI 6.2.0+

Ionic CLI 支援多應用程式設定，其中涉及在單一儲存庫或 monorepo 中有多個 Ionic 應用程式和共用程式碼。

注意

這些文件概述了 Ionic CLI 的多應用程式功能，但並未真正深入探討每個框架的詳細資訊。

如果您使用 Angular，請參閱 這篇文章以取得範例。

設定步驟​

  1. 建立一個目錄並初始化一個 monorepo（請參閱專案結構以了解完整詳細資訊）。

  2. 將 monorepo 初始化為 Ionic 多應用程式專案。這將建立一個多應用程式 ionic.config.json 檔案。請參閱設定檔以了解完整詳細資訊。

    $ ionic init --multi-app

  3. 使用 ionic start 建立 Ionic 應用程式或使用 ionic init 初始化現有的應用程式（請參閱新增應用程式以了解完整詳細資訊）。

專案結構​

在多應用程式專案中，專案結構具有彈性。唯一的要求是在儲存庫的根目錄中有一個多應用程式 ionic.config.json 檔案。

以下是一個範例設定，其中 apps/ 目錄中的應用程式與 lib/ 目錄中的共用程式碼分開。請注意根目錄中的 ionic.config.json 檔案和 monorepo 的 package.json 檔案。

apps/
├── myApp/
└── myOtherApp/
lib/
ionic.config.json
package.json

設定檔​

在多應用程式專案中，應用程式會在儲存庫的根目錄中共用單一 ionic.config.json 檔案，而不是每個應用程式都有自己的檔案。多應用程式設定檔會在 projects 物件中巢狀配置設定物件，來包含每個應用程式的設定。可以使用 defaultProject 指定預設應用程式。

以下是一個範例檔案，對應到上述的檔案結構。

{
  "defaultProject": "myApp",
  "projects": {
    "myApp": {
      "name": "My App",
      "integrations": {},
      "type": "angular",
      "root": "apps/myApp"
    },
    "myOtherApp": {
      "name": "My Other App",
      "integrations": {},
      "type": "angular",
      "root": "apps/myOtherApp"
    }
  }
}

當偵測到多應用程式專案時，Ionic CLI 將在根目錄 ionic.config.json 中設定的應用程式內容下運作。專案選取條件如下

  1. 如果指定了全域 CLI 選項 --project，則會在 projects 物件中按鍵查找專案。例如，--project=myApp 將選取 myApp 專案。
  2. 如果 CLI 偵測到正在專案路徑內執行，並使用 root 鍵設定，則它會選取相符的專案。例如，在 apps/myOtherApp/src 目錄中使用 CLI 將選取 myOtherApp 專案。
  3. 如果在 ionic.config.json 中指定了 defaultProject，則當不符合上述條件時，它會選取指定的專案。

新增應用程式​

可以使用 ionic start 來建立新的應用程式，或使用 ionic init 來初始化現有的應用程式，在多應用程式專案中註冊應用程式。

使用 ionic start​

如果在 ionic start 期間偵測到多應用程式專案，CLI 會將應用程式設定新增至根目錄 ionic.config.json 檔案，而不是建立專案專用的檔案。

如果將依賴項提升到 monorepo 的根目錄，可以使用 --no-deps 來略過依賴項安裝。

$ cd apps/
$ ionic start "My New App" --no-deps

使用 ionic init​

如果應用程式不是以 ionic start 的方式建立（例如使用預先建置的範本），請使用 ionic init 將現有的應用程式註冊到多應用程式專案。

注意

請確定應用程式沒有現有的 ionic.config.json。

$ cd apps/existing-app/
$ ionic init

進階設定​

覆寫建置​

通常，CLI 會根據專案類型執行一組硬式編碼的命令。例如，Angular 專案的標準 Web 資源建置是 ng run app:build。可以使用 ionic:build npm 腳本來覆寫 Web 資源建置，並且可以繼續使用 ionic build。同樣地，可以使用 ionic:serve npm 腳本來覆寫開發伺服器。

請密切注意 Ionic CLI 提供給腳本的旗標。如果未遵循選項，可能會發生不規則情況，尤其是在裝置上使用即時重新載入時。

命令選項​

命令選項可以使用環境變數來表達。它們通常使用 --opt=value 語法來設定。這些環境變數的命名遵循一個模式：以 IONIC_CMDOPTS_ 開頭，加上命令名稱（將任何空格替換為底線），加上選項名稱（將任何連字符替換為底線），然後將所有內容轉換為大寫。布林標記（不帶值的命令列選項）可以設定為 1 或 0。如果存在，則去除布林標記中的 --no- 前綴 (例如，在 ionic serve 中的 --no-open 可以用 IONIC_CMDOPTS_SERVE_OPEN=0 來表達)。

例如，ionic cordova run ios -lc --livereload-port=1234 --host=0.0.0.0 中的命令選項也可以用以下一系列環境變數來表達

$ export IONIC_CMDOPTS_CORDOVA_RUN_LIVERELOAD=1
$ export IONIC_CMDOPTS_CORDOVA_RUN_CONSOLELOGS=1
$ export IONIC_CMDOPTS_CORDOVA_RUN_LIVERELOAD_PORT=1234
$ export IONIC_CMDOPTS_CORDOVA_RUN_HOST=0.0.0.0

如果在環境中設定了這些變數，ionic cordova build ios 將會使用新的預設選項。

遙測資料​

CLI 會將使用情況資料傳送給 Ionic，以創造更好的體驗。若要停用此功能，請執行 ionic config set -g telemetry false。

目錄

編輯此頁面