Angular 编译器选项全解析读懂 compiler_options 公共 API 与 tsconfig 编译配置【免费下载链接】angularDeliver web apps with confidence 项目地址: https://gitcode.com/GitHub_Trending/an/angular在 Angular 官方仓库中compiler_options.api.md 是一份由 API Extractor 自动生成的公共 API 报告它凝练地呈现了 Angular 编译器的全部公开编译选项从控制模板类型检查严格度的TypeCheckingOptions到决定 AOT 产出形态的TargetOptionscompilationMode再到国际化、扩展诊断Extended Diagnostics、遗留 ngc 兼容等 8 大选项分组。本文以这份 API 报告为主干结合其底层实现文件逐条讲清每个选项的含义、默认值、使用场景与真实生效机制帮助你真正读懂tsconfig.json中angularCompilerOptions的每一项配置并据此搭建出符合项目需求的编译器配置。说明仓库内的goldens/public-api/**/*.api.md属于公共 API 黄金文件文件头明确标注Do not edit this file由 API Extractor 自动生成任何对公共 API 的改动都会在 CI 中被校验。因此它的权威定义源位于源码 public_options.ts二者必须始终保持一致本文的描述即以源码为准。一、compiler_options 公共 API 的整体结构1.1 API 报告是什么该 API 报告按public标记列出所有对外可见的类型正文中共包含7 个接口 1 个枚举类型所属分组职责BazelAndG3Options单仓库/构建系统Bazel 与 g3Google 内部 monorepo相关行为DiagnosticOptions诊断输出扩展模板诊断分类 standalone 严格约束I18nOptions国际化消息提取xi18n与$localize输出控制LegacyNgcOptions兼容层遗留 View Engine/ngc 选项Ivy 仍向后兼容消费MiscOptions杂项无法归入其它组的编译行为TargetOptions编译目标compilationModefull / partial / experimental-localTypeCheckingOptions类型检查模板类型检查的严格度细粒度开关DiagnosticCategoryLabel枚举error/warning/suppress三档诊断级别1.2 它们如何汇聚成一份配置源码中这些接口被合并进同一个超级接口// packages/compiler-cli/src/ngtsc/core/api/src/options.ts export interface NgCompilerOptions extends ts.CompilerOptions, LegacyNgcOptions, BazelAndG3Options, DiagnosticOptions, TypeCheckingOptions, TestOnlyOptions, I18nOptions, TargetOptions, InternalOptions, MiscOptions { [prop: string]: any; }从中可以提炼出两个重要事实NgCompilerOptions是 TypeScript 编译选项的超集——它继承了ts.CompilerOptions因此Angular 选项与 TS 原生选项strictNullChecks、target等共同构成一份完整编译配置同时以[prop: string]: any放宽索引签名以保证向后兼容。选项在 tsconfig 中的存放位置是angularCompilerOptions。编译器入口 perform_compile.ts 中明确读取config.angularCompilerOptions ?? config.bazelOptions?.angularCompilerOptions来获取 Angular 专属配置后者服务于 g3 内部通过bazelOptions传递的场景。典型的使用形态应用项目的tsconfig.json{ compilerOptions: { target: ES2022, strict: true, experimentalDecorators: true }, angularCompilerOptions: { strictTemplates: true, strictInjectionParameters: true, compilationMode: full, extendedDiagnostics: { defaultCategory: warning, checks: { invalidBananaInBox: error, optionalChainNotNullable: suppress } } } }二、TypeCheckingOptions模板类型检查的严格度总开关柜这是日常开发中最常用的一组选项定义于 public_options.ts。它们共同决定 Angular 编译器在生成模板类型检查块Type Check Block时的严谨程度。2.1 先理解strictTemplates这一把主钥匙strictTemplates是整个分组的核心按源码注释public_options.tsIftrue, implies all template strictness flags below (unless individually disabled). Defaults totrue。在编译器的 compiler.ts 中默认值的判定是非假即真/** * strictTemplate is true by default. * Explicit opt-out is required to disable strictness */ private get strictTemplates(): boolean { return this.options.strictTemplates ! false; }也就是说当前仓库默认即开启严格模板模式显式写strictTemplates: false才会关闭。getTypeCheckingConfig()compiler.ts随后据此生成两套基础配置开启时启用完整模板检查并让大多数子开关跟随strictTemplates取值关闭时退化为只做基础 schema 检查。2.2 各严格开关与源码映射关系下表汇总全部开关及其在类型检查配置中的落地位置选项作用文档/实现要点strictInputTypes校验输入绑定的值能否赋给组件/指令对应的 input 属性类型开启时绑定表达式与目标属性两侧均被检查映射到checkTypeOfInputBindingsstrictInputAccessModifiers检查输入绑定是否试图给readonly/private/protected字段赋值即使在strictTemplatesstrictInputTypes下也默认关闭honorAccessModifiersForInputBindings: false是显式 opt-in 项strictNullInputTypes对 input 使用严格空值语义模板中可能产生null/undefined的绑定若 input 类型不含二者即报错置false则对所有绑定表达式加非空断言绕过检查当前实现中随strictTemplates开启而启用strictAttributeTypes检查被指令消费的文本属性的类型例如input matInput disabled中disabled空字符串属性赋给booleaninput依赖strictInputTypes生效strictSafeNavigationTypes空安全导航a?.b返回类型是否严格false时返回anytrue时按a ! null ? a.b : a推断映射到同名配置项strictDomLocalRefTypes模板#ref局部引用是否按document.createElement结果推断类型false时 DOM 引用为any映射到checkTypeOfDomReferencesstrictOutputEventTypes指令输出/动画事件中$event是否按EventEmitter/Subject泛型推断false时$event为any映射到checkTypeOfOutputEventsstrictDomEventTypesDOM 事件中$event是否按HTMLElementEventMap兜底Event推断实现注释指出开启会让input (blur)update($event.target.value)产生 Object is possibly null 之类报错故编译器默认不开启 DOM 事件类型推导strictContextGenerics泛型组件Component类带泛型参数的泛型是否进入模板上下文类型false时按any处理映射到useContextGenericType对无泛型组件无影响strictLiteralTypes模板中的对象/数组字面量使用推断类型而非any严格分支中直接置truetypeCheckHostBindings是否启用 host bindings 的类型检查与宿主元素绑定场景相关实现层面的关键结论是getTypeCheckingConfig()先按strictTemplates选一套基础配置再对每个显式给出的选项做覆盖如 compiler.ts 中对strictInputAccessModifiers、strictNullInputTypes、strictOutputEventTypes、strictDomEventTypes等的! undefined判断。因此你在 tsconfig 里可以只关心要收紧或放水的那一两个开关其余交给strictTemplates派生。三、DiagnosticOptions 与扩展模板诊断系统3.1 三段式诊断级别枚举// packages/compiler-cli/src/ngtsc/core/api/src/public_options.ts#L217-L226 export enum DiagnosticCategoryLabel { Warning warning, // 作为警告不中断编译 Error error, // 作为硬错误使编译失败 Suppress suppress, // 完全忽略该诊断 }这一枚举让编译器里可配置的模板诊断有了统一的分级体系。3.2 extendedDiagnostics 的优先级逻辑export interface DiagnosticOptions { extendedDiagnostics?: { defaultCategory?: DiagnosticCategoryLabel; checks?: {[Name in ExtendedTemplateDiagnosticName]?: DiagnosticCategoryLabel}; }; strictStandalone?: boolean; }对应到编译器实现compiler.tsdefaultCategory的兜底值是warningcontrolFlowPreventingContentProjection: this.options.extendedDiagnostics?.defaultCategory || DiagnosticCategoryLabel.Warning, unusedStandaloneImports: this.options.extendedDiagnostics?.defaultCategory || DiagnosticCategoryLabel.Warning,使用规则非常清晰defaultCategory为所有未被checks单独覆盖的扩展诊断设定默认级别checks按诊断名精确覆盖key 必须是 ExtendedTemplateDiagnosticName 中的成员。实际可用的诊断名从该枚举文件中可见的部分包括invalidBananaInBox错误书写[(value)]双向绑定即香蕉盒里放反了、nullishCoalescingNotNullable、optionalChainNotNullable、textAttributeNotBinding、missingControlFlowDirective、missingNgForOfLet、suffixNotSupported、unusedStandaloneImports未使用的 standalone imports以及controlFlowPreventingContentProjection等。这些诊断的实现与单测可继续阅读 typecheck/extended。在项目实践中你通常先让defaultCategory保持warning把其中真正想卡死构建的项提升为error把误报项置为suppress例如angularCompilerOptions: { strictTemplates: true, extendedDiagnostics: { defaultCategory: warning, checks: { invalidBananaInBox: error, nullishCoalescingNotNullable: suppress } } }3.3 strictStandalone强制去 NgModulestrictStandalone?: boolean的作用是开启后非 standalone 的声明declarations将被禁止并直接产生构建错误。在 compiler.ts 中它以!!this.options.strictStandalone的形式参与 NgModule 分析用于推进全 standalone代码库的迁移治理。注意该检查只作用于当前编译单元跨库导入的组件不受影响。四、TargetOptionscompilationMode 决定 AOT 产物形态export interface TargetOptions { compilationMode?: full | partial | experimental-local; }这是理解 Angular 现代构建链路的关键选项。三种模式的语义见 public_options.ts取值适用场景说明full默认应用 AOT 构建直接生成完整 Ivy 指令ɵɵ...调用的最终代码partial库发布 NPM生成稳定但中间的产物由下游使用方如 Angular CLI 或 ngcc/linker继续链接为完整代码experimental-local开发期快速编辑/刷新仅基于单个源文件本地生成代码不依赖其依赖项的分析结果对支持的代码结构有限制成熟后将改名local在 compiler.ts 中字符串被解析为内部CompilationMode枚举同时 program.ts 等多处会针对experimental-local走专门的程序构建路径。需要特别注意partial模式下对装饰器/元数据的保留要求更高如必须保留输入、输出、HostBinding 等以用于链接期且supportTestBed/supportJitMode等内部能力在partial下会被收敛——这解释了为什么库要用 partial、应用要用 full这一业界惯例。五、I18nOptions国际化编译与消息提取面向多语言应用的xi18n提取流程由这组选项驱动public_options.ts选项含义默认/取值i18nInLocale待翻译输入的语言/locale—i18nOutFormat执行 xi18n 时导出的消息格式xlf、xlf2或xmbi18nOutFile执行 xi18n 时消息文件的输出路径—i18nOutLocale应用目标 localexi18n 请求时使用—enableI18nLegacyMessageIdFormat是否用遗留消息 ID 格式渲染$localize消息默认true若尚未把翻译文件迁移到新版$localizeID 格式则保持开启i18nUseExternalIds翻译变量名是否包含外部消息 ID服务于 Closure Compilergoog.getMsg输出的过渡期i18nNormalizeLineEndingsInICUs处理模板内嵌 ICU 表达式时是否把\r\n归一化为\n默认false未来大版本将反转仅影响templateUrl外部模板i18nPreserveWhitespaceForLegacyExtraction用遗留View Engine管道提取消息时是否保留空白默认true配置示例angularCompilerOptions: { i18nOutLocale: zh-Hans, i18nOutFormat: xlf2, i18nOutFile: ./src/locale/messages.zh.xlf, enableI18nLegacyMessageIdFormat: false }六、BazelAndG3Optionsmonorepo 与 Bazel 构建的专用开关这一组专为 Bazel 化 monorepo典型如 Google 内部的 g3 仓库设计普通 Angular CLI 应用通常无需开启但了解其语义有助于排查为什么库的 d.ts 里多了奇怪 re-export等问题generateDeepReexports当NgModule是经路径映射path-mapped打进应用构建的库模块时编译器会在该 NgModule 旁生成对内部可见指令/管道的私有再导出alias re-export保证用户写import {LibModule} from lib/deep/path/to/module后编译器能原样生成import {LibDir, LibCmp, LibPipe} from lib/deep/path/to/module而不改写路径。应用构建与按 APFAngular Package Format打包的库应关闭此选项。onlyPublishPublicTypingsForNgModules过滤 NgModule 在.d.ts中的类型指针只列出该模块公开导出的声明/导入/导出避免把内部类型泄露给消费者。annotateForClosureCompiler是否插入 Closure Compiler 需要的 JSDoc 类型注解。onlyExplicitDeferDependencyImports是否仅根据Component.deferredImports显式列表为defer块生成动态 import用于在特定内部配置下收紧本地编译local compilation对defer的支持。generateExtraImportsInLocalMode本地编译模式下额外生成等价于全量模式中由静态解析得到的组件依赖 import供 g3 打包链路使用。legacyOptionalChaining空安全导航是否遵循 JavaScript 可选链规范undefined而非null默认false。enableTemplateSourceLocations是否生成额外代码把元素源码位置作为 DOM 属性写进页面用于调试定位。_experimentalAllowEmitDeclarationOnly实验性开关——允许在emitDeclarationOnly下进入仅发声明模式依赖本地编译快速产出.d.ts而不做类型检查对不支持的外部引用存在代码结构限制命名中的下划线前缀表明其为内部实验能力。七、LegacyNgcOptionsView Engine 时代的兼容层这些选项由旧的 View Engine 编译器定义Ivy 出于向后兼容仍会消费预期未来某个版本移除flatModuleOutFile/flatModuleId扁平模块flat module打包方案——把整个库合成单一index.d.tsindex.metadata.jsonangular/core、angular/common当年即以这种方式发布。flatModuleId仅在同时设置flatModuleOutFile时有意义。具体约束见 public_options.ts。strictInjectionParameters当构造函数参数无法解析注入类型时false默认只告警、true直接报错。这也是 CLI 项目默认开启strictInjectionParameters: true的由来。preserveWhitespaces编译模板时是否保留空文本节点Angular 6 起默认false。allowEmptyCodegenFiles已被标注deprecated——此选项不再使用。八、MiscOptions难以归类但同样关键的行为开关export interface MiscOptions { compileNonExportedClasses?: boolean; disableTypeScriptVersionCheck?: boolean; forbidOrphanComponents?: boolean; }compileNonExportedClasses默认true——是否编译未导出的类。若置false编译器将跳过未导出类的代码生成可缩小产物。disableTypeScriptVersionCheck关闭对 TypeScript 版本匹配的校验正常编译期会用编译器的版本要求与typescript实际版本做一致性检查。forbidOrphanComponents开启运行时保护阻止未先加载其 NgModule 就渲染组件孤儿组件的情况。注意它只作用于当前编译单元——从别的库导入、且该库编译时未开启此选项的组件被孤儿式渲染时不会报错。九、把它们串起来选择你的编译配置综合以上内容一份生产应用 严格模板的推荐angularCompilerOptions骨架如下angularCompilerOptions: { compilationMode: full, strictTemplates: true, strictInputAccessModifiers: true, strictInjectionParameters: true, extendedDiagnostics: { defaultCategory: warning, checks: { invalidBananaInBox: error } } }如果是发布到 NPM 的库则应把compilationMode改为partial并确认其依赖被正确链接如果只用 xi18n 提取消息配合 packages/localize 生态将i18nOutFormat指向所需格式。对照速查应用 AOT 主构建 →full库发布 →partial纯开发增量 →experimental-local实验性。想让模板更难写错 →strictTemplates: true 在strictInputAccessModifiers、strictStandalone上收紧。想让某条扩展模板诊断从警告升级/降级 → 编辑extendedDiagnostics.checks。其余 g3/Bazel、扁平模块选项仅在你确实运行 Bazel 化 monorepo 或维护遗留打包流程时才需要关心。所有选项的类型权威定义与字段级 JSDoc 都可在 public_options.ts 中逐条核对而它被合并进NgCompilerOptions、再经 perform_compile.ts 从 tsconfig 读入的完整链路正是理解 Angular AOT 编译器配置体系的入口。【免费下载链接】angularDeliver web apps with confidence 项目地址: https://gitcode.com/GitHub_Trending/an/angular创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Angular 编译器选项全解析：读懂 compiler_options 公共 API 与 tsconfig 编译配置
Angular 编译器选项全解析读懂 compiler_options 公共 API 与 tsconfig 编译配置【免费下载链接】angularDeliver web apps with confidence 项目地址: https://gitcode.com/GitHub_Trending/an/angular在 Angular 官方仓库中compiler_options.api.md 是一份由 API Extractor 自动生成的公共 API 报告它凝练地呈现了 Angular 编译器的全部公开编译选项从控制模板类型检查严格度的TypeCheckingOptions到决定 AOT 产出形态的TargetOptionscompilationMode再到国际化、扩展诊断Extended Diagnostics、遗留 ngc 兼容等 8 大选项分组。本文以这份 API 报告为主干结合其底层实现文件逐条讲清每个选项的含义、默认值、使用场景与真实生效机制帮助你真正读懂tsconfig.json中angularCompilerOptions的每一项配置并据此搭建出符合项目需求的编译器配置。说明仓库内的goldens/public-api/**/*.api.md属于公共 API 黄金文件文件头明确标注Do not edit this file由 API Extractor 自动生成任何对公共 API 的改动都会在 CI 中被校验。因此它的权威定义源位于源码 public_options.ts二者必须始终保持一致本文的描述即以源码为准。一、compiler_options 公共 API 的整体结构1.1 API 报告是什么该 API 报告按public标记列出所有对外可见的类型正文中共包含7 个接口 1 个枚举类型所属分组职责BazelAndG3Options单仓库/构建系统Bazel 与 g3Google 内部 monorepo相关行为DiagnosticOptions诊断输出扩展模板诊断分类 standalone 严格约束I18nOptions国际化消息提取xi18n与$localize输出控制LegacyNgcOptions兼容层遗留 View Engine/ngc 选项Ivy 仍向后兼容消费MiscOptions杂项无法归入其它组的编译行为TargetOptions编译目标compilationModefull / partial / experimental-localTypeCheckingOptions类型检查模板类型检查的严格度细粒度开关DiagnosticCategoryLabel枚举error/warning/suppress三档诊断级别1.2 它们如何汇聚成一份配置源码中这些接口被合并进同一个超级接口// packages/compiler-cli/src/ngtsc/core/api/src/options.ts export interface NgCompilerOptions extends ts.CompilerOptions, LegacyNgcOptions, BazelAndG3Options, DiagnosticOptions, TypeCheckingOptions, TestOnlyOptions, I18nOptions, TargetOptions, InternalOptions, MiscOptions { [prop: string]: any; }从中可以提炼出两个重要事实NgCompilerOptions是 TypeScript 编译选项的超集——它继承了ts.CompilerOptions因此Angular 选项与 TS 原生选项strictNullChecks、target等共同构成一份完整编译配置同时以[prop: string]: any放宽索引签名以保证向后兼容。选项在 tsconfig 中的存放位置是angularCompilerOptions。编译器入口 perform_compile.ts 中明确读取config.angularCompilerOptions ?? config.bazelOptions?.angularCompilerOptions来获取 Angular 专属配置后者服务于 g3 内部通过bazelOptions传递的场景。典型的使用形态应用项目的tsconfig.json{ compilerOptions: { target: ES2022, strict: true, experimentalDecorators: true }, angularCompilerOptions: { strictTemplates: true, strictInjectionParameters: true, compilationMode: full, extendedDiagnostics: { defaultCategory: warning, checks: { invalidBananaInBox: error, optionalChainNotNullable: suppress } } } }二、TypeCheckingOptions模板类型检查的严格度总开关柜这是日常开发中最常用的一组选项定义于 public_options.ts。它们共同决定 Angular 编译器在生成模板类型检查块Type Check Block时的严谨程度。2.1 先理解strictTemplates这一把主钥匙strictTemplates是整个分组的核心按源码注释public_options.tsIftrue, implies all template strictness flags below (unless individually disabled). Defaults totrue。在编译器的 compiler.ts 中默认值的判定是非假即真/** * strictTemplate is true by default. * Explicit opt-out is required to disable strictness */ private get strictTemplates(): boolean { return this.options.strictTemplates ! false; }也就是说当前仓库默认即开启严格模板模式显式写strictTemplates: false才会关闭。getTypeCheckingConfig()compiler.ts随后据此生成两套基础配置开启时启用完整模板检查并让大多数子开关跟随strictTemplates取值关闭时退化为只做基础 schema 检查。2.2 各严格开关与源码映射关系下表汇总全部开关及其在类型检查配置中的落地位置选项作用文档/实现要点strictInputTypes校验输入绑定的值能否赋给组件/指令对应的 input 属性类型开启时绑定表达式与目标属性两侧均被检查映射到checkTypeOfInputBindingsstrictInputAccessModifiers检查输入绑定是否试图给readonly/private/protected字段赋值即使在strictTemplatesstrictInputTypes下也默认关闭honorAccessModifiersForInputBindings: false是显式 opt-in 项strictNullInputTypes对 input 使用严格空值语义模板中可能产生null/undefined的绑定若 input 类型不含二者即报错置false则对所有绑定表达式加非空断言绕过检查当前实现中随strictTemplates开启而启用strictAttributeTypes检查被指令消费的文本属性的类型例如input matInput disabled中disabled空字符串属性赋给booleaninput依赖strictInputTypes生效strictSafeNavigationTypes空安全导航a?.b返回类型是否严格false时返回anytrue时按a ! null ? a.b : a推断映射到同名配置项strictDomLocalRefTypes模板#ref局部引用是否按document.createElement结果推断类型false时 DOM 引用为any映射到checkTypeOfDomReferencesstrictOutputEventTypes指令输出/动画事件中$event是否按EventEmitter/Subject泛型推断false时$event为any映射到checkTypeOfOutputEventsstrictDomEventTypesDOM 事件中$event是否按HTMLElementEventMap兜底Event推断实现注释指出开启会让input (blur)update($event.target.value)产生 Object is possibly null 之类报错故编译器默认不开启 DOM 事件类型推导strictContextGenerics泛型组件Component类带泛型参数的泛型是否进入模板上下文类型false时按any处理映射到useContextGenericType对无泛型组件无影响strictLiteralTypes模板中的对象/数组字面量使用推断类型而非any严格分支中直接置truetypeCheckHostBindings是否启用 host bindings 的类型检查与宿主元素绑定场景相关实现层面的关键结论是getTypeCheckingConfig()先按strictTemplates选一套基础配置再对每个显式给出的选项做覆盖如 compiler.ts 中对strictInputAccessModifiers、strictNullInputTypes、strictOutputEventTypes、strictDomEventTypes等的! undefined判断。因此你在 tsconfig 里可以只关心要收紧或放水的那一两个开关其余交给strictTemplates派生。三、DiagnosticOptions 与扩展模板诊断系统3.1 三段式诊断级别枚举// packages/compiler-cli/src/ngtsc/core/api/src/public_options.ts#L217-L226 export enum DiagnosticCategoryLabel { Warning warning, // 作为警告不中断编译 Error error, // 作为硬错误使编译失败 Suppress suppress, // 完全忽略该诊断 }这一枚举让编译器里可配置的模板诊断有了统一的分级体系。3.2 extendedDiagnostics 的优先级逻辑export interface DiagnosticOptions { extendedDiagnostics?: { defaultCategory?: DiagnosticCategoryLabel; checks?: {[Name in ExtendedTemplateDiagnosticName]?: DiagnosticCategoryLabel}; }; strictStandalone?: boolean; }对应到编译器实现compiler.tsdefaultCategory的兜底值是warningcontrolFlowPreventingContentProjection: this.options.extendedDiagnostics?.defaultCategory || DiagnosticCategoryLabel.Warning, unusedStandaloneImports: this.options.extendedDiagnostics?.defaultCategory || DiagnosticCategoryLabel.Warning,使用规则非常清晰defaultCategory为所有未被checks单独覆盖的扩展诊断设定默认级别checks按诊断名精确覆盖key 必须是 ExtendedTemplateDiagnosticName 中的成员。实际可用的诊断名从该枚举文件中可见的部分包括invalidBananaInBox错误书写[(value)]双向绑定即香蕉盒里放反了、nullishCoalescingNotNullable、optionalChainNotNullable、textAttributeNotBinding、missingControlFlowDirective、missingNgForOfLet、suffixNotSupported、unusedStandaloneImports未使用的 standalone imports以及controlFlowPreventingContentProjection等。这些诊断的实现与单测可继续阅读 typecheck/extended。在项目实践中你通常先让defaultCategory保持warning把其中真正想卡死构建的项提升为error把误报项置为suppress例如angularCompilerOptions: { strictTemplates: true, extendedDiagnostics: { defaultCategory: warning, checks: { invalidBananaInBox: error, nullishCoalescingNotNullable: suppress } } }3.3 strictStandalone强制去 NgModulestrictStandalone?: boolean的作用是开启后非 standalone 的声明declarations将被禁止并直接产生构建错误。在 compiler.ts 中它以!!this.options.strictStandalone的形式参与 NgModule 分析用于推进全 standalone代码库的迁移治理。注意该检查只作用于当前编译单元跨库导入的组件不受影响。四、TargetOptionscompilationMode 决定 AOT 产物形态export interface TargetOptions { compilationMode?: full | partial | experimental-local; }这是理解 Angular 现代构建链路的关键选项。三种模式的语义见 public_options.ts取值适用场景说明full默认应用 AOT 构建直接生成完整 Ivy 指令ɵɵ...调用的最终代码partial库发布 NPM生成稳定但中间的产物由下游使用方如 Angular CLI 或 ngcc/linker继续链接为完整代码experimental-local开发期快速编辑/刷新仅基于单个源文件本地生成代码不依赖其依赖项的分析结果对支持的代码结构有限制成熟后将改名local在 compiler.ts 中字符串被解析为内部CompilationMode枚举同时 program.ts 等多处会针对experimental-local走专门的程序构建路径。需要特别注意partial模式下对装饰器/元数据的保留要求更高如必须保留输入、输出、HostBinding 等以用于链接期且supportTestBed/supportJitMode等内部能力在partial下会被收敛——这解释了为什么库要用 partial、应用要用 full这一业界惯例。五、I18nOptions国际化编译与消息提取面向多语言应用的xi18n提取流程由这组选项驱动public_options.ts选项含义默认/取值i18nInLocale待翻译输入的语言/locale—i18nOutFormat执行 xi18n 时导出的消息格式xlf、xlf2或xmbi18nOutFile执行 xi18n 时消息文件的输出路径—i18nOutLocale应用目标 localexi18n 请求时使用—enableI18nLegacyMessageIdFormat是否用遗留消息 ID 格式渲染$localize消息默认true若尚未把翻译文件迁移到新版$localizeID 格式则保持开启i18nUseExternalIds翻译变量名是否包含外部消息 ID服务于 Closure Compilergoog.getMsg输出的过渡期i18nNormalizeLineEndingsInICUs处理模板内嵌 ICU 表达式时是否把\r\n归一化为\n默认false未来大版本将反转仅影响templateUrl外部模板i18nPreserveWhitespaceForLegacyExtraction用遗留View Engine管道提取消息时是否保留空白默认true配置示例angularCompilerOptions: { i18nOutLocale: zh-Hans, i18nOutFormat: xlf2, i18nOutFile: ./src/locale/messages.zh.xlf, enableI18nLegacyMessageIdFormat: false }六、BazelAndG3Optionsmonorepo 与 Bazel 构建的专用开关这一组专为 Bazel 化 monorepo典型如 Google 内部的 g3 仓库设计普通 Angular CLI 应用通常无需开启但了解其语义有助于排查为什么库的 d.ts 里多了奇怪 re-export等问题generateDeepReexports当NgModule是经路径映射path-mapped打进应用构建的库模块时编译器会在该 NgModule 旁生成对内部可见指令/管道的私有再导出alias re-export保证用户写import {LibModule} from lib/deep/path/to/module后编译器能原样生成import {LibDir, LibCmp, LibPipe} from lib/deep/path/to/module而不改写路径。应用构建与按 APFAngular Package Format打包的库应关闭此选项。onlyPublishPublicTypingsForNgModules过滤 NgModule 在.d.ts中的类型指针只列出该模块公开导出的声明/导入/导出避免把内部类型泄露给消费者。annotateForClosureCompiler是否插入 Closure Compiler 需要的 JSDoc 类型注解。onlyExplicitDeferDependencyImports是否仅根据Component.deferredImports显式列表为defer块生成动态 import用于在特定内部配置下收紧本地编译local compilation对defer的支持。generateExtraImportsInLocalMode本地编译模式下额外生成等价于全量模式中由静态解析得到的组件依赖 import供 g3 打包链路使用。legacyOptionalChaining空安全导航是否遵循 JavaScript 可选链规范undefined而非null默认false。enableTemplateSourceLocations是否生成额外代码把元素源码位置作为 DOM 属性写进页面用于调试定位。_experimentalAllowEmitDeclarationOnly实验性开关——允许在emitDeclarationOnly下进入仅发声明模式依赖本地编译快速产出.d.ts而不做类型检查对不支持的外部引用存在代码结构限制命名中的下划线前缀表明其为内部实验能力。七、LegacyNgcOptionsView Engine 时代的兼容层这些选项由旧的 View Engine 编译器定义Ivy 出于向后兼容仍会消费预期未来某个版本移除flatModuleOutFile/flatModuleId扁平模块flat module打包方案——把整个库合成单一index.d.tsindex.metadata.jsonangular/core、angular/common当年即以这种方式发布。flatModuleId仅在同时设置flatModuleOutFile时有意义。具体约束见 public_options.ts。strictInjectionParameters当构造函数参数无法解析注入类型时false默认只告警、true直接报错。这也是 CLI 项目默认开启strictInjectionParameters: true的由来。preserveWhitespaces编译模板时是否保留空文本节点Angular 6 起默认false。allowEmptyCodegenFiles已被标注deprecated——此选项不再使用。八、MiscOptions难以归类但同样关键的行为开关export interface MiscOptions { compileNonExportedClasses?: boolean; disableTypeScriptVersionCheck?: boolean; forbidOrphanComponents?: boolean; }compileNonExportedClasses默认true——是否编译未导出的类。若置false编译器将跳过未导出类的代码生成可缩小产物。disableTypeScriptVersionCheck关闭对 TypeScript 版本匹配的校验正常编译期会用编译器的版本要求与typescript实际版本做一致性检查。forbidOrphanComponents开启运行时保护阻止未先加载其 NgModule 就渲染组件孤儿组件的情况。注意它只作用于当前编译单元——从别的库导入、且该库编译时未开启此选项的组件被孤儿式渲染时不会报错。九、把它们串起来选择你的编译配置综合以上内容一份生产应用 严格模板的推荐angularCompilerOptions骨架如下angularCompilerOptions: { compilationMode: full, strictTemplates: true, strictInputAccessModifiers: true, strictInjectionParameters: true, extendedDiagnostics: { defaultCategory: warning, checks: { invalidBananaInBox: error } } }如果是发布到 NPM 的库则应把compilationMode改为partial并确认其依赖被正确链接如果只用 xi18n 提取消息配合 packages/localize 生态将i18nOutFormat指向所需格式。对照速查应用 AOT 主构建 →full库发布 →partial纯开发增量 →experimental-local实验性。想让模板更难写错 →strictTemplates: true 在strictInputAccessModifiers、strictStandalone上收紧。想让某条扩展模板诊断从警告升级/降级 → 编辑extendedDiagnostics.checks。其余 g3/Bazel、扁平模块选项仅在你确实运行 Bazel 化 monorepo 或维护遗留打包流程时才需要关心。所有选项的类型权威定义与字段级 JSDoc 都可在 public_options.ts 中逐条核对而它被合并进NgCompilerOptions、再经 perform_compile.ts 从 tsconfig 读入的完整链路正是理解 Angular AOT 编译器配置体系的入口。【免费下载链接】angularDeliver web apps with confidence 项目地址: https://gitcode.com/GitHub_Trending/an/angular创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考