Angular 工作区配置link

Angular Workspace Configurationlink

Angular 工作区根目录下的 angular.json 文件提供了全工作区级的配置和具体项目的默认配置，供 Angular CLI 中的构建工具和开发工具使用。 此配置中所提供的路径值都是相对于工作区根目录的。

A file named angular.json at the root level of an Angular workspace provides workspace-wide and project-specific configuration defaults for build and development tools provided by the Angular CLI. Path values given in the configuration are relative to the root workspace folder.

JSON 的总体结构link

Overall JSON structurelink

在 angular.json 的顶级，一些属性用于配置工作区，其中的 projects 区则包含其余的针对每个项目的配置项。CLI 在工作空间级的默认设置可以被项目级的设置所覆盖，而项目级的设置可以被命令行中的设置所覆盖。

At the top level of angular.json, a few properties configure the workspace, and a projects section contains the remaining per-project configuration options. CLI defaults set at the workspace level can be overridden by defaults set at the project level, and defaults set at the project level can be overridden on the command line.

下列属性位于文件的顶级，用于配置工作空间。

The following properties, at the top level of the file, configure the workspace.

• version：该配置文件的版本。

  version: The configuration-file version.

• newProjectRoot：用来创建新工程的位置。绝对路径或相对于工作区目录的路径。

  newProjectRoot: Path where new projects are created. Absolute or relative to the workspace folder.

• defaultProject：当命令中没有指定参数时，要使用的默认工程名。当你用 ng new 在新的工作区中创建新应用时，该应用就会一直作为此工作区的默认项目，除非你到这里修改它。

  defaultProject: Default project name to use in commands, where not provided as an argument. When you use ng new to create a new app in a new workspace, that app is the default project for the workspace until you change it here.

• schematics：一组原理图，用于定制 ng generate 子命令在本工作空间中的默认选项。参见稍后的生成器原理图。

  schematics : A set of schematics that customize the ng generate sub-command option defaults for this workspace. See Generation schematics below.

• projects：对于工作区中的每个项目（应用或库）都会包含一个子分区，子分区中是每个项目的配置项。

  projects : Contains a subsection for each project (library or application) in the workspace, with the per-project configuration options.

你通过 ng new app_name 命令创建的初始应用会列在 projects 目录下：

The initial app that you create with ng new app_name is listed under "projects":

      
        content_copy
      
      "projects": {
  "app_name": {
    ...
  }
  ...
}
    

你使用 ng generate application 创建的每个应用都有相应的端到端测试项目，它有自己的配置节。当你使用 ng generate library 创建库项目时，库项目也会添加到 projects 节。

Each additional app that you create with ng generate application has a corresponding end-to-end test project, with its own configuration section. When you create a library project with ng generate library, the library project is also added to the projects section.

项目配置选项link

Project configuration optionslink

每个项目的 projects:<project_name> 下都有以下顶级配置属性。

The following top-level configuration properties are available for each project, under projects:<project_name>.

      
        content_copy
      
      "my-app": {
  "root": "",
  "sourceRoot": "src",
  "projectType": "application",
  "prefix": "app",
  "schematics": {},
  "architect": {}
}
    

生成器原理图link

Generation schematicslink

Angular 生成器的原理图是一组用来修改项目的指南，包括添加新文件或修改现有文件。 默认情况下，Angular CLI 的 ng generate 子命令会从 @angular 包中收集原理图。 可以用 schematic-package:schematic-name 格式来为子命令指定原理图名称；比如，用来生成组件的原理图名叫@angular:component。

Angular generation schematics are instructions for modifying a project by adding files or modifying existing files. Individual schematics for the default Angular CLI ng generate sub-commands are collected in the package @angular. Specify the schematic name for a subcommand in the format schematic-package:schematic-name; for example, the schematic for generating a component is @angular:component.

供 CLI 生成项目及其部件的默认原理图的 JSON 模式（schema）位于 @schematics/angular包中。 这个模式描述了 CLI ng generate 子命令的每个选项，它们会显示在 --help 的输出中。

The JSON schemas for the default schematics used by the CLI to generate projects and parts of projects are collected in the package @schematics/angular. The schema describes the options available to the CLI for each of the ng generate sub-commands, as shown in the --help output.

这个模式中的每个字段都对应于 CLI 子命令选项的参数取值范围和默认值。 你可以修改此命名空间的模式文件，来为某个子命令选项指定另外的默认值。

The fields given in the schema correspond to the allowed argument values and defaults for the CLI sub-command options. You can update your workspace schema file to set a different default for a sub-command option.

项目工具的配置选项link

Project tool configuration optionslink

建筑师（Architect）是指 CLI 用来根据所提供的配置执行复杂任务（如编译和测试运行）的工具。 angular.json 的 architect 部分包含一组建筑目标。很多目标都对应于运行它们的 CLI 命令。使用 ng run 命令可以运行一些额外的预定义目标，并可以定义自己的目标。

Architect is the tool that the CLI uses to perform complex tasks, such as compilation and test running, according to provided configurations. The architect section of angular.json contains a set of Architect targets. Many of the targets correspond to the CLI commands that run them. Some additional predefined targets can be run using the ng run command, and you can define your own targets.

每个目标对象都指定了该目标的 builder，它是建筑师所运行工具的 npm 包。此外，每个目标都有一个 options 部分，用于配置该目标的默认选项，configurations 部分可以为目标命名并指定备用配置。参见稍后的构建目标部分的例子。

Each target object specifies the builder for that target, which is the npm package for the tool that Architect runs. In addition, each target has an options section that configures default options for the target, and a configurations section that names and specifies alternative configurations for the target. See the example in Build target below.

      
        content_copy
      
      "architect": {
  "build": { },
  "serve": { },
  "e2e" : { },
  "test": { },
  "lint": { },
  "extract-i18n": { },
  "server": { },
  "app-shell": { }
}
    

• architect/build 节会为 ng build 命令的选项配置默认值。更多信息，参见稍后的构建目标部分。

  The architect/build section configures defaults for options of the ng build command. See Build target below for more information.

• architect/serve 节会覆盖构建默认值，并为 ng serve 命令提供额外的服务器默认值。除了 ng build 命令的可用选项之外，还增加了与开发服务器有关的选项。

  The architect/serve section overrides build defaults and supplies additional serve defaults for the ng serve command. In addition to the options available for the ng build command, it adds options related to serving the app.

• architect/e2e 节覆盖了构建选项默认值，以便用 ng e2e 命令构建端到端测试应用。

  The architect/e2e section overrides build-option defaults for building end-to-end testing apps using the ng e2e command.

• architect/test 节会覆盖测试时的构建选项默认值，并为 ng test 命令提供额外的默认值以供运行测试。

  The architect/test section overrides build-option defaults for test builds and supplies additional test-running defaults for the ng test command.

• architect/lint 节为 ng lint 命令配置了默认值，用于对项目源文件进行代码分析。 Angular 默认的 linting 工具为 TSLint。

  The architect/lint section configures defaults for options of the ng lint command, which performs code analysis on project source files. The default linting tool for Angular is TSLint.

• architect/extract-i18n 节为 ng xi18n 命令所用到的 ng-xi18n 工具选项配置了默认值，该命令用于从源代码中提取带标记的消息串，并输出翻译文件。

  The architect/extract-i18n section configures defaults for options of the ng-xi18n tool used by the ng xi18n command, which extracts marked message strings from source code and outputs translation files.

• architect/server 节用于为使用 ng run <project>:server 命令创建带服务器端渲染的 Universal 应用配置默认值。

  The architect/server section configures defaults for creating a Universal app with server-side rendering, using the ng run <project>:server command.

• architect/app-shell 部分使用 ng run <project>:app-shell 命令为渐进式 Web 应用（PWA）配置创建应用外壳的默认值。

  The architect/app-shell section configures defaults for creating an app shell for a progressive web app (PWA), using the ng run <project>:app-shell command.

一般来说，可以为 CLI 参考手册中列出的每个命令配置相应的默认值。注意，配置文件中的所有选项都必须使用 camelCase，而不是 dash-case。

In general, the options for which you can configure defaults correspond to the command options listed in the CLI reference page for each command. Note that all options in the configuration file must use camelCase, rather than dash-case.

构建目标link

Build targetlink

architect/build 节会为 ng build 命令的选项配置默认值。它具有下列顶级属性。

The architect/build section configures defaults for options of the ng build command. It has the following top-level properties.

默认的构建目标link

Default build targetslink

Angular 定义了一些默认的构建器，供建筑师工具和 ng run 命令使用。 这些默认的构建器会利用一些特定工具来执行复杂操作。

Angular defines default builders for use with the Architect tool and ng run command. The default builders provide implementations that use a particular tool to perform a complex operation.

这些默认构造器的选项及其默认值的 JSON 模式定义在 @angular-devkit/build-angular包中。这些 JSON 模式包括下列构建目标的配置项：

The JSON schemas that the define the options and defaults for each of these default builders are collected in the @angular-devkit/build-angularpackage. The schemas configure options for the following Architect build targets:

• app-shell
• browser
• dev-server
• extract-i18n
• karma
• protractor
• server
• tslint

备用的构建配置link

Alternate build configurationslink

默认情况下，会定义一个 production 配置，ng build 命令会使用该配置下的 --prod 选项。这里的 production 配置会设置各种默认值来优化应用，例如打包文件、最小化多余空格、移除注释和死代码，以及重写代码以使用简短的名字（“minification”）。

By default, a production configuration is defined, and the ng build command has --prod option that builds using this configuration. The production configuration sets defaults that optimize the app in a number of ways, such bundling files, minimizing excess whitespace, removing comments and dead code, and rewriting code to use short, cryptic names ("minification").

你可以定义和命名适用于你的开发过程的其它备用配置（例如stage）。其它构建配置的一些例子是 AIO 自己使用的 stable、archive、next，以及构建本地化版本应用所需的各个与区域有关的配置置。欲知详情，参见国际化（i18n） 。

You can define and name additional alternate configurations (such as stage, for instance) appropriate to your development process. Some examples of different build configurations are stable, archive and next used by AIO itself, and the individual locale-specific configurations required for building localized versions of an app. For details, see Internationalization (i18n).

额外的构建和测试选项link

Additional build and test optionslink

ng build、ng serve和 ng test命令的可配置选项通常与 ng build、ng serve和 ng test命令的可用选项一一对应。有关这些选项及其取值范围的更多信息，参见“ CLI参考手册”。

The configurable options for a default or targeted build generally correspond to the options available for the ng build, ng serve, and ng testcommands. For details of those options and their possible values, see the CLI Reference.

一些额外的选项（如下所列）只能通过配置文件来设置，可以直接编辑，也可以使用 ng config命令。

Some additional options (listed below) can only be set through the configuration file, either by direct editing or with the ng configcommand.

项目资产（asset）配置link

Project asset configurationlink

每个 build 目标配置都可以包含一个 assets 数组，它列出了当你构建项目时要复制的文件或文件夹。默认情况下，会复制 src/assets/ 文件夹和 src/favicon.ico 。

Each build target configuration can include an assets array that lists files or folders you want to copy as-is when building your project. By default, the src/assets/ folder and src/favicon.ico are copied over.

      
        content_copy
      
      "assets": [
  "src/assets",
  "src/favicon.ico"
]
    

要排除某个资产，可以从这份资产配置中删除它。

To exclude an asset, you can remove it from the assets configuration.

你可以通过把资产指定为对象的形式来进一步配置要复制的资产，而不仅是相对于工作空间根目录的路径。一个资产对象可以包含如下字段。

You can further configure assets to be copied by specifying assets as objects, rather than as simple paths relative to the workspace root. A asset specification object can have the following fields.

• glob：一个 node-glob 它使用 input 作为基准目录。

  glob: A node-glob using input as base directory.

• input：相对于工作空间根目录的路径。

  input: A path relative to the workspace root.

• output：相对于 outDir 的路径（默认为 dist/project-name ）。为了杜绝安全隐患，CLI 永远不会在项目输出路径之外写文件。

  output: A path relative to outDir (default is dist/project-name). Because of the security implications, the CLI never writes files outside of the project output path.

• ignore：要排除的 glob 列表。

  ignore: A list of globs to exclude.

例如，可以使用如下对象来更详细地表达默认的资产路径。

For example, the default asset paths can be represented in more detail using the following objects.

      
        content_copy
      
      "assets": [
  { "glob": "**/*", "input": "src/assets/", "output": "/assets/" },
  { "glob": "favicon.ico", "input": "src/", "output": "/" },
]
    

你可以使用此扩展配置从项目外部复制资产。例如，以下配置会从 node 包中复制资产：

You can use this extended configuration to copy assets from outside your project. For example, the following configuration copies assets from a node package:

      
        content_copy
      
      "assets": [
 { "glob": "**/*", "input": "./node_modules/some-package/images", "output": "/some-package/" },
]
    

node_modules/some-package/images/ 中的内容将会复制到 dist/some-package/ 中。

The contents of node_modules/some-package/images/ will be available in dist/some-package/.

下面的例子使用 ignore 字段排除了 assets 文件夹中的某些特定文件，防止它们被复制到 build 中：

The following example uses the ignore field to exclude certain files in the assets folder from being copied into the build:

      
        content_copy
      
      "assets": [
 { "glob": "**/*", "input": "src/assets/", "ignore": ["**/*.svg"], "output": "/assets/" },
]