跳至主要内容
版本: 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，用于通过代理发送所有 CLI 请求。参见 使用代理。
  • IONIC_TOKEN: 自动使用 Appflow 进行身份验证。

标志​

CLI 标志是全局选项，用于改变 CLI 命令的行为。

  • --help: 而不是运行命令，查看其帮助页面。
  • --verbose: 显示所有日志消息，用于调试目的。
  • --quiet: 仅显示 WARN 和 ERROR 日志消息。
  • --no-interactive: 关闭交互式提示和花哨的输出。如果检测到 CI 或非 TTY 终端，CLI 将自动变为非交互式。
  • --confirm: 打开对确认提示的自动确认。注意：CLI 在执行可能造成损害的操作之前会提示确认。自动确认可能会导致意外结果。

钩子​

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 期间，在同步之后执行

当使用 shell 脚本执行任何钩子时，钩子上下文定义在以 IONIC_CLI_HOOK_CTX_ 为前缀的环境变量中。

以下示例显示了为 ionic:capacitor:build 钩子设置的环境变量。

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 中定义。在项目中定义一个 hooks 对象，其中每个键都是钩子的名称（不带 ionic: 前缀），值是 JavaScript 文件的路径或路径数组。

在以下示例中，该文件在 ionic:build:before 钩子期间被导入并运行。

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

JavaScript 钩子文件应该导出单个函数，该函数在钩子执行时传递一个参数（ctx）。

该参数是传递给钩子文件的上下文，它因钩子的不同而异，在不同的调用中也会有所不同。

./scripts/build-before.js:

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

多应用项目​

在 CLI 6.2.0+ 中可用

Ionic CLI 支持多应用配置设置，其中涉及多个 Ionic 应用和一个仓库内的共享代码，或者 monorepo。

注意

这些文档概述了 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。

内容

编辑此页面