企业官网建设流程全解析

ESLint 规则配置完全指南：severity、内联注释、配置文件与禁用策略

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

规则（Rules）是 ESLint 的核心构建块。本文基于 ESLint 官方文档 docs/src/use/configure/rules.md，结合仓库源码（lib/linter/、lib/config/、lib/shared/）深入讲解如何在 flat config 体系下配置规则：包括三种严重级别的语义与用法、两种配置途径（配置注释与配置文件）、规则选项的传递与合并规则、插件规则的前缀语法，以及一套完整的规则禁用方案（行内禁用、文件级禁用、配置级禁用）和配套的内联配置管理设置。读完本文，你将能熟练地按团队规范精确控制每一条规则的开关、级别与作用范围。

规则：ESLint 的核心构建块

ESLint 中的每一条规则都是一段独立的校验逻辑：它检查你的代码是否满足某项预期，并在不满足时报告问题（problem），部分规则还附带修复（fix）能力。规则可以携带针对该规则专用的配置选项，例如引号风格、缩进宽度等。

• ESLint 内置了大量规则，完整清单见 docs/src/rules/，例如eqeqeq、curly、quotes、no-alert、semi、prefer-const等；
• 也可以通过插件（plugin）引入更多规则；
• 你可以通过**配置注释（configuration comments）或配置文件（configuration files）**两种方式修改项目使用的规则。

从源码看，内置规则在 lib/rules/index.js 中统一注册，并被包装进一个LazyLoadingRuleMap（见 lib/rules/utils/lazy-loading-rule-map.js）：每条规则在首次被访问时才执行require加载，未启用的规则不会占用加载开销，这正是内置规则众多却仍能保持启动速度的原因。

规则严重级别（Rule Severity）

每条规则都有三种可选严重级别，ESLint 支持字符串与数字两种等价写法：

在源码中，severity 的归一化逻辑集中在 lib/shared/severity.js：normalizeSeverityToString与normalizeSeverityToNumber会把0/"0"/"off"、1/"1"/"warn"、2/"2"/"error"互相转换，遇到非法值直接抛出Invalid severity value错误。也就是说，无论你写"error"还是2，最终都会被统一成同一种内部表示。

何时用"error"？规则通常设置为"error"，以在持续集成（CI）测试、pre-commit 检查和 PR 合并流程中强制约束合规性——因为一旦规则被触发，ESLint 会以非零退出码退出，从而阻断流水线。

何时用"warn"？当你暂时不想强制合规、但仍希望 ESLint 报告违规时：

• 引入一条新规则，计划未来升级为"error"（先以 warn 观察影响面）；
• 规则报告的问题并非潜在的构建期/运行期错误（例如未使用的变量）；
• 规则无法 100% 确定问题真实存在（存在误报可能，需要人工复核）。

通过配置注释配置规则

配置注释（configuration comments）允许在单个文件内部直接覆盖规则配置。格式如下：

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

上面的注释把eqeqeq关闭、把curly设为错误。同样可以使用数字等价写法：

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

如果规则带有额外选项，使用数组字面量语法。数组第一项永远是严重级别（数字或字符串），后续项是该规则的选项：

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

该注释为quotes规则指定了"double"选项。

从实现看，内联配置的解析与合并发生在 lib/linter/linter.js 的sourceCode.applyInlineConfig?.()流程中：assertIsRuleSeverity会先校验第一项是否为合法 severity；如果某个规则已在配置文件里配置过、而内联注释只写了 severity（数组只有一项），ESLint 会保留配置文件中的选项、仅覆盖严重级别（注释里明确写着"use severity from the inline config and options from the provided config"）。此外，同一规则被多个配置注释重复配置时，后面的配置会被忽略并报错。

配置注释的描述（Descriptions）

配置注释可以附带说明文字，解释这条注释为什么必要。描述必须出现在配置之后，且与配置之间用两个或以上连续的-字符分隔：

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

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

如果某条内联配置注释实际上没有改变任何既有配置（即"白写了"），可以通过linterOptions.reportUnusedInlineConfigs设置将其报告出来。默认值为"off"：

// eslint.config.js import { defineConfig } from "eslint/config"; export default defineConfig([ { linterOptions: { reportUnusedInlineConfigs: "error", }, }, ]);

该设置与 CLI 选项--report-unused-inline-configs（见 docs/src/use/command-line-interface.md）行为类似。在源码中，lib/linter/linter.js 会对reportUnusedInlineConfigs做缺省归一化，随后在检查每个内联配置注释时判断其是否真正改变了配置。

::: tip 如果你希望围绕配置注释强制推行最佳实践，社区有专门的eslint-plugin-eslint-comments插件可以检查禁用注释的使用情况。 :::

通过配置文件配置规则

在配置文件（详见 docs/src/use/configure/configuration-files.md）中使用rules键，配合错误级别和所需选项：

// eslint.config.js import { defineConfig } from "eslint/config"; export default defineConfig([ { rules: { eqeqeq: "off", "no-unused-vars": "error", "prefer-const": ["error", { ignoreReadBeforeAssign: true }], }, }, ]);

多个配置对象的合并规则

当多个配置对象对同一条规则都做了配置时，规则配置会被合并，后面的对象优先于前面的对象：

import { defineConfig } from "eslint/config"; export default defineConfig([ { rules: { semi: ["error", "never"], }, }, { rules: { semi: ["warn", "always"], }, }, ]);

最终semi的配置是["warn", "always"]——因为它排在数组最后。数组第一项是严重级别，其余是选项。

如果只想改严重级别、保留前面的选项，只写字符串或数字即可：

import { defineConfig } from "eslint/config"; export default defineConfig([ { rules: { semi: ["error", "never"], }, }, { rules: { semi: "warn", }, }, ]);

此时第二个对象只覆盖了 severity，因此semi的最终配置是["warn", "never"]。

从源码看，规则配置的规范化发生在 lib/config/config.js 的normalizeRulesConfig：每条规则配置会被转成数组形态，并使用deepMergeArrays（见 lib/shared/deep-merge-arrays.js）合并选项数组；随后 validateRulesConfig 会逐条校验规则 ID 是否存在、severity 是否合法、选项是否通过规则自身的 schema 校验，并检查规则与当前语言的兼容性。

::: important优先级说明：通过配置注释设置的规则拥有最高优先级，会在所有配置文件设置应用之后才被应用。也就是说，文件内注释可以覆盖配置文件中任何对象的规则设置（除非被noInlineConfig关闭，见下文）。 :::

插件中的规则

插件定义的规则需要使用插件命名空间/规则名的前缀格式来引用。在配置文件中：

// eslint.config.js import example from "eslint-plugin-example"; import { defineConfig } from "eslint/config"; export default defineConfig([ { plugins: { example, }, rules: { "example/rule1": "warn", }, }, ]);

这里example/rule1来自名为eslint-plugin-example的插件（导入名example即命名空间）。同样的格式也适用于配置注释：

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

:::important 要在配置注释中使用插件规则，你的配置文件必须先加载该插件并把它放进plugins对象。配置注释本身无法加载插件。 :::

从实现看，插件规则的解析在 lib/config/config.js：getRuleFromConfig先判断规则名是否包含/，若包含则从config.plugins[pluginName].rules[ruleName]中查找插件规则，否则回退到内置规则表（lib/rules/index.js）查找核心规则。

禁用规则

禁用规则时请遵守以下最佳实践：

• 谨慎使用：行内禁用只应在有明确、正当理由的少数场景使用，不应成为解决 lint 错误的默认手段；
• 记录原因：在--分隔符之后写注释，说明为什么禁用该规则、为什么在此处必要；
• 临时方案：如果禁用注释是临时应急，请创建后续任务来根治底层问题，确保注释会被 revisit 并解决；
• 代码评审：鼓励团队成员互相 review 代码，通过评审识别禁用注释背后的原因，确保其使用恰当；
• 优先配置文件：尽可能用 ESLint 配置文件代替禁用注释，配置文件的规则处理更一致、范围更可控（项目级）。

使用配置注释禁用

禁用文件某一部分的所有规则——用块注释包裹：

/* eslint-disable */ alert("foo"); /* eslint-enable */

只禁用/启用特定规则：

/* eslint-disable no-alert, no-console */ alert("foo"); console.log("bar"); /* eslint-enable no-alert, no-console */

::: warning/* eslint-enable */如果不带任何规则列表，会把所有被禁用的规则重新启用。因此"先禁一批规则、又只想放开其中部分"的场景，必须显式列出规则名。 :::

禁用整个文件的规则——把/* eslint-disable */放在文件顶部：

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

也可以对整个文件禁用特定规则：

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

确保某条规则永远不会被应用（无视未来任何 enable/disable 行）——用"off"显式配置：

/* eslint no-alert: "off" */ alert("foo");

禁用某一行上的所有规则：

alert("foo"); // eslint-disable-line // eslint-disable-next-line alert("foo"); /* eslint-disable-next-line */ alert("foo"); alert("foo"); /* eslint-disable-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");

禁用某一行上的多个规则：

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");

插件规则同样适用上述所有写法——把插件名和规则名组合成插件名/规则名即可：

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

::: tip 禁用某段代码的警告，只是让 ESLint不报告这些代码的违规；ESLint 仍会解析整个文件，因此被禁用的代码依然必须是语法合法的 JavaScript。 :::

禁用注释的描述

禁用/启用注释同样支持--描述语法，解释为什么需要禁用或重新启用：

// 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");

源码层面的禁用机制

禁用指令的解析与过滤由 lib/linter/apply-disable-directives.js 负责：它会把eslint-disable、eslint-enable、eslint-disable-line、eslint-disable-next-line四类指令（type字段）连同规则 ID 列表收集成 directive，再根据指令位置与报告问题的位置做匹配过滤。值得注意的是（[lib/linter/apply-disable-directives.js#L217-L323]），eslint-disable与eslint-enable的配对是反向追踪的：从后往前扫描，只有当后面的eslint-enable确实"解除"了某个eslint-disable时，才会被标记为已使用，这为"报告未使用禁用指令"提供了依据。

使用配置文件禁用

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

// 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", }, }, ]);

这个例子中，no-unused-expressions对普通文件是错误级别，但对所有*-test.js与*.spec.js测试文件被关闭——正是"优先用配置文件做项目级规则管理"的典型落地方式。

禁用所有内联配置注释（noInlineConfig）

如果想彻底禁止文件内的所有内联配置注释，在配置文件中使用linterOptions.noInlineConfig：

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

也可以使用 CLI 选项--no-inline-config（见 docs/src/use/command-line-interface.md）来禁用规则注释及其他内联配置。

在源码中，noInlineConfig的处理位于 lib/linter/linter.js#L354-L403：当linterOptions.noInlineConfig === true时，allowInlineConfig会被置为 false，内联配置不再生效；如果配置中还带有warnInlineConfig信息，ESLint 会针对每个被忽略的内联配置节点输出形如'...' has no effect because you have 'noInlineConfig' setting in ...的警告（lib/linter/linter.js#L1056-L1069）。这些linterOptions字段的 schema 定义见 lib/config/flat-config-schema.js#L559-L583。

报告未使用的eslint-disable注释

如果某条eslint-disable注释并没有实际压制任何问题（即"这行根本没有违规，禁用是多余的"），可以用linterOptions.reportUnusedDisableDirectives报告出来。该设置默认值为"warn"：

// eslint.config.js import { defineConfig } from "eslint/config"; export default defineConfig([ { linterOptions: { reportUnusedDisableDirectives: "error", }, }, ]);

它类似于 CLI 选项--report-unused-disable-directives和--report-unused-disable-directives-severity（见 docs/src/use/command-line-interface.md）。

实现细节上，lib/linter/linter.js#L360-L403 会把它从布尔值归一化为"off"/"warn"/"error"字符串（布尔true归一化为"warn"）；真正生成"未使用"报告的逻辑在 lib/linter/apply-disable-directives.js#L379-L430：当某条eslint-disable（或eslint-enable）指令没有被任何问题匹配到时，会产生Unused eslint-disable directive (no problems were reported from ...)这样的消息，其严重级别由该设置决定（"warn"映射为 1，"error"映射为 2），并且这类问题带有可自动修复（fix）的能力——ESLint 可以安全地删除多余的禁用指令，帮助你逐步清理历史遗留的冗余注释。

小结

规则的配置是 ESLint 日常使用的核心操作，本文覆盖了从"选规则、定级别"到"精细化禁用"的完整链路：

1. 严重级别："off"/0、"warn"/1、"error"/2三种级别，"error"用于 CI/预提交/PR 强制门槛，"warn"用于渐进式引入或低置信度规则；
2. 两种配置途径：配置注释（/* eslint ... */，文件内局部生效、优先级最高）与配置文件（rules键，项目级管理、可配合files按文件组差异化配置；多个配置对象按顺序合并、后者优先，只写 severity 可保留前者的选项）；
3. 插件规则：使用插件名/规则名前缀，且必须先加载插件；
4. 禁用体系：eslint-disable/enable、eslint-disable-line、eslint-disable-next-line覆盖区块、整文件、单行、多规则与插件规则场景，并支持--描述；
5. 内联配置治理：noInlineConfig彻底关闭内联注释，reportUnusedInlineConfigs与reportUnusedDisableDirectives让冗余的内联配置和禁用指令可被发现、可被清理。

推荐的做法是：规则的整体开关与级别放在配置文件里统一管理，内联注释只用于少数有充分理由的例外，并配合reportUnusedDisableDirectives定期清理——这样既能保持代码库的整洁，也能让 ESLint 真正成为团队代码质量的可执行规范。

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