Skip to main content

配置

文件​

¥Files

配置值存储在 JSON 文件中。Ionic CLI 维护一个全局配置文件（通常位于 ~/.ionic/config.json）和项目配置文件（通常位于项目根目录 ionic.config.json）。

¥Configuration values are stored in JSON files. The Ionic CLI maintains a global configuration file, usually located at ~/.ionic/config.json, and project configuration files, usually at the project's root directory as ionic.config.json.

CLI 提供用于设置和打印项目配置文件和全局 CLI 配置文件中的配置值的命令。请参阅 ionic config --help 或参阅 ionic config get 和 ionic config set 的使用文档。

¥The CLI provides commands for setting and printing config values from project config files and the global CLI config file. See ionic config --help or see the documentation for usage of ionic config get and ionic config set.

项目配置文件​

¥Project Configuration File

每个 Ionic 项目都有一个项目配置文件，通常位于项目的根目录中。以下是带注释的 ionic.config.json 文件。

¥Each Ionic project has a project configuration file, usually at the project's root directory. The following is an annotated ionic.config.json file.

{
  // 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": {
    ...
  }
}

环境变量​

¥Environment Variables

CLI 将查找以下环境变量：

¥The CLI will look for the following environment variables:

  • IONIC_CONFIG_DIRECTORY：全局 CLI 配置的目录。默认为 ~/.ionic。

    ¥IONIC_CONFIG_DIRECTORY: The directory of the global CLI config. Defaults to ~/.ionic.

  • IONIC_HTTP_PROXY：设置用于代理所有 CLI 请求的 URL。参见 使用代理。

    ¥IONIC_HTTP_PROXY: Set a URL for proxying all CLI requests through. See Using a Proxy.

  • IONIC_TOKEN：自动使用 应用流程 进行身份验证。

    ¥IONIC_TOKEN: Automatically authenticates with Appflow.

标志​

¥Flags

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

¥CLI flags are global options that alter the behavior of a CLI command.

  • --help：不要运行该命令，而是查看其帮助页面。

    ¥--help: Instead of running the command, view its help page.

  • --verbose：显示所有日志消息以进行调试。

    ¥--verbose: Show all log messages for debugging purposes.

  • --quiet：仅显示 WARN 和 ERROR 日志消息。

    ¥--quiet: Only show WARN and ERROR log messages.

  • --no-interactive：关闭交互式提示和奇特的输出。如果检测到 CI 或非 TTY 终端，CLI 将自动变为非交互式。

    ¥--no-interactive: Turn off interactive prompts and fancy outputs. If CI or a non-TTY terminal is detected, the CLI is automatically non-interactive.

  • --confirm：打开确认提示的自动确认。小心：CLI 在执行可能有害的操作之前会进行提示。自动确认可能会产生意想不到的结果。

    ¥--confirm: Turn on auto-confirmation of confirmation prompts. Careful: the CLI prompts before doing something potentially harmful. Auto-confirming may have unintended results.

钩子​

¥Hooks

CLI 可以在某些事件期间运行脚本，例如构建之前和之后。要挂接到 CLI，可以在 package.json 中使用以下 npm 脚本：

¥The CLI can run scripts during certain events, such as before and after builds. To hook into the CLI, the following npm scripts can be used in package.json:

  • ionic:serve:before：在开发服务器启动之前执行

    ¥ionic:serve:before: executed before the dev server starts

  • ionic:serve:after：开发服务器终止后执行

    ¥ionic:serve:after: executed after the dev server is terminated

  • ionic:build:before：在网络资源构建开始之前执行

    ¥ionic:build:before: executed before a web asset build begins

  • ionic:build:after：Web 资源构建完成后执行

    ¥ionic:build:after: executed after a web asset build finishes

  • ionic:capacitor:run:before：在执行 Capacitor 开路之前的 ionic capacitor run 期间执行

    ¥ionic:capacitor:run:before: executed during ionic capacitor run before capacitor open is executed

  • ionic:capacitor:build:before：在执行 Capacitor 开路之前的 ionic capacitor build 期间执行

    ¥ionic:capacitor:build:before: executed during ionic capacitor build before capacitor open is executed

  • ionic:capacitor:sync:after：同步后在 ionic capacitor sync 期间执行

    ¥ionic:capacitor:sync:after: executed during ionic capacitor sync after a sync

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

¥When using a shell script for any of the hooks, hook context is defined in environment variables prefixed with IONIC_CLI_HOOK_CTX_.

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

¥The following example shows the environment variables that are set for the 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 中定义。在项目中定义一个 hooks 对象，其中每个键是钩子的名称（不带 ionic: 前缀），值是 JavaScript 文件的路径或路径数组。

¥Hooks can also be defined in ionic.config.json. Define a hooks object within the project, where each key is the name of the hook (without the ionic: prefix), and the value is a path to a JavaScript file or an array of paths.

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

¥In the following example, the file is imported and run during the ionic:build:before hook.

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

JavaScript 钩子文件应导出单个函数，每当钩子执行时，都会向该函数传递单个参数 (ctx)。

¥JavaScript hook files should export a single function, which is passed a single argument (ctx) whenever the hook executes.

参数是给予钩子文件的上下文，每个钩子和不同的调用都不同。

¥The argument is the context given to the hook file, which differs from hook to hook and with different invocations.

./scripts/build-before.js：

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

多应用项目​

¥Multi-app Projects

Available in CLI 6.2.0+

Ionic CLI 支持多应用配置设置，其中涉及单个存储库或 monorepo 中的多个 Ionic 应用和共享代码。

¥The Ionic CLI supports a multi-app configuration setup, which involves multiple Ionic apps and shared code within a single repository, or monorepo.

注意

这些文档概述了 Ionic CLI 的多应用功能，但并未真正详细介绍每个框架。

¥These docs give an overview of the multi-app feature of the Ionic CLI, but don't really go into details for each framework.

如果你使用 Angular，请参阅 本文 作为示例。

¥If you're using Angular, please see this article for examples.

设置步骤​

¥Setup Steps

  1. 创建一个目录并初始化一个 monorepo（有关完整详细信息，请参阅 项目结构）。

    ¥Create a directory and initialize a monorepo (see Project Structure for full details).

  2. 将 monorepo 初始化为 Ionic 多应用项目。这将创建一个多应用 ionic.config.json 文件。完整详细信息请参见 配置文件。

    ¥Initialize the monorepo as an Ionic multi-app project. This will create a multi-app ionic.config.json file. See Config File for full details.

    $ ionic init --multi-app

  3. 使用 ionic start 创建 Ionic 应用或使用 ionic init 初始化现有应用（有关完整详细信息，请参阅 添加应用）。

    ¥Use ionic start to create Ionic apps or ionic init to initialize existing apps (see Adding an App for full details).

项目结构​

¥Project Structure

在多应用项目中，项目结构是灵活的。唯一的要求是存储库根目录下有一个多应用 ionic.config.json 文件。

¥In a multi-app project, project structure is flexible. The only requirement is a multi-app ionic.config.json file at the root of the repository.

下面是一个示例设置，其中 apps/ 目录中的应用与 lib/ 目录中的共享代码分开。请注意根 ionic.config.json 文件和 monorepo 的 package.json 文件。

¥Below is an example setup, where apps in the apps/ directory are separated from the shared code in the lib/ directory. Notice the root ionic.config.json file and the monorepo's package.json file.

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

配置文件​

¥Config File

在多应用项目中，应用在存储库的根目录下共享一个 ionic.config.json 文件，而不是每个应用都有自己的文件。多应用配置文件通过在 projects 对象中嵌套配置对象来包含每个应用的配置。可以使用 defaultProject 指定默认应用。

¥In a multi-app project, apps share a single ionic.config.json file at the root of the repository instead of each app having their own. The multi-app config file contains the configuration for each app by nesting configuration objects in a projects object. A default app can be specified using defaultProject.

下面是一个示例文件，它对应于上面的文件结构。

¥Below is an example file, which corresponds to the file structure above.

{
  "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 中配置的应用上下文中运行。项目选择标准如下：

¥When a multi-app project is detected, the Ionic CLI will operate under the context of an app configured in the root ionic.config.json. Project selection criteria is as follows:

  1. 如果指定了全局 CLI 选项 --project，则通过 projects 对象中的键查找项目。例如，--project=myApp 将选择 myApp 项目。

    ¥If the global CLI option --project is specified, the project is looked up by key in the projects object. For example, --project=myApp will select the myApp project.

  2. 如果 CLI 检测到它正在使用 root 键配置的项目路径中运行，它将选择匹配的项目。例如，在 apps/myOtherApp/src 目录中使用 CLI 将选择 myOtherApp 项目。

    ¥If the CLI detects it is being run within a project path, configured with the root key, it will select the matched project. For example, using the CLI within the apps/myOtherApp/src directory will select the myOtherApp project.

  3. 如果 ionic.config.json 中指定了 defaultProject，则当不满足上述条件时，将选择指定的项目。

    ¥If a defaultProject is specified in ionic.config.json, it will select the specified project when the above criteria is not met.

添加应用​

¥Adding an App

可以通过使用 ionic start 创建新应用或使用 ionic init 初始化现有应用在多应用项目中注册应用。

¥Apps can be registered in a multi-app project either by using ionic start to create new apps or ionic init to initialize existing apps.

使用 ionic start​

¥Using ionic start

如果在 ionic start 期间检测到多应用项目，CLI 会将应用配置添加到根 ionic.config.json 文件，而不是创建特定于项目的文件。

¥If a multi-app project is detected during ionic start, the CLI will add the app configuration to the root ionic.config.json file instead of creating a project-specific one.

如果依赖已提升到 monorepo 的根目录，则可以使用 --no-deps 跳过依赖安装。

¥Dependency installation can be skipped using --no-deps if dependencies are hoisted to the root of the monorepo.

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

使用 ionic init​

¥Using ionic init

如果应用是通过 ionic start 以外的方式创建的，例如使用预构建模板，请使用 ionic init 将现有应用注册到多应用项目。

¥If an app was created in a way other than ionic start, for example by using a prebuilt template, use ionic init to register the existing app with the multi-app project.

注意

确保应用没有现有的 ionic.config.json。

¥Make sure the app doesn't have an existing ionic.config.json.

$ cd apps/existing-app/
$ ionic init

高级配置​

¥Advanced Configuration

覆盖构建​

¥Overriding the Build

通常，CLI 根据项目类型运行一组硬编码的命令。例如，Angular 项目的标准 Web 资源构建是 ng run app:build。可以覆盖 Web 资源构建，并且可以通过利用 ionic:build npm 脚本 继续使用 ionic build。同样，可以使用 ionic:serve npm 脚本覆盖开发服务器。

¥Normally, the CLI runs a hard-coded set of commands based on the project type. For example, the standard web asset build for Angular projects is ng run app:build. The web asset build can be overridden and ionic build can continue to be used by utilizing the ionic:build npm script. Similarly, the dev server can be overridden by using the ionic:serve npm script.

请密切注意 Ionic CLI 提供给脚本的标志。如果不遵守选项，可能会出现异常情况，尤其是设备上的实时重载。

¥Pay close attention to the flags supplied to the script by the Ionic CLI. Irregularities may occur if options are not respected, especially for livereload on devices.

命令选项​

¥Command Options

命令选项可以用环境变量来表示。它们通常使用 --opt=value 语法设置。这些环境变量的命名遵循以下模式：从 IONIC_CMDOPTS_ 开始，添加命令名称（用下划线替换所有空格），添加选项名称（用下划线替换所有连字符），然后将所有内容大写。布尔标志（不带值的命令行选项）可以设置为 1 或 0。去除布尔标志中的 --no- 前缀（如果存在）（例如，Ionic 服务中的 --no-open 可以用 IONIC_CMDOPTS_SERVE_OPEN=0 表示）。

¥Command options can be expressed with environment variables. They are normally set with --opt=value syntax. The naming of these environment variables follows a pattern: start with IONIC_CMDOPTS_, add the command name (replacing any spaces with underscores), add the option name (replacing any hyphens with underscores), and then uppercase everything. Boolean flags (command-line options that don't take a value) can be set to 1 or 0. Strip the --no- prefix in boolean flags, if it exists (--no-open in ionic serve can be expressed with IONIC_CMDOPTS_SERVE_OPEN=0, for example).

例如 ionic cordova run ios -lc --livereload-port=1234 --host=0.0.0.0 中的命令选项也可以用这一系列环境变量来表示：

¥For example, the command options in ionic cordova run ios -lc --livereload-port=1234 --host=0.0.0.0 can also be expressed with this series of environment variables:

$ 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 将为其选项使用新的默认值。

¥If these variables are set in the environment, ionic cordova build ios will use new defaults for its options.

遥测​

¥Telemetry

CLI 将使用数据发送到 Ionic 以创造更好的体验。要禁用此功能，请运行 ionic config set -g telemetry false。

¥The CLI sends usage data to Ionic to create a better experience. To disable this functionality, run ionic config set -g telemetry false.

目录