配置规则

规则是 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"0 - 关闭规则

    ¥"off" or 0 - turn the rule off

  • "warn"1 - 打开规则作为警告(不影响退出代码)

    ¥"warn" or 1 - turn the rule on as a warning (doesn’t affect exit code)

  • "error"2 - 打开规则作为错误(触发时退出代码为 1)

    ¥"error" or 2 - turn the rule on as an error (exit code is 1 when triggered)

规则通常设置为 "error",以在持 Sequelize 成测试、预提交检查和拉取请求合并期间强制遵守规则,因为这样做会导致 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).

使用配置注释

¥Using configuration comments

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

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

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

在此示例中,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 */

此示例与上一个示例相同,只是它使用数字代码而不是字符串值。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 */

此注释指定 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. */
/* eslint eqeqeq: "off", curly: "error"
    --------
    Here's a description about why this configuration is necessary. */
/* eslint eqeqeq: "off", curly: "error"

 * --------

 * This will not work due to the line above starting with a '*' character.
 */

使用配置文件

¥Using 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:

export default [
    {
        rules: {
            eqeqeq: "off",
            "no-unused-vars": "error",
            "prefer-const": ["error", { "ignoreReadBeforeAssign": true }]
        }
    }
];

当多个配置对象指定相同的规则时,规则配置将与后面的对象合并,优先于任何先前的对象。例如:

¥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:

export default [
    {
        rules: {
            semi: ["error", "never"]
        }
    },
    {
        rules: {
            semi: ["warn", "always"]
        }
    }
];

使用此配置,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:

export default [
    {
        rules: {
            semi: ["error", "never"]
        }
    },
    {
        rules: {
            semi: "warn"
        }
    }
];

这里,第二个配置对象只覆盖了严重性,所以 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";

export default [
    {
        plugins: {
            example
        },
        rules: {
            "example/rule1": "warn"
        }
    }
];

在此配置文件中,规则 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" */

禁用规则

¥Disabling Rules

使用配置注释

¥Using configuration comments

  • 谨慎使用。禁用内联 ESLint 规则应受到限制,并且仅在有明确且有效理由的情况下使用。禁用内联规则不应成为解决 linting 错误的默认解决方案。

    ¥Use with Caution. Disabling ESLint rules inline should be restricted and used only in situations with a clear and valid reason for doing so. Disabling rules inline should not be the default solution to resolve linting errors.

  • 记录原因。在注释的 -- 部分后提供注释,解释禁用特定规则的原因。该文档应阐明为什么该规则被禁用以及为什么在该特定情况下有必要。

    ¥Document the Reason. Provide a comment explaining the reason for disabling a particular rule after the -- section of the comment. This documentation should clarify why the rule is being disabled and why it is necessary in that specific situation.

  • 临时解决方案。如果添加禁用注释作为解决紧迫问题的临时措施,请创建后续任务以充分解决根本问题。这可确保在稍后阶段重新访问并解决禁用注释。

    ¥Temporary Solutions. If a disable comment is added as a temporary measure to address a pressing issue, create a follow-up task to address the underlying problem adequately. This ensures that the disable comment is revisited and resolved at a later stage.

  • 代码审查和结对编程。鼓励团队成员定期审查彼此的代码。代码审查可以帮助确定禁用注释背后的原因并确保它们得到正确使用。

    ¥Code Reviews and Pair Programming. Encourage team members to review each other’s code regularly. Code reviews can help identify the reasons behind disable comments and ensure that they are used appropriately.

  • 配置。只要有可能,优先使用 ESLint 配置文件而不是禁用注释。配置文件允许一致的、项目范围的规则处理。

    ¥Configurations. Whenever possible, prefer using ESLint configuration files over disable comments. Configuration files allow for consistent and project-wide rule handling.

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

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

/* eslint-disable */

alert('foo');

/* eslint-enable */

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

¥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 */

要在整个文件中禁用规则警告,请在文件顶部添加 /* 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');

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

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

/* eslint-disable no-alert */

alert('foo');

确保永远不会应用规则(无论将来有任何启用/禁用行):

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

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

alert('foo');

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

¥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 */

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

¥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');

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

¥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');

以上所有方法也适用于插件规则。例如,要禁用 eslint-plugin-examplerule-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 */

注释描述

¥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');

使用配置文件

¥Using 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
export default [
    {
        rules: {
            "no-unused-expressions": "error"
        }
    },
    {
        files: ["*-test.js","*.spec.js"],
        rules: {
            "no-unused-expressions": "off"
        }
    }
];

禁用内联注释

¥Disabling Inline Comments

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

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

// eslint.config.js
export default [
    {
        linterOptions: {
            noInlineConfig: true
        },
        rules: {
            "no-unused-expressions": "error"
        }
    }
];

除了其他内联配置之外,你还可以使用 --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, use the reportUnusedDisableDirectives setting. For example:

// eslint.config.js
export default [
    {
        linterOptions: {
            reportUnusedDisableDirectives: "error"
        }
    }
];

此设置默认为 "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.