介绍批量抑制

在某个阶段，每个开发团队都会面临同样的挑战：你希望启用一个新的 ESLint 规则以提高代码质量，但你现有的代码库中已经存在许多违规。当该规则无法自动修复时，将其作为错误启用的过程可能会很困难。

🌐 At some point, every development team faces the same challenge: you want to enable a new ESLint rule to improve code quality, but your existing codebase already contains numerous violations. When the rule isn’t auto-fixable, the path to enabling it as an error can be challenging.

今天，我们很高兴介绍 ESLint 的新违规抑制系统，旨在使采用更严格的代码检查规则变得更加可管理。让我们来看看它是如何工作的，以及它如何帮助你的团队逐步提高代码质量。

🌐 Today, we’re excited to introduce ESLint’s new violation suppression system, designed to make adopting stricter linting rules more manageable. Let’s explore how it works and how it can help your team enhance code quality incrementally.

为什么要批量屏蔽？

🌐 Why bulk suppressions?

在已建立的项目中启用规则时，团队通常会在以下几种方式之间进行选择：立即修复所有违规、使用警告而非错误、在特定文件中禁用规则，或者添加内联禁用注释。每种方法都有其优点，但没有一种能在对新代码强制执行标准的同时，逐步处理现有违规之间提供理想的平衡。

🌐 When enabling a rule in an established project, teams typically choose between fixing all violations upfront, using warnings instead of errors, disabling rules in specific files, or adding inline disable comments. Each approach has merit, but none provides an ideal balance between enforcing standards for new code while addressing existing violations over time.

ESLint 的新抑制系统提供了一种更灵活的方法，允许你：

🌐 ESLint’s new suppression system offers a more flexible approach, allowing you to:

1. 将现有违规记录在一个可以提交到版本控制的单独文件中。
2. 将规则设置为错误。这现在只会应用于新代码。
3. 根据自己的节奏处理抑制文件中记录的现有违规情况。

这种方法优先阻止新的违规行为，同时提供了一个清晰的路径来逐步改进现有代码。

🌐 This approach prioritizes preventing new violations while providing a clear path to incrementally improve existing code.

入门

🌐 Getting started

一旦你在 ESLint 配置中将新规则配置为 "error"，你可以使用命令行批量抑制现有违规。你可以选择抑制所有违规或仅抑制特定规则的违规。

🌐 Once you’ve configured a new rule as "error" in your ESLint configuration, you can bulk suppress existing violations using the command line. You can choose to suppress all violations or only those for specific rules.

无论哪种情况，建议使用 --fix 标志运行抑制命令，以自动解决任何可以修复的违规情况。

🌐 In either case, it’s recommended to run the suppression command with the --fix flag to automatically resolve any violations that can be fixed.

# Fix all autofixable violations and suppress the remaining ones
eslint --suppress-all --fix

# Fix all autofixable violations, but suppress only violations for <rule-name>
eslint --suppress-rule <rule-name> --fix
1
2
3
4
5

当你执行上述任何命令时，ESLint 会在项目根目录下创建一个名为 eslint-suppressions.json 的文件。该文件包含每个规则和文件的违规次数。抑制文件的结构如下：

🌐 When you execute any of the above commands, ESLint will create a file called eslint-suppressions.json in the project root. This file contains the number of violations for each rule and file. The suppressions file is structured as follows:

{
  "src/file1.js": {
    "no-undef": {
        "count": 1
    }
  },
  "src/file2.js": {
    "no-unused-expressions": {
        "count": 2
    }
  }
}
1
2
3
4
5
6
7
8
9
10
11
12

ESLint将在后续运行中抑制指定规则的所有 "error" 违规行为，并且不会报告它们。然而，如果在同一文件中对同一规则发现更多违规行为，ESLint将报告所有违规行为。例如，如果一个文件最初被抑制了 2 个 no-undef 错误，但现在有 5 个，ESLint 将显示所有 5 个 no-undef 错误。

🌐 ESLint will suppress all "error" violations for the specified rules in subsequent runs and will not report them. However, if more violations are found for the same rule in the same file, ESLint will report all of them. For example, if a file originally had 2 suppressed no-undef errors but now has 5, ESLint will display all 5 no-undef errors.

这种方法是故意的，有助于避免混淆。因为抑制是按文件和规则跟踪的，而不是按具体行或代码更改跟踪，所以无法可靠地判断新的违规是最近引入的还是早已存在的。与其尝试猜测隐藏哪些违规，ESLint 选择显示完整情况。

🌐 This approach is intentional and helps avoid confusion. Because suppressions are tracked per file and rule—not per specific line or code change—there’s no reliable way to determine whether the new violations were introduced recently or already existed. Rather than trying to guess which violations to hide, ESLint chooses to show the full picture.

更改抑制文件位置

🌐 Changing the suppressions file location

默认情况下，ESLint 会在项目根目录创建名为 eslint-suppressions.json 的抑制文件。你可以使用 --suppressions-location 选项来指定抑制文件的其他位置。

🌐 By default, ESLint creates the suppressions file as eslint-suppressions.json in the project root. You can use the --suppressions-location option to specify a different location for the suppressions file.

--suppressions-location 选项接受文件的路径，该路径可以是绝对路径或相对于当前工作目录的相对路径。例如，以下命令将抑制项存储在当前工作目录中的名为 suppressions.json 的文件中：

🌐 The --suppressions-location option accepts a path to the file, which can be either absolute or relative to the current working directory. For example, the following command stores the suppressions in a file called suppressions.json in the current working directory:

eslint --suppress-all --suppressions-location ./suppressions.json
1

请注意，在运行使用抑制文件的 ESLint 命令时，必须指定 --suppressions-location 选项。例如，要使用上述示例中的抑制文件运行 ESLint：

🌐 Note that you must specify the --suppressions-location option when running ESLint commands that use the suppressions file. For example, to run ESLint with the suppressions file from the example above:

eslint --suppressions-location suppressions.json
1

随着时间管理抑制

🌐 Managing suppressions over time

启用抑制后，建议将抑制文件提交到你的代码库。这可以确保所有团队成员在运行 ESLint 时都启用了相同的抑制规则。

🌐 After enabling suppressions, it is recommended to commit the suppressions file to your repository. This ensures all team members have the same suppressions active when running ESLint.

随着你随着时间修复被抑制的违规行为，抑制文件将会变得过时。当 ESLint 发现不再发生的被抑制违规行为时，会输出警告：

🌐 As you fix suppressed violations over time, the suppressions file will become outdated. ESLint outputs a warning when it finds suppressed violations that no longer occur:

仍有一些抑制条目不再发生。考虑使用 --prune-suppressions 重新运行命令。

修剪是一个关键的维护步骤，主要因为它有助于保持抑制文件的整洁和相关性。它确保抑制文件只包含仍然存在于代码库中的违规条目。要更新抑制文件，你可以使用 --prune-suppressions 标志。这将移除代码库中已不存在的违规条目的任何条目。

🌐 Pruning is a crucial maintenance step mainly because it helps keep your suppressions file clean and relevant. It ensures that the suppressions file only contains entries for violations that still exist in your codebase. To update your suppressions file, you can use the --prune-suppressions flag. This will remove any entries for violations that no longer exist in your codebase.

结论

🌐 Conclusion

ESLint 的新抑制系统增强了你逐步采用更严格代码检查的能力。当前的实现提供了立即开始受益所需的所有功能，同时它与 ESLint 现有的架构无缝集成：

🌐 ESLint’s new suppression system enhances your ability to adopt stricter linting incrementally. The current implementation provides everything needed to start benefiting right away, while it integrates seamlessly with ESLint’s existing architecture:

• 在不使用时，它是完全透明的
• 它可以与其他功能如 --fix 和 --cache 一起使用
• 它只影响错误报告
• 被抑制的违规行为会在一个单独的属性（LintResult#suppressedMessages）中跟踪，以供可能需要此信息的工具使用

你可以通过更新到最新版本的 ESLint 来开始使用批量抑制功能。我们很想听到你在项目中采用此功能时的反馈和经验！

🌐 You can start using bulk suppressions by updating to the latest version of ESLint. We’d love to hear your feedback and experiences as you adopt this feature in your projects!