Angular compiler-cli ErrorCode 错误码体系全解析：枚举定义、NG 编码机制与诊断实现

Angular compiler-cli ErrorCode 错误码体系全解析：枚举定义、NG 编码机制与诊断实现

【免费下载链接】angularDeliver web apps with confidence 🚀项目地址: https://gitcode.com/GitHub_Trending/an/angular

本文以 Angular 仓库公开 API 清单 error_code.api.md 中的ErrorCode枚举为骨架，结合其底层实现文件packages/compiler-cli/src/ngtsc/diagnostics下的源码，系统梳理 Angular 模板编译器（ngtsc）与@angular/compiler-cli使用的全部错误码：它们的数值分布规律、各错误族（装饰器、组件/指令、NgModule、模板类型检查等）的含义，以及"内部错误码如何被编码成你看到的NGxxxx形式"的底层原理。读完本文，你将能根据控制台中的NG前缀错误码快速反查对应的枚举成员与触发场景，也能理解 Angular 编译器错误诊断从抛出到格式化输出的完整链路。

一、ErrorCode是什么：一份由 API Extractor 锁定的公开契约

ErrorCode是 Angular compiler-cli 中 ngtsc（新一代 Angular TypeScript 编译器）统一定义的诊断错误码枚举，被标注为@public（见 error_code.ts），并从诊断模块的公共出口 index.ts 中export {ErrorCode}导出。

error_code.api.md 则是通过 API Extractor 自动生成的API 报告文件，其头部声明 "Do not edit this file. It is a report generated by API Extractor"，意味着它的作用是锁死ErrorCode的公开成员名称与数值，防止在演进过程中意外改号或改名导致下游工具（如 Angular Language Service、编辑器插件、自定义扩展诊断）失配。

该文件展示的枚举拥有 120 个成员，数值覆盖约 20 个语义区间。源码中每个成员往往带有 JSDoc 注释说明触发条件，甚至配有错误模板示例（见 error_code.ts）。因此，本文后面每一个错误族的小结都可以视为"枚举 + 官方注释"的精读结果。

二、数值分布规律：读懂错误码的"分区"

从整体看，ErrorCode的数值按编译器处理阶段做了分区，区间首位数字即代表诊断来源：

源码还保留了一条编号纪律：6999 曾分配给NGMODULE_VE_DEPENDENCY_ON_IVY_LIB（View Engine 时代依赖 Ivy 库的旧错误），为避免混淆，该号码被明确注释为"不再复用"（见 error_code.ts）。这说明错误码一旦发布便被视作稳定标识，不会二次分配。

2.1 负数成员的用途

注意表中若干成员为负值（如-2009、-3003、-8001）。在 util.ts 中errorCodeWithGuideFromDiagnosticCode仅对负值错误码做指南（guide）查找，返回-absoluteErrorCode命中的成员；随后 addDiagnosticDetails 会向诊断消息追加Find more at {ERROR_DETAILS_PAGE_BASE_URL}/NG1001形式的官方错误指南链接（基础地址由 error_details_base_url.ts 依据版本号计算，预发布版指向next前缀域名）。测试用例对此给出了实证（format_compiler_error_spec.ts）。需要强调的是，不论枚举值是正是负，最终对外展示的错误码一律取绝对值（下一节详述），符号只是编译流水线内部使用的元信息。

三、从枚举值到NGxxxx：-99 标记编码机制

这是理解 Angular 编译器错误码最关键的一节。Angular 的诊断会复用 TypeScript 的ts.Diagnostic结构，而 TS 的格式化器会给每个诊断号硬编码TS前缀。为了让 Angular 自有的诊断显示成NG前缀，error_code.ts 采用了巧妙的"标记数"方案：

1. ERROR_CODE_MARKER = 99，即所有 Angular 诊断的数值都以99打头；
2. ngErrorCode(code)计算出-(99 * 10^digits + |code|)作为真正的ts.Diagnostic.code。例如枚举成员DECORATOR_ARG_NOT_LITERAL = -1001，取绝对值后编码为-991001；DECORATOR_ARITY_WRONG = 1002编码为-991002（测试见 format_compiler_error_spec.ts）；
3. 在诊断文本格式化阶段，replaceTsWithNgInErrors用正则/(\u001b\[\d+m ?)TS-99(\d+: ?\u001b\[\d+m)/g把TS-99替换为NG，于是TS-991002显示为NG1002（util.ts）。

export const ERROR_CODE_MARKER = 99; export function ngErrorCode(code: ErrorCode): number { const absoluteCode = Math.abs(code); return -(ERROR_CODE_MARKER * 10 ** decimalDigits(absoluteCode) + absoluteCode); } export function formatCompilerErrorCode(code: number): string { return `NG${Math.abs(code)}`; }

因此，你在构建日志或 IDE 里看到的NG1001、NG8111等，对应的ts.Diagnostic.code实际是-991001、-998111，而枚举原文分别是-1001/1002与8111。三者的换算关系可概括为：

• 枚举值：Angular 内部语义号（可能带符号）；
• TS 诊断码：-99拼接四位/五位补零绝对值（ngErrorCode产物）；
• 展示号：NG+ 绝对值（formatCompilerErrorCode产物）。

这样设计的好处是让所有 Angular 错误码天然规避 TS 自带诊断的码段，并能在同一套 TS 管道中无损往返（反向解析由absoluteErrorCodeFromDiagnosticCode完成，先取绝对值、剥离99标记，见 util.ts）。

四、错误族详解（全量 120 个成员）

下面按错误族逐个给出成员、数值与含义。含义文字取自枚举源码注释与 API 报告，可直接作为"报错排查手册"使用。

4.1 装饰器与 initializer API（-1001 ~ 1100）

4.2 组件、指令、宿主指令与样式资源（-2003 ~ 2028）

4.3 符号与导入生成（-3003 ~ 3004）

4.4 编译器配置（4001 ~ 4006）

4.5 解析错误（5001 ~ 5002）

4.6 NgModule 分析（-6100 / 6001 ~ 6009）

4.7 Schema 校验与模板语义（-8001 ~ -8003，8004 ~ 8029）

4.8 模板类型检查与信号语义（8101 ~ 8118）

4.9 其余专用码段（8900 ~ 11102）

特别说明：源码注释明确指出10XXX 码段专门保留给非ts.DiagnosticCategory.Error类别的诊断（error_code.ts），这类诊断由编译器在 Language Service 等工具的要求下生成，因此在常见构建报错中不出现。

五、错误码如何被生产与消费：诊断抛出的底层链路

仅知道枚举含义还不够。ErrorCode真正发挥作用，是在 error.ts 提供的工具函数中，把"枚举码 + TS AST 节点 + 消息"组装成ts.Diagnostic。

致命诊断FatalDiagnosticError：当 ngtsc 在分析阶段遇到无法继续的错误时，会直接抛出该异常，内部保存错误码、ts.Node、消息与可选的关联信息（error.ts）。其toDiagnostic()调用makeDiagnostic完成转换。makeDiagnostic的核心逻辑是：

export function makeDiagnostic( code: ErrorCode, node: ts.Node, messageText: string | ts.DiagnosticMessageChain, relatedInformation?: ts.DiagnosticRelatedInformation[], category: ts.DiagnosticCategory = ts.DiagnosticCategory.Error, ): ts.DiagnosticWithLocation { node = ts.getOriginalNode(node); return { category, code: ngErrorCode(code), file: ts.getOriginalNode(node).getSourceFile(), start: node.getStart(undefined, false), length: node.getWidth(), messageText, relatedInformation, }; }

关键点：最终写入ts.Diagnostic.code的并非枚举原值，而是经过ngErrorCode编码后的-99 标记数值（第 3 节已推导）。同时makeDiagnostic会回溯到原始节点（ts.getOriginalNode），保证经过中间代码变换后，报错位置仍指向开发者手写的源码。

配套工具还包括makeDiagnosticChain/makeRelatedInformation（构造多级消息链与关联位置信息）、addDiagnosticChain（把补充说明追加进消息链）、isFatalDiagnosticError（运行时类型守卫）与isLocalCompilationDiagnostics（识别局部编译相关错误，供 g3 等 1P 环境附加额外信息），全部从 index.ts 导出。

六、错误码的消费方：格式化、指南链接与外部工具

ErrorCode生态的另外三个消费场景：

1. 展示格式化：formatCompilerErrorCode(code)返回NG${Math.abs(code)}。测试验证DECORATOR_ARG_NOT_LITERAL与DECORATOR_ARITY_WRONG分别格式化为NG1001、NG1002（format_compiler_error_spec.ts），与开发者日常在终端看到的错误号完全一致。
2. 错误指南跳转：addDiagnosticDetails向消息文本追加Find more at <base>/NG1001形式提示，测试断言消息拼接结果（同一 spec 的第三个用例）。指南基础地址根据@angular/compiler的VERSION计算：正式版指向v<major>.angular.dev/errors，预发布（-next/-rc）指向next.angular.dev/errors（error_details_base_url.ts）。
3. 负值错误码的"是否有指南"判定：errorCodeWithGuideFromDiagnosticCode先剥离99标记还原枚举码，再检查其是否命中负值成员（util.ts），从而决定是否值得为该诊断展示 error guide 链接。这也解释了为何 4.1~4.9 表格中部分成员刻意保留负数形态——它们是"拥有官方错误指南"的家族。

七、扩展阅读与排错建议

• 想查看ErrorCode的完整 JSDoc 与模板示例，直接读枚举实现 error_code.ts，比 API 报告更详细；
• 想确认某个诊断号与工具链的绑定关系是否被破坏，比对 API 报告 error_code.api.md 与源码是否一致（goldens 目录由 CI 校验）；
• 想了解错误码格式化与指南链接的行为契约，阅读测试 format_compiler_error_spec.ts；
• 当遇到形如NG8005的错误时，建议先反查上表定位错误族（8005 属模板语义区），再对照@for/@let/@defer/信号等对应特性写法修正模板，必要时开启strictTemplates与extendedDiagnostics让编译器在早期暴露更多 81xx 类问题。

总体而言，ErrorCode是理解 Angular 编译器"如何说话"的钥匙：掌握它的分区规则与 -99 编码机制，既能在排错时快速定位错误语义域，也能在开发依赖 compiler-cli 的工具链时正确使用ngErrorCode、formatCompilerErrorCode与诊断指南接口。

【免费下载链接】angularDeliver web apps with confidence 🚀项目地址: https://gitcode.com/GitHub_Trending/an/angular