ESLint 批量抑制（Bulk Suppressions）：用 `eslint-suppressions.json` 渐进式启用严格规则

ESLint 批量抑制（Bulk Suppressions）：用eslint-suppressions.json渐进式启用严格规则

【免费下载链接】eslintFind and fix problems in your JavaScript code.项目地址: https://gitcode.com/GitHub_Trending/es/eslint

导读

本文围绕 ESLint 的批量抑制（Bulk Suppressions）功能展开，讲解如何在已存在大量历史违规的代码库中渐进式地启用新的"error"级别规则：先用一行命令把存量违规“存档”进eslint-suppressions.json，让新代码继续被严格约束，再按自己的节奏逐步修复旧问题并清理存档。读完本文，你将掌握--suppress-all、--suppress-rule、--prune-suppressions等 CLI 参数的完整用法、抑制文件的内部结构与匹配原理，以及如何通过 Node.js API 以编程方式应用抑制。

为什么需要批量抑制

在项目早期就开启新规则很简单；但当代码库已经成长到一定规模时，把一条新规则直接配置为"error"会立刻产生成百上千条违规，阻塞 CI、淹没团队。更麻烦的是，如果规则本身不可自动修复（无法靠--fix解决），团队就必须手工清理完所有存量违规才能启用规则——而在清理期间，新代码还可能引入更多违规，形成"永远追不上"的困境。

ESLint 的批量抑制功能正是为这一场景设计的：它允许你对一条或多条规则批量抑制现有违规。规则会对新代码继续生效，而已存在的违规不再被报告，你可以按自己的节奏逐步处理历史遗留问题。

::: important 关键限制 只有配置为"error"的规则才会被抑制。如果规则以"warn"启用，ESLint 不会抑制其违规。这一点在 抑制服务的统计逻辑 中有直接体现：countViolationsByRule()只统计severity === 2的消息（即 error 级别），warning 一律不计入抑制。 :::

用 CLI 批量抑制现有违规

在配置文件（如eslint.config.js）中把规则启用为"error"之后，执行：

eslint --fix --suppress-all

命令说明：

• --fix：先自动修复可修复的违规，避免把"本可自动修复"的问题也一并抑制掉，这是官方文档明确推荐的做法。
• --suppress-all：抑制当前所有以"error"启用的规则的全部现存违规。再次运行eslint时，这些违规将不再被报告。

如果想只抑制某一条规则，使用--suppress-rule：

eslint --fix --suppress-rule no-unused-expressions

也可以重复传入参数，一次抑制多条规则：

eslint --fix --suppress-rule no-unused-expressions --suppress-rule no-unsafe-assignment

对应的 CLI 选项定义可在 lib/options.js 中查到：--suppress-all是布尔开关（默认false），--suppress-rule是字符串数组类型，--suppressions-location是路径类型，--prune-suppressions与--pass-on-unpruned-suppressions均为布尔开关（默认false）。

抑制文件的生成、结构与提交

默认位置与文件内容

执行抑制命令后，ESLint 会在项目根目录（即执行eslint命令的目录）创建eslint-suppressions.json。该文件记录了被抑制的规则及其数量，典型结构如下（参考测试夹具 tests/fixtures/suppressions/eslint-suppressions.json）：

{ "test-file.js": { "no-undef": { "count": 3 }, "no-sparse-arrays": { "count": 2 } } }

结构为三层嵌套：

1. 文件层：相对于当前工作目录（cwd）的文件路径，统一使用 POSIX 分隔符（getRelativeFilePath()中会做path.sep到/的转换，见 lib/services/suppressions-service.js）；
2. 规则层：被抑制的规则 ID；
3. 计数层：该文件下该规则的违规数量count。

写入时使用json-stable-stringify-without-jsonify进行确定性排序序列化（见 save()），保证每次生成的文件内容稳定、diff 友好。

一定要提交该文件

eslint-suppressions.json应当提交到版本仓库，让所有开发者共享同一份抑制记录，否则其他人在本地运行时仍会看到已被抑制的违规，团队内无法形成一致基线。

自定义抑制文件位置

如果需要，可以用--suppressions-location改变抑制文件的位置。注意：这个参数不仅在执行抑制时要传，在平时运行eslint时也必须传，否则 ESLint 找不到正确的抑制文件：

eslint --suppressions-location .github/.eslint-suppressions

如果指定的路径以路径分隔符结尾或指向一个已存在的目录，ESLint 会在该目录内创建一个以当前工作目录哈希命名的文件（形如suppressions_<hashOfCWD>）；若指向普通文件则直接使用该文件。这一逻辑实现在 getCacheFile() 中，并通过prefix: "suppressions_"传入（见 lib/cli.js 与 lib/eslint/eslint.js）。如果指定了--suppressions-location但文件不存在、且当前并非抑制模式（未带--suppress-all/--suppress-rule），CLI 会直接报错退出（见 lib/cli.js）。

修复存量违规并清理抑制

未使用抑制的检测

当你修复了代码、解决了部分被抑制的违规后，再次运行eslint会注意到：命令以非零退出码结束，并提示存在"不再发生的抑制"：

> eslint There are suppressions left that do not occur anymore. Consider re-running the command with `--prune-suppressions`.

其底层逻辑在 applySuppressions()：每次 lint 时会把当前违规数与抑制计数对比——当前违规数小于等于抑制计数时消息被抑制；而小于的部分（以及那些已完全不再出现的规则）会被收集到unused集合中。默认情况下，只要存在 unused 抑制，CLI 就会输出上述错误并以退出码2结束（见 lib/cli.js），以此提醒你清理过期的抑制记录。

修剪无用抑制

用--prune-suppressions移除不再需要的抑制：

eslint --prune-suppressions

prune()的实现（见 lib/services/suppressions-service.js）会：

• 若某规则的抑制计数恰好等于未使用的违规数，则删除该规则的抑制条目；
• 若只修复了部分违规（未使用数小于计数），则把计数减去已修复的数量；
• 清空某文件下的所有规则后删除该文件条目；
• 对抑制文件中已不存在于磁盘上的文件，一并清理其抑制记录。

临时忽略未使用抑制

如果暂时不想处理提示，也不希望它影响退出码，可以加--pass-on-unpruned-suppressions：

eslint --pass-on-unpruned-suppressions

启用后，未使用的抑制既不会计入退出码，也不会再报告"未使用抑制"错误（见 lib/cli.js）。

抑制参数之间的互斥与限制

从 lib/cli.js 的校验逻辑可以看出，以下组合是禁止同时使用的（会直接报错并以退出码2结束）：

• --suppress-all与--suppress-rule不能同时使用（前者是全量抑制，后者是定向抑制，语义冲突）；
• --suppress-all与--prune-suppressions不能同时使用；
• --suppress-rule与--prune-suppressions不能同时使用；
• --suppress-all、--suppress-rule、--prune-suppressions均不能用于管道输入（piped-in code，即通过 stdin 传入代码的场景）。

CLI 的整体执行顺序也值得注意（见 lib/cli.js）：先按需执行suppress()写入新抑制 → 按需执行prune()修剪 → 最后统一调用applySuppressions()生成最终报告。也就是说，抑制文件的更新与报告输出在同一次命令中完成。

通过 Node.js API 使用抑制

除了命令行，抑制还可以在以编程方式使用 ESLint时应用（对应文档 Node.js API）。在ESLint构造函数中设置applySuppressions为true：

const eslint = new ESLint({ applySuppressions: true, });

默认情况下，ESLint 会在当前工作目录查找eslint-suppressions.json。可以通过suppressionsLocation指定自定义位置：

const eslint = new ESLint({ applySuppressions: true, suppressionsLocation: "./config/my-suppressions.json", });

这两项选项的类型定义见 lib/types/index.d.ts。构造时若启用了applySuppressions，ESLint 会实例化SuppressionsService并解析抑制文件路径（见 lib/eslint/eslint.js）；lintFiles()会在返回结果前对全部结果应用抑制（见 lib/eslint/eslint.js）。

使用lintText()时有一个关键要求：必须提供filePath选项，抑制才会生效——因为抑制是按文件路径匹配的（见 lib/eslint/eslint.js）。

::: important Node.js API 的能力边界 Node.js API只支持应用已存在的抑制。创建新抑制（对应--suppress-all、--suppress-rule）以及修剪无用抑制（对应--prune-suppressions）目前仅能通过 CLI 完成。 :::

抑制的底层匹配原理

了解SuppressionsService（lib/services/suppressions-service.js）的实现，有助于预判边界行为：

• 按文件 + 规则 + 计数三重匹配：applySuppressions()对每个 lint 结果，先按规则统计 error 数量，再与抑制文件中的count对比。只有"当前违规数 ≤ 抑制计数"时才会把消息移入LintResult#suppressedMessages并计入suppressions: [{ kind: "file", justification: "" }]（见 suppressMessagesByRule()）。一旦新违规数超过计数，该文件该规则的全部违规都会重新照常报告——这意味着抑制不是"一刀切豁免"，而是带数量的额度。
• 只统计 error：如开头所述，warning（severity === 1）不参与抑制统计。
• 文件不存在按空处理：load()在遇到ENOENT（抑制文件尚未创建）时返回空对象而不是报错（见 lib/services/suppressions-service.js）；只有 JSON 解析失败才会抛出异常。
• 统计字段同步重算：消息被抑制后，会通过calculateStatsPerFile()重算errorCount等统计字段，保证报告数字与抑制后的消息一致（见 lib/services/suppressions-service.js）。

这些行为都有对应的单元测试覆盖，参见 tests/lib/services/suppressions-service.js。

推荐工作流：渐进式启用新规则

结合以上全部机制，推荐的落地流程为：

1. 评估：在eslint.config.js中将新规则配置为"error"，本地先跑一次确认违规规模；
2. 抑制：执行eslint --fix --suppress-all（或针对少量规则用eslint --fix --suppress-rule <rule1> --suppress-rule <rule2>），一次性"存档"存量违规；
3. 提交：把生成的eslint-suppressions.json提交进仓库，CI 与团队成员即可共享同一基线；
4. 持续守护：此后新代码若再违反这些规则会立刻被报告（超过计数即失效），存量违规被抑制但记录在案；
5. 逐步清理：按文件或按规则修复旧违规，定期执行eslint --prune-suppressions修剪过期记录；若某阶段暂不方便清理，可用--pass-on-unpruned-suppressions临时放行，但不建议长期使用，以免抑制文件与实际违规脱节；
6. 收尾：当某规则的抑制条目全部清零（文件里不再出现该规则）后，即可确认该规则在存量代码中已完全合规。

关于上述 CLI 参数更完整的定义（参数类型、默认值、示例），可进一步查阅 Command Line Interface 文档。对于以纯函数形式调用 ESLint 的集成场景，请结合 Node.js API 文档 使用applySuppressions选项，并牢记其"只读应用、不创建不修剪"的能力边界。

【免费下载链接】eslintFind and fix problems in your JavaScript code.项目地址: https://gitcode.com/GitHub_Trending/es/eslint