Angular 编译器选项

Angular 编译器选项

使用 AoT 编译 时，可以通过在 TypeScript 配置文件中 指定模板编译器选项来控制如何编译应用程序。

模板选项对象 ​angularCompilerOptions ​和为 TypeScript 编译器提供标准选项的 ​compilerOptions ​对象是兄弟。

{
  "compileOnSave": false,
  "compilerOptions": {
    "baseUrl": "./",
    // ...
  },
  "angularCompilerOptions": {
    "enableI18nLegacyMessageIdFormat": false,
    "strictInjectionParameters": true,
    // ...
  }
}

用 extends 语法配置继承方式

像 TypeScript 编译器一样，Angular 的 AOT 编译器也支持对 TypeScript 配置文件中的 ​angularCompilerOptions ​进行 ​extends​。​extends ​属性位于顶层，和 ​compilerOptions ​和 ​angularCompilerOptions ​平级。

使用 ​extends ​属性，TypeScript 配置可以从另一个文件中继承设置。首先从基础文件中加载配置项，然后被继承自它的配置文件中的配置项覆写。

比如：

{
    "extends": "./tsconfig.json",
    "compilerOptions": {
      "outDir": "./out-tsc/app",
    // ...
    "angularCompilerOptions": {
      "strictTemplates": true,
      "preserveWhitespaces": true,
      // ...
    },
  }

欲知详情，参阅 TypeScript 手册。

模板选项

以下选项可用于配置 AoT 模板编译器。

allowEmptyCodegenFiles

如果为 ​true​，则生成所有可能的文件 —— 即使它们为空。默认值为 ​false​。Bazel 的构建规则使用它来简化 Bazel 规则跟踪文件依赖性的方式。不要在 Bazel 规则之外使用此选项。

annotationsAs

修改 Angular 专有注解的生成方式，以改善摇树优化。非 Angular 注解不受影响。可选值为 ​static fields​（默认值）或 ​decorators​。

• 默认情况下，编译器会用类中的静态字段替换装饰器，这允许像 Closure 编译器 这样的高级摇树器删除未使用的类。
• ​decorators ​值会将装饰器保留在原处，这将使编译速度更快。TypeScript 会生成对辅助器 ​__decorate​ 的调用。使用 ​--emitDecoratorMetadata​ 以支持运行时反射。

注意：
这样生成的代码将无法被正确地摇树优化。

annotateForClosureCompiler

如果为 ​true​，则使用 Tsickle 来用 JSDoc 对生成的 JavaScript 代码进行注解，这些注释是供 Closure 编译器 使用的。默认值为 ​false​。

compilationMode

指定要使用的编译模式。可以使用以下模式：

默认值为 'full'。

disableExpressionLowering

如果为 ​true​（默认值），则转换在注解中使用或允许使用的代码，以允许从模板的工厂模块导入代码。

如果为 ​false​，则禁用此重写，你必须手动进行重写。

disableTypeScriptVersionCheck

如果为 ​true​，则在使用不受支持的 TypeScript 版本时，编译器不会检查 TypeScript 版本，并且不会报错。不建议使用，因为不受支持的 TypeScript 版本可能具有未定义的行为。默认值为 ​false​。

enableI18nLegacyMessageIdFormat

指示 Angular 模板编译器为模板中用 ​i18n ​属性标出的消息生成旧版 ID。

除非你的项目依赖先前已用旧版 ID 生成的翻译，否则请将此选项设置为 ​false​。默认值为 ​true​。

Ivy 之前版本的消息提取工具为所提取的消息 id 生成了多种旧格式。这些消息格式存在许多问题，比如对空白字符的处理和对模板原始 HTML 内部信息的依赖。

新的消息格式对空白字符的改动更宽容，在所有翻译文件格式中都相同，并且可以直接通过调用 ​$localize​ 生成。这允许应用程序代码中的 ​$localize​ 消息使用与组件模板中 ​i18n ​消息完全相同的 id。

enableResourceInlining

当为 ​true ​时，将所有 ​@Component​ 装饰器中的 ​templateUrl ​和 ​styleUrls ​属性替换为 ​template ​和 ​styles ​属性中的内联内容。

启用后，​ngc ​的 ​.js​ 输出不会包含任何惰性加载的模板或样式 URL。

对于使用 CLI 生成的库项目，dev 配置下默认为 ​true​。

enableLegacyTemplate

如果为 ​true​，则启用 Angular 4.0 中为了避免与同名的 DOM 元素冲突而不推荐使用的 ​<template>​ 元素（推荐改用 ​<ng-template>​）。默认值为 ​false​。某些第三方 Angular 库可能需要它。

flatModuleId

用于导入扁平模块的模块 ID（当 ​flatModuleOutFile ​为 ​true ​时）。从扁平模块中导入符号时，模板编译器生成的引用将使用该模块的名称。如果 ​flatModuleOutFile ​为 ​false ​则忽略。

flatModuleOutFile

为 ​true ​时，将生成指定文件名和相应扁平模块元数据的扁平模块索引。用于创建像 ​@angular/core​ 和 ​@angular/common​ 这样打包的扁平模块。使用此选项时，库的 ​package.json​ 应引用生成的扁平模块索引而不是库的索引文件。

它只会生成一个 ​.metadata.json​ 文件，该文件包含从库索引中导出的符号所需的全部元数据。在生成的 ​.ngfactory.js​ 文件中，扁平模块索引用于导入符号，这些符号既包括库索引中的公共 API，也包括缩进的内部符号。

默认情况下，​files ​字段中提供的 ​.ts​ 文件会被当做库索引。如果指定了多个 ​.ts​ 文件，则使用 ​libraryIndex ​选择要使用的文件。如果提供了多个不带 ​libraryIndex .ts​ 文件，则会产生错误。

使用指定的 ​flatModuleOutFile ​名在与库索引 ​.d.ts​ 文件相同的位置创建扁平模块索引 ​.d.ts​ 和 ​.js​。

比如，如果一个库使用 ​public_api.ts​ 文件作为模块的库索引，则 ​tsconfig.json​ 的 ​files ​字段就是 ​["public_api.ts"]​。然后，比如把 ​flatModuleOutFile ​选项设置为 ​"index.js"​，这将生成 ​index.d.ts​ 和 ​index.metadata.json​ 文件。该库的 ​package.json​ 的 ​module ​字段中就会是 ​"index.js"​，而 ​typings ​字段将是 ​"index.d.ts"​。

fullTemplateTypeCheck

为 ​true​（推荐）时，会启用模板编译器的绑定表达式验证阶段，该阶段使用 TypeScript 来验证绑定表达式。

默认值为 ​false​，但是当你使用 CLI 命令 ​ng new --strict​ 时，默认生成的项目配置中会将其设置为 ​true​。

​fullTemplateTypeCheck ​选项已经在 Angular 13 中弃用，改为使用 ​strictTemplates ​家族的编译器选项。

generateCodeForLibraries

如果为 ​true​（默认值），就会为 ​.d.ts​ 和相应的 ​.metadata.json​ 生成工厂文件（​.ngfactory.js​ 和 ​.ngstyle.js​）。

如果为 ​false​，则仅为 ​.ts​ 文件生成工厂文件。当要使用工厂摘要（summary）时，请这么设置。

preserveWhitespaces

如果为 ​false​（默认值），则从编译的模板中删除空白文本节点，这将生成较小的模板工厂模块。设置为 ​true ​

skipMetadataEmit

为 ​true ​时，不生成 ​.metadata.json​ 文件。默认值为 ​false​。

​.metadata.json​ 文件包含模板编译器从 ​.ts​ 文件中获得的信息，该信息未包含在 TypeScript 编译器生成的 ​.d.ts​ 文件中。该信息包括注解的内容（比如组件的模板）等，TypeScript 会将该注解的内容发送到 ​.js​ 文件中，但不会发送到 ​.d.ts​ 文件。

你可以在使用工厂摘要（summary）中将其设置为 ​true​，因为工厂摘要中包括 ​.metadata.json​ 文件中信息的副本。

如果要使用 TypeScript 的 ​--outFile​ 选项，则设置为 ​true​，因为元数据文件对于这种 TypeScript 输出风格无效。但是，我们不建议将 ​--outFile​ 和 Angular 一起使用。请使用打包程序，比如 webpack。以保留空白文本节点。

skipTemplateCodegen

为 ​true ​时，不生成 ​.ngfactory.js​ 和 ​.ngstyle.js​ 文件。这将关闭大多数模板编译器，并禁用模板诊断报告。

可用于指示模板编译器生成 ​.metadata.json​ 文件，以使用 ​npm ​软件包进行分发，同时避免产生无法分发至 ​npm ​的 ​.ngfactory.js​ 和 ​.ngstyle.js​ 文件。

对于使用 CLI 生成的库项目，dev 配置默认为 ​true​。

strictMetadataEmit

为 ​true ​时，如果 ​"skipMetadataEmit"​ 为 ​false ​则向 ​.metadata.json​ 文件中报告错误。默认值为 ​false​。只在 ​"skipMetadataEmit"​ 为 ​false ​且 ​"skipTemplateCodegen"​ 为 ​true ​时使用。

该选项是为了验证为生成 ​npm ​包而产生的 ​.metadata.json​ 文件。这种验证是严格的，并且会报告元数据中的错误，以免当模板编译器使用它时再出错。你可以通过在某个导出符号的注释文档中使用 ​@dynamic​ 注解来暂时防止（suppress）该选项报告错误。

​.metadata.json​ 文件即使包含错误也是有效的。如果这些元数据用来确定注解的内容，则模板编译器会报告这些错误。元数据收集器无法预测哪些符号是为了在注解中使用而设计，因此它会先在元数据中为导出的符号中包含错误节点。然后，如果使用了这些符号，则模板编译器可以使用这些错误节点来报告错误。

如果库的客户代码打算在注解中使用某个符号，则模板编译器通常不会在客户方用到该符号之前就报错。此选项允许你在库的构建阶段就检测到这些错误，比如用于生成 Angular 库本身时。

对于使用 CLI 生成的库项目，dev 配置中默认为 ​true​。

strictInjectionParameters

如果为 ​true​（推荐），则报告所提供的参数的错误，无法确定该参数的注入类型。如果为 ​false​（当前为默认值），则标记为 ​@Injectable​ 但其类型无法解析的类的构造函数参数会产生警告。

当你使用 CLI 命令 ​ng new --strict​ 时，默认生成的项目配置中将其设置为 ​true​。

strictTemplates

如果为 ​true​，则启用严格的模板类型检查。

其它严格性标志允许你启用和禁用特定类型的严格模板类型检查。

当你使用 CLI 命令 ​ng new --strict​ 时，默认生成的项目配置中将其设置为 ​true​。

trace

如果为 ​true​，则在编译模板时输出额外的信息。默认值为 ​false​。

命令行选项

虽然大多数时候你都会使用 Angular CLI 间接与 Angular 编译器交互，但在调试某些问题时，你可能会发现直接调用 Angular 编译器很有用。你可以使用 ​@angular/compiler-cli​ npm 包提供的 ​ngc ​命令从命令行调用编译器。

​ngc ​命令只是 TypeScript 的 ​tsc ​编译器命令的包装器，主要通过前面部分讲过的 ​tsconfig.json​ 配置选项进行配置。

除了配置文件，你还可以使用一些 tsc命令行选项来配置 ​ngc​。