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 library 创建库项目时，库项目也会添加到 projects 节。

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 子命令会从 @schematics/angular 包中收集原理图。 可以用 schematic-package:schematic-name 格式来为子命令指定原理图名称；比如，用来生成组件的原理图名叫 @schematics/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 @schematics/angular. Specify the schematic name for a subcommand in the format schematic-package:schematic-name; for example, the schematic for generating a component is @schematics/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 用来执行复杂任务（例如编译和测试运行）的工具。 Architect 是一个根据目标配置运行指定的构建器以完成指定任务的外壳。你可以定义和配置新的构建器和目标以扩展 CLI。请参阅 Angular CLI 构建器。

Architect is the tool that the CLI uses to perform complex tasks, such as compilation and test running. Architect is a shell that runs a specified builder to perform a given task, according to a target configuration. You can define and configure new builders and targets to extend the CLI. See Angular CLI Builders.

默认的建筑师构建器和目标link

Default Architect builders and targetslink

Angular 定义了用于特定 CLI 命令或常规 ng run 命令的默认构建器。为每个默认构建器定义选项和默认值的 JSON 模式收集在 @angular-devkit/build-angular包中。这些架构为以下构建器配置选项。

Angular defines default builders for use with specific CLI commands, or with the general ng run command. The JSON schemas that 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 builders.

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

配置构建器目标link

Configuring builder targetslink

angular.json 的 architect 部分包含一组建筑目标。很多目标都对应于运行它们的 CLI 命令。使用 ng run 命令可以运行一些额外的预定义目标，并可以定义自己的目标。

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 extract-i18n 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

Alternate build configurationslink

Angular CLI 具有两种构建配置： production 和 development。默认情况下，ng build 命令使用 production 配置，该配置将应用许多构建优化，包括：

Angular CLI comes with two build configurations: production and development. By default, the ng build command uses the production configuration, which applies a number of build optimizations, including:

• 打包文件

  Bundling files

• 最小化多余的空白

  Minimizing excess whitespace

• 删除注释和无效代码

  Removing comments and dead code

• 重写代码，以使用简短、混乱的名称（最小化）

  Rewriting code to use short, mangled 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).

你可以通过将它们的名称传给 --configuration 命令行标志来选择替代配置。

You can select an alternate configuration by passing its name to the --configuration command line flag.

你还可以用逗号分隔的列表传入多个配置名称。例如，要同时应用 stage 和 fr 构建配置，请使用命令 ng build --configuration stage,fr。在这种情况下，该命令从左到右解析命名的配置。如果多个配置更改了同一个设置，则最后设置的值生效。

You can also pass in more than one configuration name as a comma-separated list. For example, to apply both stage and fr build configurations, use the command ng build --configuration stage,fr. In this case, the command parses the named configurations from left to right. If multiple configurations change the same setting, the last-set value is the final one.

额外的构建和测试选项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 can only be set through the configuration file, either by direct editing or with the ng configcommand.

复杂配置的值link

Complex configuration valueslink

选项 assets，styles 和 scripts 的值可以是简单的路径字符串，也可以是带有特定字段的对象值。可以使用命令标志将 sourceMap 和 optimization 选项设置为简单的布尔值，但也可以使用配置文件为其指定复杂的值。以下各节提供了在每种情况下如何使用这些复数值的详细信息。

The options assets, styles, and scripts can have either simple path string values, or object values with specific fields. The sourceMap and optimization options can be set to a simple Boolean value with a command flag, but can also be given a complex value using the configuration file. The following sections provide more details of how these complex values are used in each case.

项目资产（asset）配置link

Assets 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.

• followSymlinks：允许这些 glob 模式跟踪目录的符号链接。这样会允许搜索符号链接过来的子目录。默认为 false。

  followSymlinks: Allow glob patterns to follow symlink directories. This allows subdirectories of the symlink to be searched. Defaults to false.

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

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

样式和脚本配置link

Styles and scripts configurationlink

styles 和 scripts 选项的数组型条目可以是简单的路径字符串，也可以是指向额外入口点文件的对象。 其关联的构建器将在构建过程中将该文件及其依赖项作为单独的捆绑包进行加载。 对于配置对象，你可以选择使用 bundleName 字段为该入口点命名捆绑包。

An array entry for the styles and scripts options can be a simple path string, or an object that points to an extra entry-point file. The associated builder will load that file and its dependencies as a separate bundle during the build. With a configuration object, you have the option of naming the bundle for the entry point, using a bundleName field.

默认情况下捆绑包会被注入这里，但是你可以将 inject 设置为 false，以将捆绑包从注入中排除。例如，以下对象值将创建并命名包含样式和脚本的包，并将其从注入中排除：

The bundle is injected by default, but you can set inject to false to exclude the bundle from injection. For example, the following object values create and name a bundle that contains styles and scripts, and excludes it from injection:

      
        content_copy
      
      "styles": [
  {
    "input": "src/external-module/styles.scss",
    "inject": false,
    "bundleName": "external-module"
  }
],
"scripts": [
  {
    "input": "src/external-module/main.js",
    "inject": false,
    "bundleName": "external-module"
  }
]
    

你可以混合使用简单和复杂的文件引用来获取样式和脚本。

You can mix simple and complex file references for styles and scripts.

      
        content_copy
      
      "styles": [
  "src/styles.css",
  "src/more-styles.css",
  { "input": "src/lazy-style.scss", "inject": false },
  { "input": "src/pre-rename-style.scss", "bundleName": "renamed-style" },
]
    

样式预处理器选项link

Style preprocessor optionslink

在 Sass 和 Stylus 中，你可以同时使用组件样式和全局样式的 includePaths 功能，从而可以添加将用来检查导入的额外基本路径。

In Sass and Stylus you can make use of the includePaths functionality for both component and global styles, which allows you to add extra base paths that will be checked for imports.

要添加路径，请使用 stylePreprocessorOptions 选项：

To add paths, use the stylePreprocessorOptions option:

      
        content_copy
      
      "stylePreprocessorOptions": {
  "includePaths": [
    "src/style-paths"
  ]
}
    

该文件夹中的文件，例如 src/style-paths/_variables.scss，可以从项目中的任何位置导入，而无需相对路径：

Files in that folder, such as src/style-paths/_variables.scss, can be imported from anywhere in your project without the need for a relative path:

      
        content_copy
      
      // src/app/app.component.scss
// A relative path works
@import '../style-paths/variables';
// But now this works as well
@import 'variables';
    

请注意，如果要将其用于单元测试，则还需要向 test 构建器中添加某些样式或脚本。另请参阅在应用程序内部使用运行时全局库。

Note that you will also need to add any styles or scripts to the test builder if you need them for unit tests. See also Using runtime-global libraries inside your app.

优化配置link

Optimization configurationlink

optimization 这个浏览器构建器选项可以是布尔值或对象，以进行更精细的配置。此选项可对构建输出进行各种优化，包括：

The optimization browser builder option can be either a Boolean or an Object for more fine-tune configuration. This option enables various optimizations of the build output, including:

• 脚本和样式的最小化

  Minification of scripts and styles

• 摇树优化

  Tree-shaking

• 消除死代码

  Dead-code elimination

• 内联关键 CSS

  Inlining of critical CSS

• 字体内联

  Fonts inlining

有几个选项可用于微调应用程序的优化方式。

There are several options that can be used to fine-tune the optimization of an application.

样式优化选项link

Styles optimization optionslink

字体优化选项link

Fonts optimization optionslink

• optimization 选项适用于脚本，样式和字体。你可以提供诸如以下的值，以将此优化应用于一个或另一个：

  The optimization option applies to scripts, styles and fonts. You can supply a value such as the following to apply optimization to one or the other:

      
        content_copy
      
      "optimization": {
  "scripts": true,
  "styles": {
    "minify": true,
    "inlineCritical": true
  },
  "fonts": true
}
    

Source map（源码映射）配置link

Source map configurationlink

sourceMap 这个浏览器构建器选项可以是 Boolean 或 Object，以进行更精细的配置以控制应用程序的源码映射。

The sourceMap browser builder option can be either a Boolean or an Object for more fine-tune configuration to control the source maps of an application.

以下示例显示了如何切换一个或多个值以配置源码映射输出：

The example below shows how to toggle one or more values to configure the source map outputs:

      
        content_copy
      
      "sourceMap": {
  "scripts": true,
  "styles": false,
  "hidden": true,
  "vendor": true
}