版本

配置文件

您可以将 ESLint 项目配置放在配置文件中。您可以包含内置规则、您希望如何强制执行它们、带有自定义规则的插件、可共享配置、您希望规则应用于哪些文件等等。

配置文件

ESLint 配置文件可以命名为以下任何一个

它应该放在项目的根目录下，并导出一个 配置对象 数组。这是一个例子

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

export default defineConfig([
    {
        rules: {
            semi: "error",
            "prefer-const": "error"
        }
    }
]);

在这个例子中，使用了 defineConfig() 辅助函数来定义一个只有一个配置对象的配置数组。配置对象启用了两个规则：semi 和 prefer-const。这些规则应用于 ESLint 使用此配置文件处理的所有文件。

如果您的项目在它的 package.json 文件中没有指定 "type":"module"，那么 eslint.config.js 必须是 CommonJS 格式，例如

// eslint.config.js
const { defineConfig } = require("eslint/config");

module.exports = defineConfig([
    {
        rules: {
            semi: "error",
            "prefer-const": "error"
        }
    }
]);

配置对象

每个配置对象都包含 ESLint 在一组文件上执行所需的所有信息。每个配置对象都由以下属性组成

  • name - 配置对象的名称。这用于错误消息和配置检查器中，以帮助识别正在使用哪个配置对象。（命名约定）
  • files - 指示配置对象应应用于的文件的 glob 模式数组。如果未指定，则配置对象将应用于任何其他配置对象匹配的所有文件。
  • ignores - 指示配置对象不应应用于的文件的 glob 模式数组。如果未指定，则配置对象将应用于 files 匹配的所有文件。如果 ignores 在配置对象中没有使用任何其他键，则这些模式充当 全局忽略，并且它将应用于每个配置对象。
  • languageOptions - 包含与如何为 linting 配置 JavaScript 相关的设置的对象。
    • ecmaVersion - 要支持的 ECMAScript 版本。可以是任何年份（即，2022）或版本（即，5）。设置为 "latest" 以获取最新的受支持版本。（默认值："latest"）
    • sourceType - JavaScript 源代码的类型。可能的值为 "script"（用于传统脚本文件），"module"（用于 ECMAScript 模块 (ESM)）和 "commonjs"（用于 CommonJS 文件）。（默认值：.js 和 .mjs 文件的 "module"；.cjs 文件的 "commonjs"）
    • globals - 一个对象，指定在 linting 期间应添加到全局作用域的其他对象。
    • parser - 一个对象，包含 parse() 方法或 parseForESLint() 方法。（默认值：espree）
    • parserOptions - 一个对象，指定直接传递给解析器上的 parse() 或 parseForESLint() 方法的其他选项。可用选项取决于解析器。
  • linterOptions - 一个对象，包含与 linting 过程相关的设置。
    • noInlineConfig - 一个布尔值，指示是否允许内联配置。
    • reportUnusedDisableDirectives - 一个严重性字符串，指示是否以及如何跟踪和报告未使用的禁用和启用指令。为了向后兼容，true 等同于 "warn"，false 等同于 "off"。（默认值："warn"）。
    • reportUnusedInlineConfigs - 一个严重性字符串，指示是否以及如何跟踪和报告未使用的内联配置。（默认值："off"）
  • processor - 一个对象，包含 preprocess() 和 postprocess() 方法，或者一个字符串，指示插件内处理器的名称（即，"pluginName/processorName"）。
  • plugins - 一个对象，包含插件名称到插件对象的名称-值映射。当指定 files 时，这些插件仅对匹配的文件可用。
  • rules - 一个对象，包含已配置的规则。当指定 files 或 ignores 时，这些规则配置仅对匹配的文件可用。
  • settings - 一个对象，包含应提供给所有规则的信息的名称-值对。

指定 files 和 ignores

您可以使用 files 和 ignores 的组合来确定配置对象应应用于哪些文件以及不应应用于哪些文件。默认情况下，ESLint lint 符合模式 **/*.js、**/*.cjs 和 **/*.mjs 的文件。除非您使用 全局忽略 显式排除它们，否则这些文件始终匹配。由于未指定 files 或 ignores 的配置对象应用于任何其他配置对象已匹配的所有文件，因此它们将应用于所有 JavaScript 文件。例如

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

export default defineConfig([
    {
        rules: {
            semi: "error"
        }
    }
]);

使用此配置，semi 规则对 ESLint 中所有匹配默认文件的文件启用。因此，如果您将 example.js 传递给 ESLint，则会应用 semi 规则。如果您传递一个非 JavaScript 文件，例如 example.txt，则不会应用 semi 规则，因为没有其他配置对象与该文件名匹配。（ESLint 输出一条错误消息，告知您由于缺少配置而忽略了该文件。）

使用 ignores 排除文件

您可以通过指定 files 和 ignores 模式的组合来限制配置对象应用于哪些文件。例如，您可能希望某些规则仅应用于 src 目录中的文件

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

export default defineConfig([
    {
        files: ["src/**/*.js"],
        rules: {
            semi: "error"
        }
    }
]);

在这里，只有 src 目录中的 JavaScript 文件应用了 semi 规则。如果您在另一个目录中的文件上运行 ESLint，则会跳过此配置对象。通过添加 ignores，您还可以从该配置对象中删除 src 中的某些文件

import { defineConfig } from "eslint/config";

export default defineConfig([
    {
        files: ["src/**/*.js"],
        ignores: ["**/*.config.js"],
        rules: {
            semi: "error"
        }
    }
]);

此配置对象匹配 src 目录中的所有 JavaScript 文件，但以 .config.js 结尾的文件除外。您还可以在 ignores 中使用否定模式来排除忽略模式中的文件，例如

import { defineConfig } from "eslint/config";

export default defineConfig([
    {
        files: ["src/**/*.js"],
        ignores: ["**/*.config.js", "!**/eslint.config.js"],
        rules: {
            semi: "error"
        }
    }
]);

在这里，配置对象排除以 .config.js 结尾的文件，但 eslint.config.js 除外。该文件仍然应用了 semi。

非全局 ignores 模式只能匹配文件名。像 "dir-to-exclude/" 这样的模式不会忽略任何内容。要忽略特定目录中的所有内容，应使用像 "dir-to-exclude/**" 这样的模式。

如果 ignores 在没有 files 的情况下使用，并且有其他键（例如 rules），则配置对象将应用于除 ignores 排除的文件之外的所有 linted 文件，例如

import { defineConfig } from "eslint/config";

export default defineConfig([
    {
        ignores: ["**/*.config.js"],
        rules: {
            semi: "error"
        }
    }
]);

此配置对象应用于所有 JavaScript 文件，但以 .config.js 结尾的文件除外。实际上，这就像将 files 设置为 **/*。通常，如果您指定 ignores，最好始终包含 files。

请注意，当未指定 files 时，否定的 ignores 模式不会导致任何匹配的文件自动被 linted。ESLint 仅 lint 默认情况下匹配或由不是 * 且不以 /* 或 /** 结尾的 files 模式匹配的文件。

指定具有任意扩展名的文件

要 lint 扩展名不是默认 .js、.cjs 和 .mjs 的文件，请使用 "**/*.extension" 格式的模式将它们包含在 files 中。任何模式都有效，除非它是 * 或以 /* 或 /** 结尾。例如，要 lint 扩展名为 .ts、.cts 和 .mts 的 TypeScript 文件，您将指定如下配置对象

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

export default defineConfig([
    {
        files: [
            "**/*.ts",
            "**/*.cts",
            "**.*.mts"
        ]
    },
    // ...other config
]);

指定没有扩展名的文件

可以使用模式 !(*.*) 匹配没有扩展名的文件。例如

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

export default defineConfig([
    {
        files: ["**/!(*.*)"]
    },
    // ...other config
]);

上面的配置 lint 所有目录中除了默认 .js、.cjs 和 .mjs 扩展名之外的没有扩展名的文件。

使用 ignores 全局忽略文件

根据 ignores 属性的使用方式，它可以表现为非全局 ignores 或全局 ignores。

  • 当 ignores 在配置对象中没有使用任何其他键（除了 name）时，这些模式充当全局忽略。这意味着它们应用于每个配置对象（不仅应用于定义它的配置对象）。全局 ignores 允许您不必在多个配置对象中复制和保持 ignores 属性同步。
  • 如果 ignores 与同一配置对象中的其他属性一起使用，则这些模式充当非全局忽略。这样，ignores 仅应用于定义它的配置对象。

全局和非全局 ignores 有一些使用差异

  • 非全局 ignores 中的模式仅匹配文件（dir/filename.js）或目录中的文件（dir/**）
  • 全局 ignores 中的模式除了非全局忽略支持的模式外，还可以匹配目录（dir/）。

对于 ignores 的所有用法

  • 您定义的模式在默认 ESLint 模式（即 ["**/node_modules/", ".git/"]）之后添加。
  • 模式始终匹配以点开头的文件和目录，例如 .foo.js 或 .fixtures，除非这些文件被显式忽略。默认情况下忽略的唯一点目录是 .git。
// eslint.config.js
import { defineConfig } from "eslint/config";

// Example of global ignores
export default defineConfig([
    {
      ignores: [".config/", "dist/", "tsconfig.json"] // acts as global ignores, due to the absence of other properties
    },
    { ... }, // ... other configuration object, inherit global ignores
    { ... }, // ... other configuration object inherit global ignores
]);

// Example of non-global ignores
export default defineConfig([
    {
      ignores: [".config/**", "dir1/script1.js"],
      rules: { ... } // the presence of this property dictates non-global ignores
    },
    {
      ignores: ["other-dir/**", "dist/script2.js"],
      rules: { ... } // the presence of this property dictates non-global ignores
    },
]);

为避免混淆，请使用 globalIgnores() 辅助函数来清楚地指示哪些忽略旨在成为全局的。这是重写的先前示例，以使用 globalIgnores()

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

// Example of global ignores
export default defineConfig([
    globalIgnores([".config/", "dist/", "tsconfig.json"]),
    { ... }, // ... other configuration object, inherit global ignores
    { ... }, // ... other configuration object inherit global ignores
]);

// Example of non-global ignores
export default defineConfig([
    {
      ignores: [".config/**", "dir1/script1.js"],
      rules: { ... } // the presence of this property dictates non-global ignores
    },
    {
      ignores: ["other-dir/**", "dist/script2.js"],
      rules: { ... } // the presence of this property dictates non-global ignores
    },
]);

有关配置关于 ignores 的规则的更多信息和示例，请参阅 忽略文件。

级联配置对象

当多个配置对象匹配给定的文件名时，配置对象将被合并，并且当存在冲突时，后面的对象将覆盖先前的对象。例如

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

export default defineConfig([
    {
        files: ["**/*.js"],
        languageOptions: {
            globals: {
                MY_CUSTOM_GLOBAL: "readonly"
            }
        }
    },
    {
        files: ["tests/**/*.js"],
        languageOptions: {
            globals: {
                it: "readonly",
                describe: "readonly"
            }
        }
    }
]);

使用此配置，所有 JavaScript 文件都定义了一个名为 MY_CUSTOM_GLOBAL 的自定义全局对象，而 tests 目录中的那些 JavaScript 文件除了 MY_CUSTOM_GLOBAL 之外，还将 it 和 describe 定义为全局对象。对于 tests 目录中的任何 JavaScript 文件，都将应用这两个配置对象，因此 languageOptions.globals 将合并以创建最终结果。

配置 Linter 选项

可以使用 linterOptions 对象配置特定于 linting 过程的选项。这些会影响 linting 的进行方式，并且不会影响如何解释文件的源代码。

禁用内联配置

内联配置是使用 /*eslint*/ 注释实现的，例如 /*eslint semi: error*/。您可以通过将 noInlineConfig 设置为 true 来禁止内联配置。启用后，所有内联配置都将被忽略。这是一个例子

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

export default defineConfig([
    {
        files: ["**/*.js"],
        linterOptions: {
            noInlineConfig: true
        }
    }
]);

报告未使用的禁用指令

禁用和启用指令，例如 /*eslint-disable*/、/*eslint-enable*/ 和 /*eslint-disable-next-line*/，用于禁用代码某些部分周围的 ESLint 规则。随着代码的更改，这些指令可能不再需要，因为代码已更改为不再触发该规则的方式。您可以通过将 reportUnusedDisableDirectives 选项设置为严重性字符串来启用报告这些未使用的禁用指令，如本例所示

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

export default defineConfig([
    {
        files: ["**/*.js"],
        linterOptions: {
            reportUnusedDisableDirectives: "error"
        }
    }
]);

此设置默认为 "warn"。

您可以使用 --report-unused-disable-directives 或 --report-unused-disable-directives-severity 命令行选项覆盖此设置。

为了向后兼容，true 等同于 "warn"，false 等同于 "off"。

报告未使用的内联配置

内联配置注释，例如 /* eslint rule-name: "error" */，用于更改代码某些部分周围的 ESLint 规则严重性和/或选项。随着项目的 ESLint 配置文件更改，这些指令可能不再与已设置的内容不同。您可以通过将 reportUnusedInlineConfigs 选项设置为严重性字符串来启用报告这些未使用的内联配置注释，如本例所示

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

export default defineConfig([
    {
        files: ["**/*.js"],
        linterOptions: {
            reportUnusedInlineConfigs: "error"
        }
    }
]);

您可以使用 --report-unused-inline-configs 命令行选项覆盖此设置。

配置规则

您可以通过添加包含带有规则配置的对象的 rules 属性，在配置对象中配置任意数量的规则。此对象中的名称是规则的名称，值是每个规则的配置。这是一个例子

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

export default defineConfig([
    {
        rules: {
            semi: "error"
        }
    }
]);

此配置对象指定应启用 semi 规则，严重性为 "error"。您还可以通过指定一个数组来为规则提供选项，其中第一个项目是严重性，之后每个项目都是规则的选项。例如，您可以通过传递 "never" 作为选项来将 semi 规则切换为不允许分号

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

export default defineConfig([
    {
        rules: {
            semi: ["error", "never"]
        }
    }
]);

每个规则都指定了自己的选项，并且可以是任何有效的 JSON 数据类型。请查看您要配置的规则的文档，以获取有关其可用选项的更多信息。

有关配置规则的更多信息，请参阅 配置规则。

配置共享设置

ESLint 支持将共享设置添加到配置文件中。当您向配置对象添加 settings 对象时，它将提供给每个规则。按照约定，插件命名它们感兴趣的设置，以避免与其他插件发生冲突。插件可以使用 settings 来指定应在其所有规则之间共享的信息。如果您要添加自定义规则并希望它们能够访问相同的信息，这可能很有用。这是一个例子

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

export default defineConfig([
    {
        settings: {
            sharedData: "Hello"
        },
        plugins: {
            customPlugin: {
                rules: {
                    "my-rule": {
                        meta: {
                            // custom rule's meta information
                        },
                        create(context) {
                            const sharedData = context.settings.sharedData;
                            return {
                                // code
                            };
                        }
                    }
                }
            }
        },
        rules: {
            "customPlugin/my-rule": "error"
        }
    }
]);

扩展配置

配置对象使用 extends 来继承另一个配置对象或数组的所有特征（包括规则、插件和语言选项），然后可以修改所有选项。extends 键是一个值数组，指示要从哪些配置扩展。extends 数组的元素可以是以下三个值之一

  • 一个字符串，指定插件中配置的名称
  • 一个配置对象
  • 一个配置数组

使用来自插件的配置

ESLint 插件可以导出预定义的配置。这些配置使用字符串引用，并遵循模式 pluginName/configName。必须首先在 plugins 键中指定插件。这是一个例子

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

export default defineConfig([
    {
        plugins: {
            example: examplePlugin
        },
        extends: ["example/recommended"]
    }
]);

在这个例子中，加载了来自 eslint-plugin-example 的名为 recommended 的配置。插件配置也可以在配置数组内按名称引用。

您还可以直接将插件配置插入到 extends 数组中。例如

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

export default defineConfig([
    {
        plugins: {
            example: pluginExample
        },
        extends: [pluginExample.configs.recommended]
    }
]);

在这种情况下，可以通过插件对象的 configs 属性直接访问来自 eslint-plugin-example 的名为 recommended 的配置。

使用预定义配置

ESLint 有两个 JavaScript 预定义配置

  • js/recommended - 启用 ESLint 建议每个人使用的规则，以避免潜在的错误。
  • js/all - 启用 ESLint 附带的所有规则。不建议在生产环境中使用此配置，因为它会随着 ESLint 的每个次要版本和主要版本而更改。使用风险自负。

要包含这些预定义的配置，请安装 @eslint/js 包，然后对后续配置对象中的其他属性进行任何修改

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

export default defineConfig([
    {
        plugins: {
            js
        },
        extends: ["js/recommended"],
        rules: {
            "no-unused-vars": "warn"
        }
    }
]);

在这里，首先应用 js/recommended 预定义配置，然后另一个配置对象为 no-unused-vars 添加所需的配置。

有关如何将预定义配置与您的偏好相结合的更多信息，请参阅 合并配置。

使用可共享配置包

可共享配置是一个 npm 包，它导出一个配置对象或数组。此包应作为依赖项安装在您的项目中，然后从您的 eslint.config.js 文件内部引用。例如，要使用名为 eslint-config-example 的可共享配置，您的配置文件将如下所示

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

export default defineConfig([
    {
        extends: [exampleConfig],
        rules: {
            "no-unused-vars": "warn"
        }
    }
]);

在这个例子中，exampleConfig 可以是对象或数组，无论哪种方式，它都可以直接插入到 extends 数组中。

有关如何将可共享配置与您的偏好相结合的更多信息，请参阅 合并配置。

配置命名约定

name 属性是可选的，但建议为每个配置对象提供一个名称，尤其是在您创建共享配置时。该名称用于错误消息和配置检查器中，以帮助识别正在使用哪个配置对象。

该名称应描述配置对象的用途，并使用 / 作为分隔符，使用配置名称或插件名称进行作用域限定。ESLint 不强制名称在运行时是唯一的，但建议设置唯一名称以避免混淆。

例如，如果您正在为名为 eslint-plugin-example 的插件创建配置对象，您可以将 name 添加到带有 example/ 前缀的配置对象

export default {
    configs: {
        recommended: {
            name: "example/recommended",
            rules: {
                "no-unused-vars": "warn"
            }
        },
        strict: {
            name: "example/strict",
            rules: {
                "no-unused-vars": "error"
            }
        }
    }
};

当公开配置对象数组时，name 可能具有额外的作用域级别，以帮助识别配置对象。例如

export default {
    configs: {
        strict: [
            {
                name: "example/strict/language-setup",
                languageOptions: {
                    ecmaVersion: 2024
                }
            },
            {
                name: "example/strict/sub-config",
                file: ["src/**/*.js"],
                rules: {
                    "no-unused-vars": "error"
                }
            }
        ]
    }
}

配置文件解析

当 ESLint 在命令行上运行时，它首先检查当前工作目录中是否存在 eslint.config.js。如果找到该文件，则搜索停止，否则它会检查 eslint.config.mjs。如果找到该文件，则搜索停止，否则它会检查 eslint.config.cjs。如果未找到任何文件，它将检查父目录中的每个文件。此搜索将继续，直到找到配置文件或到达根目录。

您可以使用命令行上的 -c 或 --config 选项来指定备用配置文件，从而阻止搜索 eslint.config.js，例如

npm

npx eslint --config some-other-file.js **/*.js

yarn

yarn dlx eslint --config some-other-file.js **/*.js

pnpm

pnpm dlx eslint --config some-other-file.js **/*.js

bun

bunx eslint --config some-other-file.js **/*.js

在这种情况下，ESLint 不会搜索 eslint.config.js，而是使用 some-other-file.js。

实验性配置文件解析

您可以使用 unstable_config_lookup_from_file 标志来更改 ESLint 搜索配置文件的方式。ESLint 将首先从正在 linting 的文件的目录开始搜索配置文件，然后向上搜索其祖先目录，直到找到 eslint.config.js 文件（或任何其他扩展名的配置文件），而不是从当前工作目录开始搜索。此行为更适合 monorepos，其中每个子目录可能都有自己的配置文件。

要在命令行上使用此功能，请使用 --flag 标志

npx eslint --flag unstable_config_lookup_from_file .

有关使用功能标志的更多信息，请参阅 功能标志。

TypeScript 配置文件

对于 Deno 和 Bun，原生支持 TypeScript 配置文件；对于 Node.js，您必须在您的项目中安装可选的开发依赖项 jiti，版本为 2.0.0 或更高版本（此依赖项不会由 ESLint 自动安装）

npm

npm install --save-dev jiti

yarn

yarn add --dev jiti

pnpm

pnpm add --save-dev jiti

bun

bun add --dev jiti

然后，您可以创建一个扩展名为 .ts、.mts 或 .cts 的配置文件，并导出一个 配置对象 数组。

配置文件优先级

如果您有多个 ESLint 配置文件，ESLint 会优先考虑 JavaScript 文件而不是 TypeScript 文件。优先级顺序如下

  1. eslint.config.js
  2. eslint.config.mjs
  3. eslint.config.cjs
  4. eslint.config.ts
  5. eslint.config.mts
  6. eslint.config.cts

要覆盖此行为，请使用 --config 或 -c 命令行选项来指定不同的配置文件

npm

npx eslint --config eslint.config.ts

yarn

yarn dlx eslint --config eslint.config.ts

pnpm

pnpm dlx eslint --config eslint.config.ts

bun

bunx eslint --config eslint.config.ts
编辑此页
© OpenJS Foundation 和 ESLint 贡献者，www.openjsf.org。内容根据 MIT 许可证 获得许可。
更改语言