Angular NG0100 错误完整解析：ExpressionChangedAfterItHasBeenCheckedError 成因、触发场景与调试修复指南

本指南以 Angular 官方错误参考文档 adev/src/content/reference/errors/NG0100.md 为核心，结合本仓库 @angular/core 中该错误实际的抛出与检查源码，系统讲解 ExpressionChangedAfterItHasBeenCheckedError（NG0100）为什么会发生、Angular 为什么坚持抛出它、它通常在哪些代码场景中出现，以及官方推荐的逐步调试与修复方法。阅读完本文，你将能够读懂 NG0100 报错信息中的每个字段，独立定位到出问题的模板绑定与生命周期钩子，并给出正确的重构方案。

NG0100 是什么：什么条件下 Angular 会抛出它

ExpressionChangedAfterItHasBeenCheckedError 的完整报错形如：

ExpressionChangedAfterItHasBeenCheckedError: Expression has changed after it was checked. Previous value for 'xxx': '...'. Current value: '...'. Expression location: ... component

从 NG0100.md 的定义可知它的触发前提非常明确：

Angular throws an ExpressionChangedAfterItHasBeenCheckedError when an expression value has been changed after change detection has completed. Angular only throws this error in development mode.

也就是说，只有当某次变更检测运行结束之后，模板中某个绑定表达式求出的值又发生了变化时，Angular 才在开发模式下抛出该错误；生产环境构建中不会出现它。这一点也能在源码中得到印证：错误抛出路径被严格包在 ngDevMode && isInCheckNoChangesMode() 的守卫之中（见 packages/core/src/render3/bindings.ts），ngDevMode 为 false 的生产构建根本不会进入这条分支。

其错误代码为 RuntimeErrorCode.EXPRESSION_CHANGED_AFTER_CHECKED = -100，见 packages/core/src/errors.ts。值得一提的设计细节是：代码使用负数表示“该错误在 angular.dev 上有专门的详解指南”（Note: the minus sign denotes the fact that a particular code has a detailed guide on angular.io，见 packages/core/src/errors.ts），NG0100 正是官方为其配置了专项文档的错误之一。

为什么 Angular 要坚持做“二次检查”

理解 NG0100 的关键在于理解 Angular 在开发模式下的额外工作。文档 NG0100.md 明确解释：

• 在开发模式下，每完成一次变更检测之后，Angular 都会额外执行一遍校验（check no changes），用来确认模板中的绑定没有被再次改变；
• 这一机制用于捕捉视图被留在不一致状态的错误，例如某个方法或 getter 每次被调用都返回不同的值，或者子组件反过来修改了父组件的值；
• 只要发生上述情况，就说明变更检测没有达到稳定（stabilized）状态；
• Angular 抛出该错误以确保视图中的数据永远被正确反映，从而避免界面行为反复无常（erratic UI behavior），甚至避免潜在的死循环（infinite loop）。

从实现层面看，这套“正常变更检测 + 二次校验”的双遍机制运行于 checkNoChanges 模式。核心入口 packages/core/src/render3/instructions/change_detection.ts 中的 checkNoChangesInternal，配合 isInCheckNoChangesMode() 标志位，让 Angular 在第二遍检查时不再只是更新视图，而是逐个比对绑定新旧值并决定是否抛出 NG0100。

最容易踩中 NG0100 的几类典型场景

文档 NG0100.md 明确指出，该错误在以下阶段最常出现：

1. 新添加了模板表达式（template expressions）时；
2. 刚开始实现生命周期钩子，尤其是 ngAfterViewInit 或 ngOnChanges 时；
3. 处理加载状态（loading status）与异步操作时；
4. 子组件修改了父组件的绑定（child component changes its parent bindings）时。

把这几类场景和源码对应起来，可以归纳为两种本质原因：

• 表达式本身不稳定：模板中调用的方法 / getter 存在副作用或每次都重新计算产生新值，例如 {{ getFormattedDate() }} 内部每次调用都 new Date() 或拼接数组，导致“上一次读到的旧值”与“二次校验时读到的值”不一致；
• 在错误的时机修改数据：在视图渲染完成后（如 ngAfterViewInit 回调里）再去修改已渲染依赖的数据，或子组件在自身变更检测期间直接修改父组件输入所依赖的属性。

源码视角：NG0100 的错误信息是如何构造的

实际的报错由 throwErrorIfNoChangesMode() 抛出，其完整实现位于 packages/core/src/render3/errors.ts。通过它你能读懂报错消息里每一段话的含义：

let msg =
  `ExpressionChangedAfterItHasBeenCheckedError: Expression has changed after it was checked. ` +
  `Previous value${field}: '${formatValue(oldValue)}'. Current value: '${formatValue(currValue)}'.` +
  (componentClassName ? ` Expression location: ${componentClassName} component` : '');
if (creationMode) {
  msg +=
    ` It seems like the view has been created after its parent and its children have been dirty checked.` +
    ` Has it been created in a change detection hook?`;
}
throw new RuntimeError(RuntimeErrorCode.EXPRESSION_CHANGED_AFTER_CHECKED, msg);

几点值得注意的工程细节：

• field 与组件定位：若绑定有属性名，会以 Previous value for 'propName' 形式给出（propName 由 getExpressionChangedErrorDetails 结合插值元数据解析得到，见 packages/core/src/render3/errors.ts）；同时会尝试定位抛出位置的宿主组件类名，输出 Expression location: SomeComponent component；
• 旧值语义：当二次校验发生在视图首次创建之前（oldValue === NO_CHANGE）时，会按 View Engine 的兼容行为把旧值视为 undefined 再参与比较；
• 值格式化与截断：formatValue 对对象/数组走 JSON.stringify，并对超过 200 个字符的值截断追加省略号（VALUE_STRING_LENGTH_LIMIT = 200，见 packages/core/src/render3/errors.ts 与 L88-L100），防止巨型对象刷屏；
• 附加提示语：若视图是在“父组件及其子组件已 dirty check 之后才被创建”的（creationMode === true），会追加提示 Has it been created in a change detection hook?——这正是 ngAfterViewInit 里动态创建视图后立刻抛错的典型信号。

底层绑定检查流程：bindingUpdated 与 devModeEqual 豁免机制

从绑定更新指令的入口 bindingUpdated（packages/core/src/render3/bindings.ts）可以看清 NG0100 在单条绑定上的完整判定链：

1. 若模板传入 NO_CHANGE 哨兵值，直接视为无变化返回 false；
2. 用 Object.is 比较 lView 中保存的旧值与本次新值，相同则返回 false；
3. 一旦不同，则判断是否处于 ngDevMode && isInCheckNoChangesMode()：
   • 处于二次校验模式时，会先调用 devModeEqual(oldValueToCompare, value) 做一次“开发模式等价”判定——如果新旧值在开发模式语义下被视为等价（例如数字 1 与字符串 '1'），则豁免抛错，同时提前返回且不把新值写回 lView（源码注释解释这正是为了“下次变更检测不会再次误判为变化”）；
   • 否则调用 throwErrorIfNoChangesMode 抛出 NG0100；
4. 正常（非二次校验）模式下才把新值写回 lView 并返回 true。

这套机制解释了 NG0100 的另一个特性：报错与否并不完全等同于“值是否变了”，而是以 devModeEqual 为边界做了一次宽容处理，避免开发模式下对类型宽松绑定的过度敏感。

关于 OnPush 组件“隐藏”错误与 exhaustive 检查

Angular 默认在变更检测后执行的二次校验对 ChangeDetectionStrategy.OnPush 组件并不完全有效：按需刷新后 OnPush 视图不再处于待检状态，二次校验会跳过它们，从而“掩盖”潜在的不稳定表达式（参见 packages/core/src/change_detection/provide_check_no_changes_config.ts）。为此 Angular 20 起以开发者预览形式提供 provideCheckNoChangesConfig({ exhaustive: true })，该校验会把所有挂载在 ApplicationRef 上的视图（及其子孙，ChangeDetectorRef.detach() 脱离的子树除外）都当作 Default 策略来执行二次检查，以暴露被 OnPush 隐藏的 NG0100 类问题；默认值仍是 false（见 packages/core/src/change_detection/use_exhaustive_check_no_changes.ts），且整体只在实际开发模式（ngDevMode 为真）下生效。它还支持可选的 interval 参数，用于在 zoneless 应用中周期性执行 checkNoChanges。

官方推荐的调试步骤

借助 CLI 生成的 Source Map 回溯调用栈

文档 NG0100.md 推荐的第一步是使用 CLI 生成的 Source Map 进行调试：在 DevTools 中开启 source map 后，沿调用栈向上查找，直到定位到“报错信息中显示的那个值发生变化”的模板表达式所在位置。这一步通常能立刻把问题收敛到某一个具体的绑定或插值上。

确保二次校验之后绑定不再变化

修复的核心原则（NG0100.md）：确保变更检测运行结束后，模板中的绑定不会再发生任何变化。这通常意味着需要把你的用例重构到正确的组件生命周期钩子中执行：

当前出错的钩子	官方推荐的修法
ngAfterViewInit 中设置初始值	改用 constructor 或 ngOnInit 设置初始值
涉及其他值绑定的初始化	使用 ngAfterContentInit 完成绑定所需的数据准备
触发了视图创建/更新	避免在变更检测钩子内创建视图或再次触发检测，必要时用 ChangeDetectorRef.detectChanges() 显式通知 Angular 你“知道并接受”这次更新

上述原则与源码中的 creationMode 附加提示遥相呼应——当报错附带 “Has it been created in a change detection hook?” 时，几乎可以断定是视图在钩子内被创建导致父级已完成检查后才出现新内容。

谨慎在模板中绑定方法

如果模板中绑定的是方法调用（NG0100.md），务必确认该方法的执行不会去更新模板里的其他绑定。方法是“每次渲染都会重新求值”的入口，一旦内部写入了某个也被本模板读取的字段，就构成典型的“检查完成后值又变了”。

如何在真实项目中预防与验证

结合本仓库源码可以给出三条具备可验证性的工程建议：

1. 善用 devModeEqual 之外的类型一致性：尽量让绑定数据保持稳定引用，模板插值优先使用属性/信号，而不是每次求值都新建对象的方法；
2. 显式掌握检测时机：若确实需要在视图渲染后再同步状态（例如第三方库回填、图表初始化），在该次操作后主动调用 ChangeDetectorRef.detectChanges()，向 Angular 声明“此变更在下一次检测时收敛”，而不是在 ngAfterViewInit 中直接改数据并期待无警告；
3. 开启 exhaustive 校验暴露 OnPush 掩盖的问题：按上文所述通过 provideCheckNoChangesConfig({ exhaustive: true })（开发者预览特性）在开发阶段提前发现隐患。

关于 NG0100 的更多背景还可以结合本仓库内的相关材料继续阅读：

• 组件生命周期指南（其中多处涉及 NG0100 与 ngAfterViewInit / ngOnChanges 的关系）；
• 组件查询指南（涵盖 ngAfterContentInit 等查询类钩子的正确用法）；
• 错误总览（查看 NG0100 在全部运行时错误编码体系中的位置）；
• 该错误的运行时测试用例位于 packages/core/test/acceptance/change_detection_spec.ts，可作为复现与验证行为的参考。

最后回到官方文档给出的结论（NG0100.md）：NG0100 不是框架的缺陷，而是 Angular 开发模式的保护性哨兵——它强制你在开发期就发现“数据流不收敛”的隐患，避免这些隐患在用户浏览器中演变成抖动的界面甚至死循环。学会读懂它、用 Source Map 定位它、并在正确的生命周期钩子中重构赋值逻辑，是每个 Angular 开发者必须掌握的核心调试技能。