企业官网建设流程全解析

自覆盖忽略这个词，是我在排查一次 ESLint 突然什么文件都不检查、CI 却绿灯通过的诡异问题时，给这个问题起的名字。明明配置里写了覆盖规则，也写了忽略规则，ESLint 却像自己被自己绕晕了一样，该管的文件没人管，该放过的文件又静默吞掉，整个工程 lint 形同虚设。这类问题在 legacy.eslintrc和新的eslint.config.js（Flat Config）里表现形式完全不同，但根子都在于“忽略”和“覆盖”两套机制的文件模式互相叠盖。

这篇文章适合两类人看：一类是把 ESLint 当黑盒用、遇到“规则没生效”只能清缓存重启的纯使用者；另一类是维护工程规范、经常跟 monorepo 下的复杂overrides结构打交道的配置管理员。我会从机制原理讲到实际操作，再给出一套我自己踩了多次坑之后沉淀下来的配置策略，内容偏实战，尽量让你看完就能排查出自己项目里的“自覆盖忽略”问题。

1. 先弄清两个机制：忽略与覆盖

1.1 忽略：文件的黑名单机制

忽略机制在 ESLint 里的表现形态有好几种：传统的.eslintignore文件、legacy 配置里的ignorePatterns字段、Flat Config 下的ignores属性，以及命令行里的--ignore-pattern。它们本质都是同一件事：给文件系统做一次黑名单过滤，命中的文件直接不进 lint 队列。

忽略的逻辑优先级非常高，近似“一票否决”。一个文件只要被任意一条忽略规则命中，后面无论写过什么覆盖规则、什么插件、什么解析器配置，统统不会执行。这就好比小区门口的黑名单，只要你的名字出现在门卫的名单上，你就进不了小区，别说你住哪栋楼，连保安亭都过不去。

很多人对忽略机制的误区在于：以为“忽略”和“覆盖”是同级配置，可以互相修正。实际上忽略是提前拦截，覆盖是拦截之后的事情。ESLint 不会先给文件配上覆盖规则再检查它是否被忽略，而是先确认文件有没有资格被 lint，没资格就什么都不谈。

这里还要注意一个容易被忽略的细节：legacy 配置里ignorePatterns使用的是 gitignore 风格的 glob，而overrides里的files使用的是 minimatch 风格的 glob。这两种模式看起来写起来差不多，实际语义差别很大。比如dist在 gitignore 风格里会匹配任意层级的dist目录，但在 minimatch 里只匹配根目录下的dist；*.js在 gitignore 风格里可以匹配任意目录下的 js 文件，在 minimatch 里只匹配当前目录层级。这个差异是很多“配置看着对但行为诡异”问题的起点。

1.2 覆盖：给不同文件发不同的规则卡

覆盖机制对应 legacy 里的overrides字段和 Flat Config 里同时包含files的配置对象，核心作用是对不同文件集合应用不同的规则集。典型场景是：普通源码走严格的规则，测试文件放宽no-unused-expressions，配置文件单独关掉no-console，monorepo 里不同 package 使用不同规则版本。

overrides之所以强大，是因为它按文件模式动态匹配，同一份配置里的规则不再是全局统一的。你可以把它理解成一座大楼的分层管理：整栋楼有统一的门禁（全局规则），但 10 楼可以额外规定不准养大型犬，11 楼可以额外规定晚上十点后禁止洗澡。这就是覆盖的本意。

但问题也随之而来：覆盖规则里声明了files时，ESLint 会根据模式筛选候选文件。如果这些候选文件同时撞进了忽略黑名单，那覆盖规则就成了“空头支票”。反过来，如果你在覆盖规则里写了ignorePatterns（legacy）或ignores（flat），其作用范围限制在当前覆盖块内部，很多人会误以为它能反向“复活”被全局忽略的文件，于是矛盾就此滋生。

1.3 自覆盖忽略的三种典型现场

我总结下来，“自覆盖忽略”的现象基本可以归为三类，各位可以对号入座：

第一种是模式重叠。全局忽略列表里已经写了src/generated/**，覆盖规则里又给src/generated/**单独配置了no-undef关闭项。表面上看，你既忽略了这些文件又给它们开了特例，实际上忽略优先级高于覆盖，覆盖规则永远没机会执行。你在配置里写了一句“我需要管它”，又在另一处写了一句“我不管它”，ESLint 最终选择了后者，这就是配置层面的自我矛盾。

第二种是取反模式串层。你想忽略某个目录，又想放行其中个别文件，于是在.eslintignore里写了dist/**，在overrides[].ignorePatterns里写了!dist/keep.js。你本意是希望覆盖规则里的取反能抵消全局忽略，但 ESLint 处理忽略时先处理全局列表，文件在第一步就被判了死刑，后面的覆盖块根本运行不到。这就好比你在大门前被保安拦下，你在 10 楼前台说“我是业主”也没用，因为根本进不了电梯。

第三种是 Flat Config 下的交错顺序问题。在eslint.config.js里，先给所有 TS 文件开了规则，随后一个ignores把某目录拉进黑名单，之后又有一个files试图给该目录单独配规则。数组顺序和 ignore 累积的逻辑叠加在一起，导致文件永久性从 lint 队列消失，而你只是把 ignore 写在了规则对象的前面或后面，就成了完全不同的行为。

2. legacy 配置里的经典冲突：overrides 与 ignorePatterns 的相爱相杀

2.1 从 .eslintignore 到 ignorePatterns，取反模式是怎么工作的

在切换到 Flat Config 之前，绝大多数项目用的是.eslintrc+.eslintignore的组合。.eslintignore支持 gitignore 风格的语法，其中!开头的行表示取反。比如：

dist/ !dist/keep.js

这个规则列表的语义是：dist 目录下所有文件都被忽略，但dist/keep.js除外。这个取反能够成立的前提是：正反模式位于同一个忽略列表里，ESLint 会按顺序处理整份列表，允许后续的取反抵消先前的忽略。

ignorePatterns字段的作用和.eslintignore类似，但它可以直接写在.eslintrc里。顶层ignorePatterns自然成为全局忽略；overrides块里的ignorePatterns则只对当前覆盖块的候选文件做二次过滤。

这里的关键点在于：ESLint 评估“文件是否被忽略”时，全局忽略和覆盖块的本地忽略不是同一次遍历。全局列表先把文件从候选池里捞走，覆盖块连看都看不到它，更别提覆盖块里的取反模式。跨列表的取反，在 legacy 模式下基本是无效操作。

2.2 现场复现：为什么覆盖配置让忽略一夜失效

我来做一个可以直接复现的实验。假设项目里有这样的文件结构：

src/ components/ button.test.js fixtures/ button.test.js

配置文件长这样：

// .eslintrc.cjs module.exports = { ignorePatterns: ['**/fixtures/**'], overrides: [ { files: ['**/*.test.js'], ignorePatterns: ['!**/fixtures/**'], env: { node: true }, rules: { 'no-unused-expressions': 'off' }, }, ], };

我们的预期可能是：全局忽略所有 fixtures 下的文件，但覆盖块里对 test.js 文件做特殊规则，并且通过!**/fixtures/**放行 fixtures 下的测试文件。然而实际执行时：

npx eslint src/components/button.test.js src/fixtures/button.test.js

输出结果只有src/components/button.test.js被 lint，src/fixtures/button.test.js直接没有任何输出。原因很简单：ESLint 先执行了顶层ignorePatterns，**/fixtures/**已经匹配到了src/fixtures/button.test.js，这个文件在遍历阶段就被标记为 ignored。覆盖块里的取反模式根本没机会参与第二次判定。

如果你把顶层ignorePatterns去掉，只在覆盖块的ignorePatterns里写['**/fixtures/**', '!src/fixtures/button.test.js']，那这个文件反而能正常工作。也就是说，取反必须和正模式放在同一个列表里，跨列表取反是典型的无效配置。

2.3 手动计算生效链：ESLint 如何判定一个文件是否进入队列

我在 debug 这类问题时，手动整理了一套判定链，每次都能快速定位问题。可以把 ESLint 对单个文件的判定拆成下面几步：

1. 收集全局忽略源：.eslintignore文件、顶层ignorePatterns、命令行--ignore-pattern。
2. 对目标文件跑全局忽略匹配，命中则标记为 ignored，处理结束。
3. 若未被全局忽略，遍历所有overrides，判断files模式是否匹配当前文件。
4. 对匹配的覆盖块，再检查其内部ignorePatterns。覆盖块内部的忽略发生在“已确认候选”之后。
5. 未被任何忽略命中的文件，应用所有匹配到的规则，此时配置顺序才决定规则覆盖关系。

这套链的关键在于第 2 步和第 4 步是两套独立流程。全局忽略一旦命中就提前终止，覆盖块内部的取反、排除、规则统统轮不到。所以凡是遇到“我在覆盖块里写了规则，但文件没被 lint”，第一步就该检查：这个文件是否已经被全局忽略列表或.eslintignore拦截了。

有一回我看到一个项目里，开发者在.eslintignore里写死了所有.d.ts文件，又在overrides里给vite-env.d.ts单独配了no-undef关闭项，意图是让这个特殊声明文件能过检查。结果自然是规则完全不生效，因为.eslintignore的优先级太高了。与其纠结取反，不如直接在全局忽略列表里用取反语法把想保留的文件先救出来，或者干脆别忽略.d.ts，改用入口过滤的方式处理。

3. flat config 下的新坑：overrides 里的 ignores 会把全局 ignore 顶掉

3.1 flat config 的思维转变：一切皆对象，ignores 不是普通配置

ESLint 8.21 之后开始推广 Flat Config，到 9.x 成为默认，.eslintrc模式退居二线。Flat Config 把整个配置拆成一个数组，数组里的每个元素是一个配置对象，对象通过files选择文件集合，通过rules设置规则，通过ignores排除文件。

这套设计和 legacy 相比，表面上是结构简化了，实则暗含一套更严格的“顺序累积”逻辑：配置数组从前到后依次执行，ignores设置的不是一次性过滤，而是往一个全局忽略模式池里追加内容。数组后续的配置对象在匹配文件时，这个全局忽略池就已经生效了。

很多人从 legacy 迁移到 flat config 时，习惯性地认为ignores和旧版的ignorePatterns一样是局部过滤，结果把忽略配置丢在了中间某个对象里，导致前面对象配好的规则全部失效。这里要记住一个根本区别：在 flat config 中，如果一个配置对象只有ignores而没有files，它修改的就是全局忽略状态，影响范围是“从这一刻起所有后续匹配”。

3.2 复现代码：全局 ignores 生效，加了覆盖就失效

直接看一个典型事故现场。我有一次给某项目做规则收敛，目标是：所有 TS 文件关闭no-console，src/generated 目录下的生成代码关闭no-undef。看起来没什么问题，配置文件结构如下：

// eslint.config.js export default [ { files: ['**/*.ts'], rules: { 'no-console': 'off', }, }, { ignores: ['src/generated/**'], }, { files: ['src/generated/**'], rules: { 'no-undef': 'off', }, }, ];

文件树：

src/ generated/ schema.ts components/ Button.ts

当我执行：

npx eslint src

结果是什么样的？src/components/Button.ts正常拿到no-console关闭配置，没有任何报错。但src/generated/schema.ts完全不在处理范围内，既没有no-undef豁免，也没有no-console关闭。因为第二个配置对象把src/generated/**加进了全局忽略池，第三个配置对象里的files: ['src/generated/**']就像一个对着关闭的大门的请帖，写了地址但送不到。

更加隐蔽的变体是：如果你把这第二个ignores对象放到数组末尾，前面的files: ['**/*.ts']规则对象仍然会匹配到src/generated/schema.ts，但它同样不会进 lint 队列，因为文件已经被全局忽略。也就是说，ignores对象无论放哪里，只要文件命中了黑名单，所有files匹配都是空谈。

3.3 官方对 ignores 的定义：最后一个匹配生效机制

官方文档里对ignores的说明有一条很容易被忽略：flat config 中的 ignore 模式也是支持!取反的，而且取反生效的规则是“同一个配置对象内按顺序处理”。比如：

{ ignores: ['dist/**', '!dist/keep.js'], }

这样dist目录下所有文件仍会被忽略，但dist/keep.js会被保留下来。这个写法和 legacy 的.eslintignore取反类似，是推荐的用法。问题是，很多人试图跨配置对象取反：

[ { ignores: ['dist/**'] }, { ignores: ['!dist/keep.js'] }, ]

在不同版本下这种行为并不完全一致。某些版本下，后一个对象的取反可以抵消前一个对象的影响；某些版本下却不行，因为对象处理时用了不同的阶段判断。ESLint 官方对 flat config 的过滤模型强调的是“最终匹配状态”，但在具体版本实现里，跨对象取反并不总那么丝滑，所以我的建议非常明确：正模式和取反模式务必放在同一个ignores数组里，不要分散在不同配置对象中。

另外还要注意一点：在 flat config 中，--no-ignore这个 CLI 参数不再可用。过去你在 legacy 下可以通过--no-ignore强行 lint 被忽略的文件来验证，但 flat config 下此路不通。想验证一个文件是不是被忽略了，只能用 debug 模式或--print-config加调试输出，没有捷径。

4. 自查与排查：三步定位你被冤枉的文件

4.1 第一步：把 ESLint 的“决策过程”打到控制台

排查自覆盖忽略问题，最忌讳反复改配置重启 lint，那样只能靠猜。正确做法是直接让 ESLint 把内部决策过程打出来。

legacy 模式下用：

DEBUG=eslint:config-array-factory npx eslint src/fixtures/button.test.js 2>&1 | grep button.test

flat config 模式下用：

DEBUG=eslint:config-array-factory DEBUG=eslint:flat-config-array npx eslint src/generated/schema.ts 2>&1 | grep schema

debug 输出里会显示文件匹配了哪条 glob、是否进入 ignore 列表、匹配到了哪些配置对象。重点看文件名的处理日志：如果日志里出现了 “ignored” 标记，或者匹配配置对象数量为 0，那基本可以断定是被忽略机制拦截了。

我在实际操作中发现，这种方式比任何配置文件分析工具都直观，因为 debug 日志反映的是 ESLint 运行时真实的判定顺序，而不是我们脑补的逻辑顺序。遇到“规则没生效”时，先打 debug 日志，能过滤掉一半以上的假问题。

4.2 第二步：对照配置文件写“决策表”

如果不想被 debug 日志刷屏，还有更朴素的办法：手工整理一张决策表。把目标文件列出来，再把配置文件里所有影响该文件的规则对象、忽略模式、覆盖块逐一列出，按执行顺序从上往下写。

举个例子，排查src/fixtures/button.test.js的决策表可以这样：

这张表一写出来，问题根源马上就浮出水面。很多人不写表的时候觉得配置没问题，一写表就会发现，自己想要的“覆盖”在逻辑顺序上根本轮不到执行。

4.3 第三步：用等价正则在 Node 里模拟匹配

如果项目里 glob 模式特别多，写决策表会有点累。这时候可以借助minimatch包在 Node 里快速验证模式之间的包含关系。

操作步骤：安装 minimatch 后，写一个极简脚本，模拟 ESLint 的忽略流程：

const { minimatch } = require('minimatch'); const file = 'src/generated/schema.ts'; const globalIgnorePatterns = ['src/generated/**']; const overrideFiles = ['src/generated/**']; const isGloballyIgnored = globalIgnorePatterns.some((pattern) => minimatch(file, pattern) ); if (isGloballyIgnored) { console.log('文件被全局忽略，覆盖规则不会生效'); } else { const matchedByOverride = overrideFiles.some((pattern) => minimatch(file, pattern) ); console.log('文件是否命中覆盖规则：', matchedByOverride); }

这样跑一下，你立刻可以验证“全局忽略优先”的判断是否成立。虽然这是对 ESLint 内部机制的一个简化模拟，但对于定位“哪个模式击沉了这个文件”已经足够。

5. 避坑指南：一套能落地的“忽略不覆盖”配置策略

5.1 legacy 配置的稳妥写法

如果你还在维护.eslintrc项目，我的核心建议只有一条：忽略规则全部收敛到.eslintignore，overrides里不要写ignorePatterns，更不能在覆盖块里试图用取反来“复活”全局忽略的文件。

如果确实需要在覆盖块内“减掉”一部分文件，正确做法是用files的取反模式。ESLint 的overrides.files支持 negated glob，你可以这样写：

module.exports = { overrides: [ { files: ['**/*.test.js', '!**/ui/fixtures/**'], env: { node: true }, rules: { 'no-unused-expressions': 'off', }, }, ], };

这里的!**/ui/fixtures/**表示：测试文件这个集合里，排除 ui/fixtures 下的子集。这种写法不碰全局忽略逻辑，只在覆盖匹配阶段做减法，行为可靠得多。

再有就是统一 glob 风格的问题。.eslintignore里用 gitignore 风格，overrides.files里用 minimatch 风格，两处模式的写法不要盲复制。比如在.eslintignore里写dist会匹配任意层级的 dist 目录，但在overrides.files里写dist只会匹配根目录下的 dist 文件。如果两套风格混用，很容易出现“目录明明在前一份配置里被忽略得很好，复制到 files 里后完全匹配不上”的尴尬。

5.2 flat config 的推荐结构

flat config 下我的推荐结构是：全局忽略声明放在数组首部，而且只做一个事情——维护忽略模式池。所有带files的规则对象，一律不要混入ignores。

标准结构可以长这样：

// eslint.config.js export default [ { ignores: [ 'node_modules/**', 'dist/**', 'coverage/**', 'src/generated/**', '!src/generated/keep.ts', ], }, { files: ['**/*.ts'], rules: { 'no-console': 'off', }, }, { files: ['**/*.test.ts', '!**/ui/fixtures/**'], rules: { 'no-unused-expressions': 'off', }, }, ];

这里有一个细节：!src/generated/keep.ts和src/generated/**放在同一个 ignores 数组里，这样keep.ts会从忽略列表中放行，后续配置对象仍然可以给它分配规则。同理，测试文件想排除特定子集，用files的取反模式实现，比在规则对象的ignores字段里做减法要清晰得多。

5.3 一条必须刻在心里的核心原则

我把这条原则写在团队 eslint 规范的 README 第一行：忽略模式永远不要和文件选择模式共享同一套字面量。

什么意思？如果你想“忽略 src/generated 下的绝大多数文件，但给个别文件开规则”，不要既在ignores里写src/generated/**，又在files里写src/generated/**。两处模式一旦重叠，忽略对象必然提前拦截，覆盖对象必然成为摆设。

真正可维护的做法是：把忽略和覆盖的目标范围错开。要么全局范围不写死，保留特例文件的放行口子；要么干脆把生成目录从 lint 入口里排除，比如 npm script 里直接写成：

eslint src --ext .js,.ts --ignore-pattern 'src/generated/**'

脚本层入口收窄，配置文件里不加任何对应模式，这样就不会有两套机制互相冲突的问题。

5.4 场景化速查表

我把实际项目里最常见的几个场景整理成表，方便直接对着抄：

最后分享一个小技巧：如果你维护的是大型 monorepo，建议把 ignore 模式抽成一个独立模块统一导出，比如eslint-ignore-patterns.js，legacy 和 flat config 都引用同一份常量。这样即使配置结构变了，忽略列表也不会出现两处手写不一致的情况。毕竟大多数“自覆盖忽略”问题，本质都是我们自己在不同位置写了互相冲突的规则，ESLint 只是忠实执行了其中优先级更高的一条。