angular12 angular.json

一、 angular.json文件时如何产生的

angular6之前我们通过脚手架（angular cli）创建的项目会有一个angular-cli.json文件，此文件是cli的相关配置信息。

在angular6+的版本后，原先的angular-cli.json就被换成了angular.json。

而其中里面的字段变化挺大了，如果不了解基本的组成，或者直接把老版本的代码 copy 到新版本的工作空间中，会导致一些很不友好的错误。

这种变化主要还是因为Angular CLI引入了 monorepo (一个空间管理多个项目) 的开发模式，即使用ng new出来的相当于一个大的工作空间，通过angular.json配置来管理各种ng generate application | library出来的项目或组件库。

二、 Angular工作空间

• Angular工作空间： 一个由Angular CLI创建，并且能够包含多个项目 或者 由单一文件导出配置的库 的目录空间。

实际上，从现在开始，Angular CLI项目开始叫做Angular 工作空间。

当你ng new一个工作空间时，默认会在根目录创建一个项目以及对应e2e项目。初始的angular.json结构如下：

{
  "$schema": "./node_modules/@angular/cli/lib/config/schema.json",
  "version": 1,
  "newProjectRoot": "projects",
  "projects": {
    "xxxx": {
      "root": "",
      "sourceRoot": "src",
      "projectType": "application",
      "prefix": "app",
      "schematics": {},
      "architect": {}
    }
  },
  "defaultProject": "xxxx"
}

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

ng则是Angular的一个命令，该命令在运行时将读取angular.json配置文件。

三、 JSON Schema

3.1 JSON Schema

JSON 格式的优点之一就是轻量，其本身并不支持写注释，所以没办法直接在文件本身中对字段进行描述。

因此，假如我们用 JSON 来做配置文件，大多数情况下都要对着文档来查看每个字段的类型、限制范围，才能编写出正确的配置。这样做不仅效率低，而且必须要自己来校验编写出的配置是否正确，一不小心就写错了。

而 JSON Schema 就是为解决此问题而生的，他本身就是 JSON 文件，用来注解和校验 JSON 文件。

3.2 编写 JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://www.code-nav.cn/latest.json",
  "title": "GameConfig",
  "description": "游戏配置",
  "type": "object",
  "properties": {
    "items": {
      "type": "array"
    }
  }
}

3.3 使用 JSON Schema

在要校验的数据中指定 “$schema” 字段为该校验文件地址，比如下列 JSON 配置，故意把 items 字段的值设置为 string（字符串）而非数组：

{
  "$schema": "https://www.code-nav.cn/latest.json",
  "name": "yupi",
  "difficulty": 5,
  "items": "haha"
}

这样就能检查数据是否合法啦！很多主流的编辑器（比如 JetBrains 全家桶）可以自动识别校验文件，并且检查你的 JSON 输入是否合法。也可以使用 JSON Schema validation online 等在线校验 JSON Schema 的网页来查看效果

四、 顶层字段

字段名	说明
version	该配置文件的版本 ，指明了Angular 工作空间 概要的版本
$schema	关联了JSON Schema在Angular CLI中的实施文件。JSON Schema 是一个允许我们注解和验证JSON数据格式的工具。Angular CLI使用它来强化对于Angular Workspace schema的解释说明。
newProjectRoot	用来创建新工程的位置。绝对路径或相对于工作区目录的路径。
cli	一组用于自定义 Angular CLI 的选项。参见 CLI 配置选项部分。
schematics	一组原理图，用于定制 ng generate 子命令在本工作区中的默认选项。参阅生成器原理图。大家或多或少，都听说过 Schematics。作为Angular DevKit的一部分，用来转换、创建 或者 更新项目开发的工作流工具。schematics属性 可以在工作空间的root level来配置Schematics packages的选项。注意 这个会在工作空间的任何 level 进行应用。
projects	对于工作区中的每个项目（应用或库）都会包含一个子分区，子分区中是每个项目的配置项。这个属性包含了工作空间中所有项目的配置信息。
defaultProject	命令中用到的默认项目名称

schematic-package：schematic-name:(object类型)，此对象包含schematic的配置选项，默认的json格式配置如下：

• @schematics/angular:component
• @schematics/angular:directive
• @schematics/angular:module
• @schematics/angular:service
• @schematics/angular:pipe
• @schematics/angular:class

五、 cli配置详解

名称	说明	值类型
analytics	与 Angular 团队共享匿名使用数据	boolean
analyticsSharing	一组分析共享选项	分析共享选项
cache	控制 Angular CLI 构建器使用的持久化磁盘缓存	缓存选项
defaultCollection	要使用的默认原理图集合	string
packageManager	要使用的首选包管理器工具	npm
warnings	控制 CLI 特定的控制台警告	警告选项

六、 projects

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

属性	说明
root	该项目的根文件夹，相对于工作区文件夹的路径。初始应用的值为空，因为它位于工作区的顶层
sourceRoot	项目源文件的根文件夹
projectType	application 或 library 之一。应用可以在浏览器中独立运行，而库则不行
prefix Angular	所生成的选择器的前缀字符串。可以自定义它，以作为应用或功能区的标识
schematics	一组原理图（schematic），它可以为该项目自定义 ng generate 子命令的默认选项。参见生成原理图部分
architect	为本项目的各个构建器目标配置默认值

6.1 architect配置详解

"architect": {
  "build": {},//为 ng build 命令的选项配置默认值
  "serve": {},//覆盖构建默认值，并为 ng serve 命令提供额外的服务器默认值。除了 ng build 命令的可用选项之外，还增加了与开发服务器有关的选项
  "e2e" : {},//覆盖了构建选项默认值，以便用 ng e2e 命令构建端到端测试应用
  "test": {},//会覆盖测试时的构建选项默认值，并为 ng test 命令提供额外的默认值以供运行测试
  "lint": {},//ng lint 命令配置了默认值，用于对项目源文件进行代码分析。Angular 默认的 linting 工具为 TSLint
  "extract-i18n": {},//为 ng xi18n 命令所用到的 ng-xi18n 工具选项配置了默认值，该命令用于从源代码中提取带标记的消息串，并输出翻译文件
  "server": {},//用于为使用 ng run <project>:server 命令创建带服务器端渲染的 Universal 应用配置默认值
  "app-shell": {}//使用 ng run <project>:app-shell 命令为渐进式 Web 应用（PWA）配置创建应用外壳的默认值
}

6.1.1 serve配置详解

{
  "serve": {
    "builder": "@angular-builders/custom-webpack:dev-server",
    "options": {
      "browserTarget": "sub-app2:build",
      "proxyConfig": "proxy.conf.json"
    },
    "configurations": {
      "production": {
        "browserTarget": "sub-app2:build:production"
      },
      "development": {
        "browserTarget": "sub-app2:build:development"
      }
    },
    "defaultConfiguration": "development"
  }
}

属性	说明
builder	用于构建此目标的构建工具的 npm 包。默认为 @angular-devkit/build-angular:browser，它使用的是 webpack 打包器。 注意：当构建库（ng build myLib）时使用了不同的构建器
options	本节包含构建选项的默认值，当没有指定命名的备用配置时使用
configurations	本节定义并命名针对不同目标的备用配置。它为每个命名配置都包含一节，用于设置该目标环境的默认选项

6.1.1.1 configurations

配置项中，主要用来做如下工作：

• 打包文件
• 最小化多余的空白
• 删除注释和无效代码
• 重写代码，以使用简短、混乱的名称（最小化）

通常build 是用production的

选项属性	说明
assets	一个对象，包含一些用于添加到项目的全局上下文中的静态文件路径。它的默认路径指向项目的图标文件及项目的 assets 文件夹。参阅项目资产（asset）配置部分
styles	一个对象，包含一些要添加到项目全局上下文中的样式文件。Angular CLI 支持 CSS 导入和所有主要的 CSS 预处理器： sass/scss 和 less
stylePreprocessorOptions	一个对象，包含要传给样式预处理器的选项"值-对"
scripts	一个对象，包含一些 JavaScript 脚本文件，用于添加到项目的全局上下文中。这些脚本的加载方式和在 index.html 的

七、样例

{
  // 注解和验证JSON数据格式的工具，比如可以自动填充属性或属性值
  "$schema": "./node_modules/@angular/cli/lib/config/schema.json",
  // 该配置文件的版本 ，指明了Angular 工作空间 概要的版本
  "version": 1,
  // 用来创建析工程的位置。绝对路径或相对于工作区目录的路径。 使用 ng generate application myDemo, 就会在 angular-dave/projects 目录下生成 myDemo 项目。 ps：新建项目是 ng new angular-dave；ng g application myDemo 是在项目angular-dave下生成myDemo子项目，不是一回事
  "newProjectRoot": "projects",
  // 这个属性包含了工作空间中所有项目的配置信息。 如果如上生成 myDemo, 那么在这里还有与 angular-dave 同一层级的 myDemo 的配置
  // 对于工作区中的每个项目（应用或库）都会包含一个子分区，子分区中是每个项目的配置项。这个属性包含了工作空间中所有项目的配置信息。
  "projects": {
    "angular-dave": {
      // 该属性有 application 和 library 两种选择，应用可以在浏览器中独立运行，而库则不行
      "projectType": "application",
      // 该项目的根文件夹，相对于工作区文件夹的路径。初始应用的值为空，因为它位于工作区的顶层
      // 如果如上生成 myDemo, 那么 myDemo 的如下几个属性值路径会有所不同
      "root": "",
      // 一组原理图（schematic），它可以为该项目自定义 ng generate 子命令的默认选项。
      "schematics": {
        // 在项目级别统一进行配置，比如在这里，配置了所有的 component 都使用 scss
        // 可试着查看其它的配置项，因为有 $schema, 会帮你自动补全相关属性
        "@schematics/angular:component": {
          "style": "scss"
        }
      },
      // 项目源文件的根文件夹
      "sourceRoot": "src",
      // 当CLI创建 `component`或者`directive`时，使用该属性 来区别他们
      "prefix": "app",
      // 为本项目的各个构建器目标配置默认值
      "architect": {
        // 为 ng build 命令的选项配置默认值
        "build": {
          // 每个目标对象都指定了该目标的 builder，它是 architect (建筑师)所运行工具的 npm 包
          "builder": "@angular-devkit/build-angular:browser",
          "options": {
            "outputPath": "dist/angular-dave",
            "index": "src/index.html",
            "main": "src/main.ts",
            "polyfills": "src/polyfills.ts",
            "tsConfig": "tsconfig.app.json",
            "aot": false,
            // 包含一些用于添加到项目的全局上下文中的静态文件路径
            // 每个 build 目标配置都可以包含一个 assets 数组，它列出了当你构建项目时要复制的文件或文件夹。
            // 默认情况下，会复制 src/assets/ 文件夹和 src/favicon.ico
            "assets": [
              "src/favicon.ico",
              "src/assets"
            ],
            // 包含一些要添加到项目全局上下文中的样式文件(即全局样式)
            "styles": [
              "src/styles.scss"
            ],
            // 包含一些 JavaScript 脚本文件，用于添加到项目的全局上下文中。 这些脚本的加载方式和在 index.html 的 <script> 标签中添加是完全一样的。
            "scripts": []
          },
          // configurations 部分可以为目标命名并指定备用配置
          "configurations": {
            "development": {
              "sourceMap": true,
              "optimization": false
            },
            "production": {
              "fileReplacements": [
                {
                  "replace": "src/environments/environment.ts",
                  "with": "src/environments/environment.prod.ts"
                }
              ],
              "optimization": true,
              "outputHashing": "all",
              "sourceMap": false,
              "extractCss": true,
              "namedChunks": false,
              "aot": true,
              "extractLicenses": true,
              "vendorChunk": false,
              "buildOptimizer": true,
              // 全部或部分应用的默认尺寸预算的类型和阈值。 当构建的输出达到或超过阈值大小时，你可以将构建器配置为报告警告或错误
              "budgets": [
                {
                  "type": "initial",
                  "maximumWarning": "2mb",
                  "maximumError": "5mb"
                },
                {
                  "type": "anyComponentStyle",
                  "maximumWarning": "6kb",
                  "maximumError": "10kb"
                }
              ]
            }
          }
        },
        // 覆盖构建默认值，并为 ng serve 命令提供额外的服务器默认值
        "serve": {
          "builder": "@angular-devkit/build-angular:dev-server",
          "options": {
            "browserTarget": "angular-dave:build"
          },
          "configurations": {
            "production": {
              "browserTarget": "angular-dave:build:production"
            }
          }
        },
        // 为 ng xi18n 命令所用到的 ng-xi18n 工具选项配置了默认值
        "extract-i18n": {
          "builder": "@angular-devkit/build-angular:extract-i18n",
          "options": {
            "browserTarget": "angular-dave:build"
          }
        },
        // 覆盖测试时的构建选项默认值，并为 ng test 命令提供额外的默认值以供运行测试
        "test": {
          "builder": "@angular-devkit/build-angular:karma",
          "options": {
            "main": "src/test.ts",
            "polyfills": "src/polyfills.ts",
            "tsConfig": "tsconfig.spec.json",
            "karmaConfig": "karma.conf.js",
            "assets": [
              "src/favicon.ico",
              "src/assets"
            ],
            "styles": [
              "src/styles.scss"
            ],
            "scripts": []
          }
        },
        // 为 ng lint 命令配置了默认值，用于对项目源文件进行代码分析
        "lint": {
          "builder": "@angular-devkit/build-angular:tslint",
          "options": {
            "tsConfig": [
              "tsconfig.app.json",
              "tsconfig.spec.json",
              "e2e/tsconfig.json"
            ],
            "exclude": [
              "**/node_modules/**"
            ]
          }
        },
        // 覆盖了构建选项默认值，以便用 ng e2e 命令构建端到端测试应用
        "e2e": {
          "builder": "@angular-devkit/build-angular:protractor",
          "options": {
            "protractorConfig": "e2e/protractor.conf.js",
            "devServerTarget": "angular-dave:serve"
          },
          "configurations": {
            "production": {
              "devServerTarget": "angular-dave:serve:production"
            }
          }
        }
      }
    }
  },
  // 命令中用到的默认项目名称
  "defaultProject": "angular-dave",
  // 一组用于自定义 Angular CLI 的选项。参见 CLI 配置选项部分。
  "cli": {
    "analytics": false
  }
}

参考

• 3 分钟了解 JSON Schema
• JSON schema配置规范使用教程
• 【精】angular.json配置详解【angular12】
• angular.json参数详解
• angular.json简单解释