配置规则

规则是 ESLint 的核心构建块。规则用于验证你的代码是否符合某种期望，以及如果不符合该期望应当做什么。规则还可以包含该规则特定的额外配置选项。

🌐 Rules are the core building block of ESLint. A rule validates if your code meets a certain expectation, and what to do if it does not meet that expectation. Rules can also contain additional configuration options specific to that rule.

ESLint 附带大量的内置规则，你可以通过插件添加更多规则。你可以通过配置注释或配置文件修改项目使用的规则。

🌐 ESLint comes with a large number of built-in rules and you can add more rules through plugins. You can modify which rules your project uses with either configuration comments or configuration files.

规则严重性

🌐 Rule Severities

要更改规则的严重性，请将规则 ID 设置为以下值之一：

🌐 To change a rule’s severity, set the rule ID equal to one of these values:

• "off" or 0 - 关闭规则。
• "warn" or 1 - 将规则作为警告打开（不影响退出代码）。
• "error" or 2 - 将规则作为错误打开（触发时退出代码为 1）。

规则通常设置为 "error"，以在持续集成测试、预提交检查和拉取请求合并期间强制遵守规则，因为这样会导致 ESLint 以非零退出代码退出。

🌐 Rules are typically set to "error" to enforce compliance with the rule during continuous integration testing, pre-commit checks, and pull request merging because doing so causes ESLint to exit with a non-zero exit code.

如果你不想强制执行某条规则，但仍希望 ESLint 报告该规则的违规情况，请将严重性设置为 "warn"。这通常在引入一条将来最终会设置为 "error" 的新规则时使用，或者当规则标记的是构建时或运行时错误以外的问题（例如未使用的变量），又或者当规则不能确定问题是否确实存在时（当规则可能存在误报并需要人工审核时）。

🌐 If you don’t want to enforce compliance with a rule but would still like ESLint to report the rule’s violations, set the severity to "warn". This is typically used when introducing a new rule that will eventually be set to "error", when a rule is flagging something other than a potential buildtime or runtime error (such as an unused variable), or when a rule cannot determine with certainty that a problem has been found (when a rule might have false positives and need manual review).

使用配置注释

🌐 Use configuration comments

要使用配置注释在文件内配置规则，请使用以下格式的注释：

🌐 To configure rules inside of a file using configuration comments, use a comment in the following format:

/* eslint eqeqeq: "off", curly: "error" */
1

在此示例中，eqeqeq 被关闭，而 curly 被作为错误打开。你也可以使用规则严重性的数字等效值：

🌐 In this example, eqeqeq is turned off and curly is turned on as an error. You can also use the numeric equivalent for the rule severity:

/* eslint eqeqeq: 0, curly: 2 */
1

这个例子与上一个例子相同，只是它使用数字代码而不是字符串值。eqeqeq 规则已关闭，curly 规则设置为错误。

🌐 This example is the same as the last example, only it uses the numeric codes instead of the string values. The eqeqeq rule is off and the curly rule is set to be an error.

如果规则有其他选项，你可以使用数组字面语法指定它们，例如：

🌐 If a rule has additional options, you can specify them using array literal syntax, such as:

/* eslint quotes: ["error", "double"], curly: 2 */
1

此评论为 quotes 规则指定了 "double" 选项。数组中的第一个项总是规则的严重性（数字或字符串）。

🌐 This comment specifies the "double" option for the quotes rule. The first item in the array is always the rule severity (number or string).

配置注释描述

🌐 Configuration Comment Descriptions

配置注释可以包含说明，用于解释为什么该注释是必要的。说明必须出现在配置之后，并且与配置之间用两个或更多连续的 - 字符分隔。例如：

🌐 Configuration comments can include descriptions to explain why the comment is necessary. The description must occur after the configuration and is separated from the configuration by two or more consecutive - characters. For example:

/* eslint eqeqeq: "off", curly: "error" -- Here's a description about why this configuration is necessary. */
1

/* eslint eqeqeq: "off", curly: "error"
    --------
    Here's a description about why this configuration is necessary. */
1
2
3

/* eslint eqeqeq: "off", curly: "error"
 * --------
 * This will not work due to the line above starting with a '*' character.
 */
1
2
3
4

报告未使用的 eslint 内联配置注释

🌐 Report unused eslint inline config comments

要报告未使用的 eslint 内联配置注释（那些没有改变已配置内容的注释），请使用 reportUnusedInlineConfigs 设置。例如：

🌐 To report unused eslint inline config comments (those that don’t change anything from what was already configured), use the reportUnusedInlineConfigs setting. For example:

// eslint.config.js
import { defineConfig } from "eslint/config";

export default defineConfig([
	{
		linterOptions: {
			reportUnusedInlineConfigs: "error",
		},
	},
]);
1
2
3
4
5
6
7
8
9
10

此设置默认值为 "off"。

🌐 This setting defaults to "off".

此设置类似于 --report-unused-inline-configs 命令行选项。

🌐 This setting is similar to the --report-unused-inline-configs CLI option.

使用配置文件

🌐 Use Configuration Files

要在配置文件中配置规则，请使用 rules 键以及错误级别和你想要使用的任何选项。例如：

🌐 To configure rules inside of a configuration file, use the rules key along with an error level and any options you want to use. For example:

// eslint.config.js
import { defineConfig } from "eslint/config";

export default defineConfig([
	{
		rules: {
			eqeqeq: "off",
			"no-unused-vars": "error",
			"prefer-const": ["error", { ignoreReadBeforeAssign: true }],
		},
	},
]);
1
2
3
4
5
6
7
8
9
10
11
12

当多个配置对象指定相同的规则时，规则配置会被合并，后面的对象优先于之前的对象。例如：

🌐 When more than one configuration object specifies the same rule, the rule configuration is merged with the later object taking precedence over any previous objects. For example:

import { defineConfig } from "eslint/config";

export default defineConfig([
	{
		rules: {
			semi: ["error", "never"],
		},
	},
	{
		rules: {
			semi: ["warn", "always"],
		},
	},
]);
1
2
3
4
5
6
7
8
9
10
11
12
13
14

使用此配置，semi 的最终规则配置为 ["warn", "always"]，因为它在数组中最后出现。该数组表示配置的是严重性等级及任何选项。你可以只通过定义字符串或数字来更改严重性，如本例所示：

🌐 Using this configuration, the final rule configuration for semi is ["warn", "always"] because it appears last in the array. The array indicates that the configuration is for the severity and any options. You can change just the severity by defining only a string or number, as in this example:

import { defineConfig } from "eslint/config";

export default defineConfig([
	{
		rules: {
			semi: ["error", "never"],
		},
	},
	{
		rules: {
			semi: "warn",
		},
	},
]);
1
2
3
4
5
6
7
8
9
10
11
12
13
14

在这里，第二个配置对象只覆盖了严重性，因此 semi 的最终配置是 ["warn", "never"]。

🌐 Here, the second configuration object only overrides the severity, so the final configuration for semi is ["warn", "never"].

来自插件的规则

🌐 Rules from Plugins

要配置插件中定义的规则，请在规则 ID 前加上插件命名空间和 /。

🌐 To configure a rule that is defined within a plugin, prefix the rule ID with the plugin namespace and /.

例如，在一个配置文件中：

🌐 In a configuration file, for example:

// eslint.config.js
import example from "eslint-plugin-example";
import { defineConfig } from "eslint/config";

export default defineConfig([
	{
		plugins: {
			example,
		},
		rules: {
			"example/rule1": "warn",
		},
	},
]);
1
2
3
4
5
6
7
8
9
10
11
12
13
14

在这个配置文件中，规则 example/rule1 来自名为 eslint-plugin-example 的插件。

🌐 In this configuration file, the rule example/rule1 comes from the plugin named eslint-plugin-example.

你还可以将此格式与配置注释一起使用，例如：

🌐 You can also use this format with configuration comments, such as:

/* eslint "example/rule1": "error" */
1

禁用规则

🌐 Disable Rules

使用配置注释

🌐 Use configuration comments

• 谨慎使用。 应仅在有明确且合理的理由时，限制性地在行内禁用 ESLint 规则。将行内禁用规则作为解决 lint 错误的默认方案是不应当的。
• 记录原因。 在注释的 -- 部分之后提供一个解释禁用特定规则原因的评论。该文档应说明为什么要禁用该规则以及为什么在特定情况下这是必要的。
• 临时解决方案。 如果禁用注释作为临时措施被添加以解决紧迫问题，请创建后续任务以充分解决根本问题。这确保禁用注释会在后期被重新评估和解决。
• 代码审查与结对编程。 鼓励团队成员定期审查彼此的代码。代码审查可以帮助识别禁用注释背后的原因，并确保它们被适当地使用。
• 配置。 尽可能优先使用 ESLint 配置文件，而不是禁用注释。配置文件允许进行一致且全项目范围的规则管理。

要在文件的一部分中禁用规则警告，请使用以下格式的块注释：

🌐 To disable rule warnings in a part of a file, use block comments in the following format:

/* eslint-disable */

alert("foo");

/* eslint-enable */
1
2
3
4
5

你还可以禁用或启用特定规则的警告：

🌐 You can also disable or enable warnings for specific rules:

/* eslint-disable no-alert, no-console */

alert("foo");
console.log("bar");

/* eslint-enable no-alert, no-console */
1
2
3
4
5
6

要在整个文件中禁用规则警告，请在文件顶部添加一个 /* eslint-disable */ 块注释：

🌐 To disable rule warnings in an entire file, put a /* eslint-disable */ block comment at the top of the file:

/* eslint-disable */

alert("foo");
1
2
3

你还可以禁用或启用整个文件的特定规则：

🌐 You can also disable or enable specific rules for an entire file:

/* eslint-disable no-alert */

alert("foo");
1
2
3

确保永远不会应用规则（无论将来有任何启用/禁用行）：

🌐 To ensure that a rule is never applied (regardless of any future enable/disable lines):

/* eslint no-alert: "off" */

alert("foo");
1
2
3

要禁用特定行上的所有规则，请使用以下格式之一的行或块注释：

🌐 To disable all rules on a specific line, use a line or block comment in one of the following formats:

alert("foo"); // eslint-disable-line

// eslint-disable-next-line
alert("foo");

/* eslint-disable-next-line */
alert("foo");

alert("foo"); /* eslint-disable-line */
1
2
3
4
5
6
7
8
9

要禁用特定行上的特定规则：

🌐 To disable a specific rule on a specific line:

alert("foo"); // eslint-disable-line no-alert

// eslint-disable-next-line no-alert
alert("foo");

alert("foo"); /* eslint-disable-line no-alert */

/* eslint-disable-next-line no-alert */
alert("foo");
1
2
3
4
5
6
7
8
9

要禁用特定行上的多个规则：

🌐 To disable multiple rules on a specific line:

alert("foo"); // eslint-disable-line no-alert, quotes, semi

// eslint-disable-next-line no-alert, quotes, semi
alert("foo");

alert("foo"); /* eslint-disable-line no-alert, quotes, semi */

/* eslint-disable-next-line no-alert, quotes, semi */
alert("foo");

/* eslint-disable-next-line
  no-alert,
  quotes,
  semi
*/
alert("foo");
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

上述所有方法也适用于插件规则。例如，要禁用 eslint-plugin-example 的 rule-name 规则，将插件名称 (example) 和规则名称 (rule-name) 组合成 example/rule-name：

🌐 All of the above methods also work for plugin rules. For example, to disable eslint-plugin-example’s rule-name rule, combine the plugin’s name (example) and the rule’s name (rule-name) into example/rule-name:

foo(); // eslint-disable-line example/rule-name
foo(); /* eslint-disable-line example/rule-name */
1
2

注释描述

🌐 Comment descriptions

配置注释可以包括描述，以解释为什么有必要禁用或重新启用规则。描述必须在配置之后，并且需要使用两个或更多连续的 - 字符与配置分隔。例如：

🌐 Configuration comments can include descriptions to explain why disabling or re-enabling the rule is necessary. The description must come after the configuration and needs to be separated from the configuration by two or more consecutive - characters. For example:

// eslint-disable-next-line no-console -- Here's a description about why this configuration is necessary.
console.log("hello");

/* eslint-disable-next-line no-console --
 * Here's a very long description about why this configuration is necessary
 * along with some additional information
 **/
console.log("hello");
1
2
3
4
5
6
7
8

使用配置文件

🌐 Use configuration files

要在配置文件中禁用一组文件的规则，请使用带有 files 键的后续配置对象。例如：

🌐 To disable rules inside of a configuration file for a group of files, use a subsequent config object with a files key. For example:

// eslint.config.js
import { defineConfig } from "eslint/config";

export default defineConfig([
	{
		rules: {
			"no-unused-expressions": "error",
		},
	},
	{
		files: ["*-test.js", "*.spec.js"],
		rules: {
			"no-unused-expressions": "off",
		},
	},
]);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

禁用行内评论

🌐 Disable Inline Comments

要禁用所有内联配置注释，请在配置文件中使用 noInlineConfig 设置。例如：

🌐 To disable all inline config comments, use the noInlineConfig setting in your configuration file. For example:

// eslint.config.js
import { defineConfig } from "eslint/config";

export default defineConfig([
	{
		linterOptions: {
			noInlineConfig: true,
		},
		rules: {
			"no-unused-expressions": "error",
		},
	},
]);
1
2
3
4
5
6
7
8
9
10
11
12
13

除了其他内联配置外，你还可以使用 --no-inline-config CLI 选项来禁用规则注释。

🌐 You can also use the --no-inline-config CLI option to disable rule comments, in addition to other in-line configuration.

报告未使用的 eslint-disable 注释

🌐 Report unused eslint-disable comments

要报告未使用的 eslint-disable 注释（那些禁用规则但实际上不会在被禁用的行上报告的注释），请使用 reportUnusedDisableDirectives 设置。例如：

🌐 To report unused eslint-disable comments (those that disable rules which would not report on the disabled line), use the reportUnusedDisableDirectives setting. For example:

// eslint.config.js
import { defineConfig } from "eslint/config";

export default defineConfig([
	{
		linterOptions: {
			reportUnusedDisableDirectives: "error",
		},
	},
]);
1
2
3
4
5
6
7
8
9
10

此设置默认值为 "warn"。

🌐 This setting defaults to "warn".

此设置类似于 --report-unused-disable-directives 和 --report-unused-disable-directives-severity CLI 选项。

🌐 This setting is similar to --report-unused-disable-directives and --report-unused-disable-directives-severity CLI options.