深夜十一点半我盯着终端里长长的eslint --fix输出心里有种说不出的别扭。团队刚引入一套更严格的代码规范几十个文件跑完自动修复CI 全绿看起来一切顺利。但同事 review 代码时却丢来一句这里的eslint-disable注释是怎么回事这行代码明明没有任何问题注释却在悄悄压制规则。我切回编辑器一看确实整整一个文件的报错都被一条撤下的// eslint-disable-next-line盖住了。规则没报错CI 自然放行但那行代码只是被注释“护着”真正的错误并没有消失。这就是我一直想聊的“ESLint 自覆盖忽略”——ESLint 自身的忽略机制在特定条件下把本应暴露的问题“自我掩盖”掉了。这篇文章就从我这次排查出发把“自覆盖忽略”的成因、机制、复现方式和完整排查链路拆开讲透。想彻底搞懂的人或者是团队里被一堆eslint-disable注释困扰的、正准备升级 ESLint v9/v10 的朋友都可以照着我这篇的步骤去复现一遍基本能把 ESLint 的忽略机制摸清楚。1. “自覆盖忽略”到底是什么一次真实排查中看到的怪现象很多人把eslint-disable、.eslintignore、ignores当成普通的“配置文件选项”觉得“不检查就不检查呗反正我代码是对的”。问题恰恰出在这个心态上。1.1 从“CI 全绿但代码明显有问题”说起那次我负责迁移一个老的 Vue 项目到新的 lint 规范。迁移手段很常规跑一遍eslint --fix再用脚本批量处理剩余报错。其中有个文件改动前有 23 个报错改完之后是 0 报错。我当时还挺得意直到看到 diff 才知道真相——--fix只解决了其中 9 个问题剩下 14 个全被自动追加的// eslint-disable-next-line给“屏蔽”了。这 14 条注释里有一部分确实是遗留代码我们暂时不想处理但有一部分是--fix执行时产生的次生问题——比如引号风格改了后面一行本来不违规的代码变成了违规结果被同一条忽略注释顺手压住了。更隐蔽的是第三条跑完--fix之后代码行数变了某条注释原本指向的“下一行”已经不是原来的“下一行”了。注释的“覆盖范围”发生了漂移把不应该忽略的新错误给盖住了。这个现象我称之为“自覆盖忽略”ESLint 的自动修复行为和被它自身创建的忽略注释在运行过程中形成了互相覆盖的闭环。修复产生错误注释吞掉错误CI 看到的是“没问题”。1.2 自覆盖忽略的三层含义我翻了各种官方文档ESLint 并没有“自覆盖忽略”这个专有名词所以先把我的定义摆出来。整套机制其实分三层层级机制典型表现规则级eslint-disable-line/eslint-disable-next-line单条注释压制单行/下一行的所有规则或指定规则文件级.eslintignore / flat config 的 ignores整个文件、目录被排除在检查范围外配置级reportUnusedDisableDirectives等控制“失效的忽略规则”是否上报影响忽略规则本身能否被检查“自覆盖忽略”最常见的三种表现正好对应这三层修复覆盖--fix改完代码后disable 注释跟着漂移盖住了新产生的违规。僵尸覆盖规则配置升级后旧注释对应的违规“已不存在”但注释还留在代码里。此时它不是忽略了一个错误而是留下了一块永远无法被规则检查的盲区。配置自屏蔽.eslintignore或ignores里把eslint.config.js、webpack.config.js这类文件排除掉导致“检查工具自身的文件”反而成了法外之地。无论哪一种结果都一样你得到的“没问题”是一个假阳性信号。1.3 不是所有 ignore 都有害这里必须说句公道话忽略机制是好东西是它在不破坏遗留代码的情况下让团队平滑迁移规范。// eslint-disable-next-line no-console在调试代码里出现太正常了。问题从来不在“用了忽略”而在于使用者意识不到忽略有作用域、有效期、覆盖优先级这些隐藏属性。所以本文要做的事就三个讲透 ESLint 忽略机制的底层执行逻辑。展示三种“自覆盖”最常发生的场景。给出一套能彻底挖出“被吞掉的错误”的排查链路。不夸张地说这几十行配置的代价比绝大多数 lint 规则要贵得多。2. 忽略机制的地基ESLint 两级忽略的工作逻辑在讲具体的“自覆盖”场景之前得先把地基打好。ESLint 的忽略体系可以精简成两个词行内抑制和文件级忽略。它们的执行逻辑是先后顺序而不是并列关系。2.1 行内抑制disable 注释的作用范围与优先级先来看一行经典注释// eslint-disable-next-line no-unused-vars const unused 1;这里no-unused-vars只会被这一行覆盖下一行照样报错。这条注释的作用范围只有一个“代码单位”——就是注释下面那行实际的可执行语句或声明。它有几个很容易翻车的特征不指定规则名时压制当前范围内所有规则// eslint-disable-next-line const foo 1;这条注释会把no-unused-vars、semi、quotes等所有规则全压住。一旦你只针对一个规则写了注释却因为偷懒没写规则名其它规则的报错也在同一行被静默吞掉。eslint-disable和eslint-enable成对出现形成块级范围/* eslint-disable no-eval */ eval(some string); /* eslint-enable no-eval */中间所有代码的no-eval都被覆盖直到遇到eslint-enable。如果中间有--fix插进来改动了行数这块范围会继续生效覆盖到原本不想影响的行。同一行出现多个注释时优先级按注释顺序叠加// eslint-disable-line no-unused-vars, semi const a 1;这里no-unused-vars和semi同时被忽略而不是“忽略一个、保留另一个”。ESLint 在遍历语法树时会在 report 阶段检查当前违规位置是否命中某条 disabled 注释。如果命中了这条消息直接标记为 suppressed它不会进入最终的错误列表不会影响 exit code也不会触发--fix的修复逻辑。这就是“自覆盖”能发生的第一个技术前提被抑制的消息整个生命周期都终结在注释面前。2.2 文件级忽略.eslintignore 与 flat config 的 ignores文件级忽略有两种配置载体传统.eslintignore和 flat config 里的ignores数组。.eslintignore是 ESLint 老牌机制规则简单直接每一行一条 glob 模式dist/** .eslintrc.js在 express 等老项目里经常看到这种写法逻辑清晰但它有个致命缺陷.eslintignore是自己单独的一个文件它本身不受 ESLint 检查。如果你的规则变更、新版 ESLint 对 glob 的语义发生了变化.eslintignore里写错的模式会静默失效你可能完全察觉不到。flat configESLint v9 默认v10 延续里不再推荐.eslintignore而是把忽略逻辑统一到eslint.config.js的ignoresexport default [ { ignores: [**/dist/**, **/node_modules/**], }, { files: [src/**/*.js], rules: { semi: error }, }, ];ignores数组里的模式作用域是整个配置对象。如果一个文件被ignores命中它就直接退出 lint 流程后续所有配置对象里对它的files、rules都不再生效。这里有个非常关键的差异.eslintignore的行为是“忽略这些路径完全不做任何检查”。flat config 的ignores行为是“忽略这些路径且该路径不参与任何规则匹配”。听起来差不多但在“自己检查自己”的场景下区别巨大。你完全可以在.eslintignore里写.eslintrc.js来跳过对配置文件的检查但eslint.config.js里的ignores: [eslint.config.js]会导致配置文件本身永远不被测试。ESLint 在 v9 后其实是建议“把配置文件也纳入检查范围”的但很多人还是习惯性把配置文件的自身检查排除掉。2.3 一个常被忽视的执行顺序fix 与 suppress 谁先谁后第二个技术前提是--fix和 suppress 的执行顺序。ESLint 的修复流程是这样的先跑完整树的规则检查收集所有可修复的消息再根据消息对应的 fix 函数生成补丁一次性应用。被 disable 注释抑制的消息不在列表里自然也不会被修复。所以当你写// eslint-disable-next-line semi const a 1同时开了semi规则你会发现即使运行eslint --fix这一行也不会被自动补上分号——因为这条消息已经被 suppress修复逻辑无法触达。这个特性被很多人当作“临时屏蔽某个可修复错误”的手段。但在大型迁移里它会变成灾难你屏蔽了一个错误结果--fix为了修另一个规则改动了相邻几行代码导致这条注释对应的上下文变了。注释的作用行没变但被覆盖的“错误”本身已经不是原来那个错误了。一个简单的“下一行”却能覆盖住完全不同的新问题这就是“自覆盖”的另一个具体形态。3. 最容易被“自覆盖”的三个场景所有的理论都要落到具体场景里才有价值。我整理了三个高频发生“自覆盖忽略”的场景每个都是真实踩过坑的。3.1 场景一自动修复后 disable 注释漂移这是我最常见到的一种发生过程如下团队决定引入prettier统一格式。为了兼容先在某些文件里加了// eslint-disable-next-line压制某些规则。跑eslint --fix后prettier对代码做了大量换行、缩进。原来的“下一行”发生了漂移注释覆盖到了完全不同的代码上。举个例子// eslint-disable-next-line no-console const name eslint; console.log(name);prettier --fix后变成// eslint-disable-next-line no-console const name eslint; console.log( name, );console.log(name)这一行本来没有任何问题但现在它成了“下一行”的内容之一被no-console的无心注释覆盖。原本该报的错误不见了取而代之的是一个静默的、不该被忽略的规则冲突。为什么难以发现因为你看到的还是那行代码注释还在它上面一眼望去“注释盖住了要忽略的东西”。你先入为主地认为注释是对的除非哪一天有同事删掉这条注释代码才开始报错。怎么避免迁移后务必跑--report-unused-disable-directives4.1 节会细说。这个命令能快速找出“被覆盖的行”和“注释原始意图”之间不匹配的案例。3.2 场景二旧注释变僵尸长期压制真实违规第二种更隐蔽我称之为“僵尸覆盖”。想象一下这个场景// eslint-disable-next-line eqeqeq if (a b) { /* ... */ }因为历史原因a b存在写了注释勉强过关。后来重构把a b改成了a b这条eqeqeq规则就不再被触发了。但注释还在原地。严格说这条注释已经是“未使用的 disable 指令”了。默认情况下ESLint 不会报这个因为reportUnusedDisableDirectives默认不开启。于是它就一直躺在那里像一个空房的保安。问题出在这个“空房保安”会挡后续搬进来的“新房客”// eslint-disable-next-line if (a b) { // 假如后来有人改成了 如果注释没带规则名且覆盖范围过大即使a b后来被某次事务又改回a b注释仍然会静默压制这个错误。你永远不知道这里有一个“历史错误”被旧注释守护着。更常见的情况是项目里存着几十条、上百条这样的旧注释它们就像一颗颗定时炸弹覆盖着真实的错误。当你用--fix清理时又会因为 3.1 的注释漂移把新错误带进来。3.3 场景三配置文件自我忽略这类场景在升级到 flat config 后特别常见。很多团队升级 ESLint v9 时习惯性地写成export default [ { ignores: [node_modules/**, dist/**, eslint.config.js], }, // ... ];加eslint.config.js进ignores的原因通常是为了“别让 eslint 检查它自己”怕无限递归或麻烦。但这样一来配置文件自身的语法问题、格式问题、潜在逻辑错误全都不会被发现。我记得有一次团队的eslint.config.js里写了一个错误的规则名ESLint 直接报Rule foo-bar is not defined。同事第一反应是“哪个插件没装”最后发现是配置文件里写错了但配置文件自己却被列在 ignores 里导致 ESLint 连“配置文件有问题”的提示都给不了你只能靠外面的终端输出硬看。更隐蔽的版本ignores写得太宽。一个团队把**/*.d.ts全忽略了结果某天一个关键类型文件里出现了类型错误ESLint 不报TypeScript 编译也不报因为忽略只在 ESLint 层问题直接被吞掉。4. 完整排查链路把被吞掉的错误挖出来现在进入本文最硬核的部分。如果你已经意识到项目里可能存在“自覆盖忽略”下面这套排查链路就是专门来挖真相的。4.1 第一步用--report-unused-disable-directives打开盖子这是整个排查链路里最核心的一步没有之一。在 ESLint v9 的 flat config 中在eslint.config.js里加上export default [ { linterOptions: { reportUnusedDisableDirectives: warn, }, }, ];或者在 CLI 里直接跑npx eslint . --report-unused-disable-directives这个开关打开后ESLint 除了检查代码本身还会检查每一条 disable 注释是否真的压制了至少一个报告。如果一条注释没有压制任何内容它就会被当成一个“未使用的忽略指令”报告出来。输出长这样/project/src/foo.js 1:1 warning Unused eslint-disable directive (no problems were reported from no-unused-vars) no-unused-vars看到这条警告的那一刻基本就找到了“僵尸注释”。这时你心里要清楚ESLint 官方默认不告诉你这些注释是没用的必须手动开这个开关。4.2 第二步让--fix自动清理无用注释打开reportUnusedDisableDirectives后eslint --fix还有一个隐藏福利它会自动移除这些无用的 disable 注释。继续用上面的配置然后跑npx eslint . --fix --report-unused-disable-directives注意此时 ESLint 会把“未使用的 ignore 指令”当成一个可修复的 lint 错误。修补方式是直接将注释从代码中删除。所以哪怕你不想改代码本身只清理注释这条命令也够用。我建议清理时先用--fix-dry-run看一遍会清掉哪些注释避免误删。npx eslint . --fix-dry-run --report-unused-disable-directives它会列出每个文件会产生哪些 diff但不实际写入。这个步骤相当重要因为有些注释虽然“未使用”但它是人为留下的文档。比如一段代码很怪作者用注释标明“为什么没按规则来”。这样的注释即使没有再压制错误也应保留。4.3 第三步对真实剩余错误做分类处置清理完僵尸注释后再跑一次npx eslint .这时候出来的报错才是这个代码库的“真实负债”。我习惯把它们分为三类类型处理方式备注真实违规立即修复或记入技术债往往都是隐藏了很久的真问题规范争议和团队讨论规则是否合理不要用注释掩盖争议暂时不处理的重新写一条带规则名和原因的 disable 注释不许裸注释在第三步里重新写 disable 注释时务必带上规则名和理由// eslint-disable-next-line no-unused-vars -- 暂时放着等模板功能删掉后再清 const tempHelper () {};这样即使将来代码变动注释依然能被追踪。裸的// eslint-disable-next-line在排查里是重点打击对象因为它的覆盖范围是整个下一行的所有规则。4.4 进阶配合 git diff 和--fix-dry-run做最小还原如果你是在一次大迁移中遇到问题直接全量跑--fix风险不小。我推荐一套更稳妥的组合拳记录当前 git 状态git stash只对改动文件做 dry-rungit diff --name-only HEAD | xargs npx eslint --fix-dry-run检查 dry-run 的 diff专门看-行里是不是有新增/移动的 disable 注释git diff | grep -n eslint-disable确认--fix-dry-run之后再真正执行--fix。这套流程看起来很繁琐但在几十个文件的大迁移场景下非常可靠。它能在“自动修复”和“注释漂移”之间设一道人工检查闸门避免新一轮自覆盖。5. 配置层面的防线让“自覆盖”从一开始就难发生排查链路是事后止损要想真正摆脱“自覆盖忽略”的阴影还是得从配置和团队协作层面下手。5.1 flat config 里 ignores 的优先级陷阱前面提到ignores一旦命中文件完全不参与后续规则匹配。这里有一个容易踩的优先级陷阱export default [ { files: [src/**/*.js], ignores: [src/**/*.test.js], rules: { no-console: off, }, }, { files: [src/**/*.test.js], rules: { no-console: error, }, }, ];第二个配置对象里的no-console: error作用域是src/**/*.test.js。看起来测试文件应该报 error。但第一个配置对象里的ignores: [src/**/*.test.js]已经先行排除了这些文件所以它们根本到不了第二个配置对象。ESLint 对 flat config 中同一个配置对象里的files和ignores关系是这样处理的先匹配files再应用ignores。如果ignores命中这个文件段就完全失效。不同配置对象之间早期匹配到的排除规则会阻断后续所有匹配。所以我的建议是把全局忽略node_modules、dist、生成文件放到一个单独的配置对象里并且放在最前面针对具体文件的忽略则考虑用逻辑更明确的files 反向模式而不是全局ignoresexport default [ { ignores: [**/node_modules/**, **/dist/**], }, { files: [src/**/*.js, !src/**/*.test.js], rules: { no-console: off }, }, ];!src/**/*.test.js是显式的“排除测试文件”一目了然不会被后面的配置对象忽略掉。5.2 把 reportUnusedDisableDirectives 开成 error 的实践前面说了默认不开启这个选项但如果把它开成error效果会完全不同export default [ { linterOptions: { reportUnusedDisableDirectives: error, }, }, ];这样任何一条失效的 disable 注释都会导致 ESLint 报错CI 直接失败。这个“绝情”的配置能倒逼团队成员每次代码改动时旧注释必须同步清理。新增注释前会先想清楚这个注释压制的问题是否仍然合理。大迁移时注释漂移问题当场暴露不会藏到 review 阶段。缺点是初期会有抱怨——旧项目里可能有几百条僵尸注释一次性全报 error 会刷屏。我的过渡方案是先开warn让团队知道哪些注释失效了。用--fix --report-unused-disable-directives清掉一大半。剩余真正需要保留的注释重写并带上理由。彻底清理后再把配置升为error。这个方案在好几个项目里跑下来反馈都不错。5.3 团队规则禁裸 disable、限定范围、写清原因最后聊一下团队规范。配置文件只是工具真正的长治久安还是得靠人在代码层面守住规则。我在团队里推过三条硬性约定清晰且代价低第一条禁止裸// eslint-disable和// eslint-disable-line。使eslint-disable不带任何规则名等于把当前整个作用域内所有规则全关掉。这样做对后续排查是灾难性的因为你压根不知道它原本想压制什么。我要求必须写明规则名// 错误示范 // eslint-disable-next-line // 正确示范 // eslint-disable-next-line no-console -- 为兼容旧日志工具允许使用 console第二条凡是 disable 注释必须带一个原因。原因可以是“待重构”“兼容旧浏览器”“lint 规则误报”等但必须写明。这个原因有两大作用方便后续同事评估这条注释是否还有存在必要。也防止注释背后的错误成为“历史事故现场”。第三条每次 PR 里disable 注释的数量必须可审查。我的实际操作是在 CI 脚本里跑一条统计命令npx eslint . --report-unused-disable-directives | grep eslint-disable | wc -l然后跟上次构建对比。如果数量陡然上升就去看对应的 diff。这不是为了零注释而是为了对“被静默掉的问题”始终心里有数。补一条个人经验大迁移之后别急着庆祝 CI 变绿。先跑一遍--report-unused-disable-directives把输出里的每一条 disable 注释都过一遍。绝大多数“自覆盖忽略”不会让 CI 失败它只会让错误在代码里悄悄埋伏下来。只有当你主动把盖子掀开那些被压制的问题才会真正浮出水面。如果你正在准备 ESLint v10这套 flat config 下的检查逻辑依然成立反而是趁现在把旧项目里的僵尸注释清干净升级时能省掉大半的排查时间。
ESLint 自覆盖忽略：被 disable 注释悄悄吞掉的错误
深夜十一点半我盯着终端里长长的eslint --fix输出心里有种说不出的别扭。团队刚引入一套更严格的代码规范几十个文件跑完自动修复CI 全绿看起来一切顺利。但同事 review 代码时却丢来一句这里的eslint-disable注释是怎么回事这行代码明明没有任何问题注释却在悄悄压制规则。我切回编辑器一看确实整整一个文件的报错都被一条撤下的// eslint-disable-next-line盖住了。规则没报错CI 自然放行但那行代码只是被注释“护着”真正的错误并没有消失。这就是我一直想聊的“ESLint 自覆盖忽略”——ESLint 自身的忽略机制在特定条件下把本应暴露的问题“自我掩盖”掉了。这篇文章就从我这次排查出发把“自覆盖忽略”的成因、机制、复现方式和完整排查链路拆开讲透。想彻底搞懂的人或者是团队里被一堆eslint-disable注释困扰的、正准备升级 ESLint v9/v10 的朋友都可以照着我这篇的步骤去复现一遍基本能把 ESLint 的忽略机制摸清楚。1. “自覆盖忽略”到底是什么一次真实排查中看到的怪现象很多人把eslint-disable、.eslintignore、ignores当成普通的“配置文件选项”觉得“不检查就不检查呗反正我代码是对的”。问题恰恰出在这个心态上。1.1 从“CI 全绿但代码明显有问题”说起那次我负责迁移一个老的 Vue 项目到新的 lint 规范。迁移手段很常规跑一遍eslint --fix再用脚本批量处理剩余报错。其中有个文件改动前有 23 个报错改完之后是 0 报错。我当时还挺得意直到看到 diff 才知道真相——--fix只解决了其中 9 个问题剩下 14 个全被自动追加的// eslint-disable-next-line给“屏蔽”了。这 14 条注释里有一部分确实是遗留代码我们暂时不想处理但有一部分是--fix执行时产生的次生问题——比如引号风格改了后面一行本来不违规的代码变成了违规结果被同一条忽略注释顺手压住了。更隐蔽的是第三条跑完--fix之后代码行数变了某条注释原本指向的“下一行”已经不是原来的“下一行”了。注释的“覆盖范围”发生了漂移把不应该忽略的新错误给盖住了。这个现象我称之为“自覆盖忽略”ESLint 的自动修复行为和被它自身创建的忽略注释在运行过程中形成了互相覆盖的闭环。修复产生错误注释吞掉错误CI 看到的是“没问题”。1.2 自覆盖忽略的三层含义我翻了各种官方文档ESLint 并没有“自覆盖忽略”这个专有名词所以先把我的定义摆出来。整套机制其实分三层层级机制典型表现规则级eslint-disable-line/eslint-disable-next-line单条注释压制单行/下一行的所有规则或指定规则文件级.eslintignore / flat config 的 ignores整个文件、目录被排除在检查范围外配置级reportUnusedDisableDirectives等控制“失效的忽略规则”是否上报影响忽略规则本身能否被检查“自覆盖忽略”最常见的三种表现正好对应这三层修复覆盖--fix改完代码后disable 注释跟着漂移盖住了新产生的违规。僵尸覆盖规则配置升级后旧注释对应的违规“已不存在”但注释还留在代码里。此时它不是忽略了一个错误而是留下了一块永远无法被规则检查的盲区。配置自屏蔽.eslintignore或ignores里把eslint.config.js、webpack.config.js这类文件排除掉导致“检查工具自身的文件”反而成了法外之地。无论哪一种结果都一样你得到的“没问题”是一个假阳性信号。1.3 不是所有 ignore 都有害这里必须说句公道话忽略机制是好东西是它在不破坏遗留代码的情况下让团队平滑迁移规范。// eslint-disable-next-line no-console在调试代码里出现太正常了。问题从来不在“用了忽略”而在于使用者意识不到忽略有作用域、有效期、覆盖优先级这些隐藏属性。所以本文要做的事就三个讲透 ESLint 忽略机制的底层执行逻辑。展示三种“自覆盖”最常发生的场景。给出一套能彻底挖出“被吞掉的错误”的排查链路。不夸张地说这几十行配置的代价比绝大多数 lint 规则要贵得多。2. 忽略机制的地基ESLint 两级忽略的工作逻辑在讲具体的“自覆盖”场景之前得先把地基打好。ESLint 的忽略体系可以精简成两个词行内抑制和文件级忽略。它们的执行逻辑是先后顺序而不是并列关系。2.1 行内抑制disable 注释的作用范围与优先级先来看一行经典注释// eslint-disable-next-line no-unused-vars const unused 1;这里no-unused-vars只会被这一行覆盖下一行照样报错。这条注释的作用范围只有一个“代码单位”——就是注释下面那行实际的可执行语句或声明。它有几个很容易翻车的特征不指定规则名时压制当前范围内所有规则// eslint-disable-next-line const foo 1;这条注释会把no-unused-vars、semi、quotes等所有规则全压住。一旦你只针对一个规则写了注释却因为偷懒没写规则名其它规则的报错也在同一行被静默吞掉。eslint-disable和eslint-enable成对出现形成块级范围/* eslint-disable no-eval */ eval(some string); /* eslint-enable no-eval */中间所有代码的no-eval都被覆盖直到遇到eslint-enable。如果中间有--fix插进来改动了行数这块范围会继续生效覆盖到原本不想影响的行。同一行出现多个注释时优先级按注释顺序叠加// eslint-disable-line no-unused-vars, semi const a 1;这里no-unused-vars和semi同时被忽略而不是“忽略一个、保留另一个”。ESLint 在遍历语法树时会在 report 阶段检查当前违规位置是否命中某条 disabled 注释。如果命中了这条消息直接标记为 suppressed它不会进入最终的错误列表不会影响 exit code也不会触发--fix的修复逻辑。这就是“自覆盖”能发生的第一个技术前提被抑制的消息整个生命周期都终结在注释面前。2.2 文件级忽略.eslintignore 与 flat config 的 ignores文件级忽略有两种配置载体传统.eslintignore和 flat config 里的ignores数组。.eslintignore是 ESLint 老牌机制规则简单直接每一行一条 glob 模式dist/** .eslintrc.js在 express 等老项目里经常看到这种写法逻辑清晰但它有个致命缺陷.eslintignore是自己单独的一个文件它本身不受 ESLint 检查。如果你的规则变更、新版 ESLint 对 glob 的语义发生了变化.eslintignore里写错的模式会静默失效你可能完全察觉不到。flat configESLint v9 默认v10 延续里不再推荐.eslintignore而是把忽略逻辑统一到eslint.config.js的ignoresexport default [ { ignores: [**/dist/**, **/node_modules/**], }, { files: [src/**/*.js], rules: { semi: error }, }, ];ignores数组里的模式作用域是整个配置对象。如果一个文件被ignores命中它就直接退出 lint 流程后续所有配置对象里对它的files、rules都不再生效。这里有个非常关键的差异.eslintignore的行为是“忽略这些路径完全不做任何检查”。flat config 的ignores行为是“忽略这些路径且该路径不参与任何规则匹配”。听起来差不多但在“自己检查自己”的场景下区别巨大。你完全可以在.eslintignore里写.eslintrc.js来跳过对配置文件的检查但eslint.config.js里的ignores: [eslint.config.js]会导致配置文件本身永远不被测试。ESLint 在 v9 后其实是建议“把配置文件也纳入检查范围”的但很多人还是习惯性把配置文件的自身检查排除掉。2.3 一个常被忽视的执行顺序fix 与 suppress 谁先谁后第二个技术前提是--fix和 suppress 的执行顺序。ESLint 的修复流程是这样的先跑完整树的规则检查收集所有可修复的消息再根据消息对应的 fix 函数生成补丁一次性应用。被 disable 注释抑制的消息不在列表里自然也不会被修复。所以当你写// eslint-disable-next-line semi const a 1同时开了semi规则你会发现即使运行eslint --fix这一行也不会被自动补上分号——因为这条消息已经被 suppress修复逻辑无法触达。这个特性被很多人当作“临时屏蔽某个可修复错误”的手段。但在大型迁移里它会变成灾难你屏蔽了一个错误结果--fix为了修另一个规则改动了相邻几行代码导致这条注释对应的上下文变了。注释的作用行没变但被覆盖的“错误”本身已经不是原来那个错误了。一个简单的“下一行”却能覆盖住完全不同的新问题这就是“自覆盖”的另一个具体形态。3. 最容易被“自覆盖”的三个场景所有的理论都要落到具体场景里才有价值。我整理了三个高频发生“自覆盖忽略”的场景每个都是真实踩过坑的。3.1 场景一自动修复后 disable 注释漂移这是我最常见到的一种发生过程如下团队决定引入prettier统一格式。为了兼容先在某些文件里加了// eslint-disable-next-line压制某些规则。跑eslint --fix后prettier对代码做了大量换行、缩进。原来的“下一行”发生了漂移注释覆盖到了完全不同的代码上。举个例子// eslint-disable-next-line no-console const name eslint; console.log(name);prettier --fix后变成// eslint-disable-next-line no-console const name eslint; console.log( name, );console.log(name)这一行本来没有任何问题但现在它成了“下一行”的内容之一被no-console的无心注释覆盖。原本该报的错误不见了取而代之的是一个静默的、不该被忽略的规则冲突。为什么难以发现因为你看到的还是那行代码注释还在它上面一眼望去“注释盖住了要忽略的东西”。你先入为主地认为注释是对的除非哪一天有同事删掉这条注释代码才开始报错。怎么避免迁移后务必跑--report-unused-disable-directives4.1 节会细说。这个命令能快速找出“被覆盖的行”和“注释原始意图”之间不匹配的案例。3.2 场景二旧注释变僵尸长期压制真实违规第二种更隐蔽我称之为“僵尸覆盖”。想象一下这个场景// eslint-disable-next-line eqeqeq if (a b) { /* ... */ }因为历史原因a b存在写了注释勉强过关。后来重构把a b改成了a b这条eqeqeq规则就不再被触发了。但注释还在原地。严格说这条注释已经是“未使用的 disable 指令”了。默认情况下ESLint 不会报这个因为reportUnusedDisableDirectives默认不开启。于是它就一直躺在那里像一个空房的保安。问题出在这个“空房保安”会挡后续搬进来的“新房客”// eslint-disable-next-line if (a b) { // 假如后来有人改成了 如果注释没带规则名且覆盖范围过大即使a b后来被某次事务又改回a b注释仍然会静默压制这个错误。你永远不知道这里有一个“历史错误”被旧注释守护着。更常见的情况是项目里存着几十条、上百条这样的旧注释它们就像一颗颗定时炸弹覆盖着真实的错误。当你用--fix清理时又会因为 3.1 的注释漂移把新错误带进来。3.3 场景三配置文件自我忽略这类场景在升级到 flat config 后特别常见。很多团队升级 ESLint v9 时习惯性地写成export default [ { ignores: [node_modules/**, dist/**, eslint.config.js], }, // ... ];加eslint.config.js进ignores的原因通常是为了“别让 eslint 检查它自己”怕无限递归或麻烦。但这样一来配置文件自身的语法问题、格式问题、潜在逻辑错误全都不会被发现。我记得有一次团队的eslint.config.js里写了一个错误的规则名ESLint 直接报Rule foo-bar is not defined。同事第一反应是“哪个插件没装”最后发现是配置文件里写错了但配置文件自己却被列在 ignores 里导致 ESLint 连“配置文件有问题”的提示都给不了你只能靠外面的终端输出硬看。更隐蔽的版本ignores写得太宽。一个团队把**/*.d.ts全忽略了结果某天一个关键类型文件里出现了类型错误ESLint 不报TypeScript 编译也不报因为忽略只在 ESLint 层问题直接被吞掉。4. 完整排查链路把被吞掉的错误挖出来现在进入本文最硬核的部分。如果你已经意识到项目里可能存在“自覆盖忽略”下面这套排查链路就是专门来挖真相的。4.1 第一步用--report-unused-disable-directives打开盖子这是整个排查链路里最核心的一步没有之一。在 ESLint v9 的 flat config 中在eslint.config.js里加上export default [ { linterOptions: { reportUnusedDisableDirectives: warn, }, }, ];或者在 CLI 里直接跑npx eslint . --report-unused-disable-directives这个开关打开后ESLint 除了检查代码本身还会检查每一条 disable 注释是否真的压制了至少一个报告。如果一条注释没有压制任何内容它就会被当成一个“未使用的忽略指令”报告出来。输出长这样/project/src/foo.js 1:1 warning Unused eslint-disable directive (no problems were reported from no-unused-vars) no-unused-vars看到这条警告的那一刻基本就找到了“僵尸注释”。这时你心里要清楚ESLint 官方默认不告诉你这些注释是没用的必须手动开这个开关。4.2 第二步让--fix自动清理无用注释打开reportUnusedDisableDirectives后eslint --fix还有一个隐藏福利它会自动移除这些无用的 disable 注释。继续用上面的配置然后跑npx eslint . --fix --report-unused-disable-directives注意此时 ESLint 会把“未使用的 ignore 指令”当成一个可修复的 lint 错误。修补方式是直接将注释从代码中删除。所以哪怕你不想改代码本身只清理注释这条命令也够用。我建议清理时先用--fix-dry-run看一遍会清掉哪些注释避免误删。npx eslint . --fix-dry-run --report-unused-disable-directives它会列出每个文件会产生哪些 diff但不实际写入。这个步骤相当重要因为有些注释虽然“未使用”但它是人为留下的文档。比如一段代码很怪作者用注释标明“为什么没按规则来”。这样的注释即使没有再压制错误也应保留。4.3 第三步对真实剩余错误做分类处置清理完僵尸注释后再跑一次npx eslint .这时候出来的报错才是这个代码库的“真实负债”。我习惯把它们分为三类类型处理方式备注真实违规立即修复或记入技术债往往都是隐藏了很久的真问题规范争议和团队讨论规则是否合理不要用注释掩盖争议暂时不处理的重新写一条带规则名和原因的 disable 注释不许裸注释在第三步里重新写 disable 注释时务必带上规则名和理由// eslint-disable-next-line no-unused-vars -- 暂时放着等模板功能删掉后再清 const tempHelper () {};这样即使将来代码变动注释依然能被追踪。裸的// eslint-disable-next-line在排查里是重点打击对象因为它的覆盖范围是整个下一行的所有规则。4.4 进阶配合 git diff 和--fix-dry-run做最小还原如果你是在一次大迁移中遇到问题直接全量跑--fix风险不小。我推荐一套更稳妥的组合拳记录当前 git 状态git stash只对改动文件做 dry-rungit diff --name-only HEAD | xargs npx eslint --fix-dry-run检查 dry-run 的 diff专门看-行里是不是有新增/移动的 disable 注释git diff | grep -n eslint-disable确认--fix-dry-run之后再真正执行--fix。这套流程看起来很繁琐但在几十个文件的大迁移场景下非常可靠。它能在“自动修复”和“注释漂移”之间设一道人工检查闸门避免新一轮自覆盖。5. 配置层面的防线让“自覆盖”从一开始就难发生排查链路是事后止损要想真正摆脱“自覆盖忽略”的阴影还是得从配置和团队协作层面下手。5.1 flat config 里 ignores 的优先级陷阱前面提到ignores一旦命中文件完全不参与后续规则匹配。这里有一个容易踩的优先级陷阱export default [ { files: [src/**/*.js], ignores: [src/**/*.test.js], rules: { no-console: off, }, }, { files: [src/**/*.test.js], rules: { no-console: error, }, }, ];第二个配置对象里的no-console: error作用域是src/**/*.test.js。看起来测试文件应该报 error。但第一个配置对象里的ignores: [src/**/*.test.js]已经先行排除了这些文件所以它们根本到不了第二个配置对象。ESLint 对 flat config 中同一个配置对象里的files和ignores关系是这样处理的先匹配files再应用ignores。如果ignores命中这个文件段就完全失效。不同配置对象之间早期匹配到的排除规则会阻断后续所有匹配。所以我的建议是把全局忽略node_modules、dist、生成文件放到一个单独的配置对象里并且放在最前面针对具体文件的忽略则考虑用逻辑更明确的files 反向模式而不是全局ignoresexport default [ { ignores: [**/node_modules/**, **/dist/**], }, { files: [src/**/*.js, !src/**/*.test.js], rules: { no-console: off }, }, ];!src/**/*.test.js是显式的“排除测试文件”一目了然不会被后面的配置对象忽略掉。5.2 把 reportUnusedDisableDirectives 开成 error 的实践前面说了默认不开启这个选项但如果把它开成error效果会完全不同export default [ { linterOptions: { reportUnusedDisableDirectives: error, }, }, ];这样任何一条失效的 disable 注释都会导致 ESLint 报错CI 直接失败。这个“绝情”的配置能倒逼团队成员每次代码改动时旧注释必须同步清理。新增注释前会先想清楚这个注释压制的问题是否仍然合理。大迁移时注释漂移问题当场暴露不会藏到 review 阶段。缺点是初期会有抱怨——旧项目里可能有几百条僵尸注释一次性全报 error 会刷屏。我的过渡方案是先开warn让团队知道哪些注释失效了。用--fix --report-unused-disable-directives清掉一大半。剩余真正需要保留的注释重写并带上理由。彻底清理后再把配置升为error。这个方案在好几个项目里跑下来反馈都不错。5.3 团队规则禁裸 disable、限定范围、写清原因最后聊一下团队规范。配置文件只是工具真正的长治久安还是得靠人在代码层面守住规则。我在团队里推过三条硬性约定清晰且代价低第一条禁止裸// eslint-disable和// eslint-disable-line。使eslint-disable不带任何规则名等于把当前整个作用域内所有规则全关掉。这样做对后续排查是灾难性的因为你压根不知道它原本想压制什么。我要求必须写明规则名// 错误示范 // eslint-disable-next-line // 正确示范 // eslint-disable-next-line no-console -- 为兼容旧日志工具允许使用 console第二条凡是 disable 注释必须带一个原因。原因可以是“待重构”“兼容旧浏览器”“lint 规则误报”等但必须写明。这个原因有两大作用方便后续同事评估这条注释是否还有存在必要。也防止注释背后的错误成为“历史事故现场”。第三条每次 PR 里disable 注释的数量必须可审查。我的实际操作是在 CI 脚本里跑一条统计命令npx eslint . --report-unused-disable-directives | grep eslint-disable | wc -l然后跟上次构建对比。如果数量陡然上升就去看对应的 diff。这不是为了零注释而是为了对“被静默掉的问题”始终心里有数。补一条个人经验大迁移之后别急着庆祝 CI 变绿。先跑一遍--report-unused-disable-directives把输出里的每一条 disable 注释都过一遍。绝大多数“自覆盖忽略”不会让 CI 失败它只会让错误在代码里悄悄埋伏下来。只有当你主动把盖子掀开那些被压制的问题才会真正浮出水面。如果你正在准备 ESLint v10这套 flat config 下的检查逻辑依然成立反而是趁现在把旧项目里的僵尸注释清干净升级时能省掉大半的排查时间。