配置文件

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

配置文件

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

eslint.config.js
eslint.config.mjs
eslint.config.cjs
eslint.config.ts（需要额外设置）
eslint.config.mts（需要额外设置）
eslint.config.cts（需要额外设置）

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

// eslint.config.js
export default [
    {
        rules: {
            semi: "error",
            "prefer-const": "error"
        }
    }
];
1
2
3
4
5
6
7
8
9

在此示例中，配置数组仅包含一个配置对象。配置对象启用了两个规则：semi 和 prefer-const。这些规则应用于 ESLint 使用此配置文件处理的所有文件。

如果您的项目在其 package.json 文件中未指定 "type":"module"，则 eslint.config.js 必须采用 CommonJS 格式，例如

// eslint.config.js
module.exports = [
    {
        rules: {
            semi: "error",
            "prefer-const": "error"
        }
    }
];
1
2
3
4
5
6
7
8
9

配置对象

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

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

指定 `files` 和 `ignores`

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

// eslint.config.js
export default [
    {
        rules: {
            semi: "error"
        }
    }
];
1
2
3
4
5
6
7
8

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

使用 `ignores` 排除文件

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

// eslint.config.js
export default [
    {
        files: ["src/**/*.js"],
        rules: {
            semi: "error"
        }
    }
];
1
2
3
4
5
6
7
8
9

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

export default [
    {
        files: ["src/**/*.js"],
        ignores: ["**/*.config.js"],
        rules: {
            semi: "error"
        }
    }
];
1
2
3
4
5
6
7
8
9

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

export default [
    {
        files: ["src/**/*.js"],
        ignores: ["**/*.config.js", "!**/eslint.config.js"],
        rules: {
            semi: "error"
        }
    }
];
1
2
3
4
5
6
7
8
9

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

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

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

export default [
    {
        ignores: ["**/*.config.js"],
        rules: {
            semi: "error"
        }
    }
];
1
2
3
4
5
6
7
8

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

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

使用任意扩展名指定文件

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

// eslint.config.js
export default [
    {
        files: [
            "**/*.ts",
            "**/*.cts",
            "**.*.mts"
        ]
    },
    // ...other config
];
1
2
3
4
5
6
7
8
9
10
11

指定没有扩展名的文件

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

// eslint.config.js
export default [
    {
        files: ["**/!(*.*)"]
    },
    // ...other config
];
1
2
3
4
5
6
7

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

使用 `ignores` 全局忽略文件

如果在配置对象中不使用其他任何键而仅使用 ignores，则这些模式将作为全局忽略规则。以下是一个示例

// eslint.config.js
export default [
    {
        ignores: [".config/*"]
    }
];
1
2
3
4
5
6

此配置指定应忽略 .config 目录中的所有文件。此模式是在默认模式之后添加的，默认模式为 ["**/node_modules/", ".git/"]。

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

级联配置对象

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

// eslint.config.js
export default [
    {
        files: ["**/*.js"],
        languageOptions: {
            globals: {
                MY_CUSTOM_GLOBAL: "readonly"
            }
        }
    },
    {
        files: ["tests/**/*.js"],
        languageOptions: {
            globals: {
                it: "readonly",
                describe: "readonly"
            }
        }
    }
];
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

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

配置代码检查器选项

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

禁用内联配置

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

// eslint.config.js
export default [
    {
        files: ["**/*.js"],
        linterOptions: {
            noInlineConfig: true
        }
    }
];
1
2
3
4
5
6
7
8
9

报告未使用的禁用指令

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

// eslint.config.js
export default [
    {
        files: ["**/*.js"],
        linterOptions: {
            reportUnusedDisableDirectives: "error"
        }
    }
];
1
2
3
4
5
6
7
8
9

此设置默认为 "warn"。

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

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

配置规则

您可以在配置对象中配置任意数量的规则，方法是添加一个 rules 属性，该属性包含一个包含规则配置的对象。此对象中的名称是规则的名称，值是每个规则的配置。以下是一个示例

// eslint.config.js
export default [
    {
        rules: {
            semi: "error"
        }
    }
];
1
2
3
4
5
6
7
8

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

// eslint.config.js
export default [
    {
        rules: {
            semi: ["error", "never"]
        }
    }
];
1
2
3
4
5
6
7
8

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

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

配置共享设置

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

// eslint.config.js
export default [
    {
        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"
        }
    }
];
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

使用预定义配置

ESLint 为 JavaScript 提供了两个预定义配置

js.configs.recommended - 启用 ESLint 建议每个人使用的规则，以避免潜在错误
js.configs.all - 启用随 ESLint 一起提供的全部规则

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

// eslint.config.js
import js from "@eslint/js";

export default [
    js.configs.recommended,
    {
        rules: {
            "no-unused-vars": "warn"
        }
    }
];
1
2
3
4
5
6
7
8
9
10
11

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

有关如何将预定义配置与您的首选项结合使用的更多信息，请参阅组合配置。

配置命名约定

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

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

例如，如果您正在为名为 eslint-plugin-example 的插件创建配置对象，则可能会使用 example/ 前缀将 name 添加到配置对象中

export default {
    configs: {
        recommended: {
            name: "example/recommended",
            rules: {
                "no-unused-vars": "warn"
            }
        },
        strict: {
            name: "example/strict",
            rules: {
                "no-unused-vars": "error"
            }
        }
    }
};
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

在公开配置对象数组时，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"
                }
            }
        ]
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

使用可共享的配置包

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

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

export default [
    exampleConfig,

    // your modifications
    {
        rules: {
            "no-unused-vars": "warn"
        }
    }
];
1
2
3
4
5
6
7
8
9
10
11
12
13

在此示例中，exampleConfig 是一个对象，因此您将其直接插入配置数组中。

一些可共享配置将导出一个数组，在这种情况下，您需要使用扩展运算符将这些项插入配置数组中。例如

// eslint.config.js
import exampleConfigs from "eslint-config-example";

export default [
    ...exampleConfigs,

    // your modifications
    {
        rules: {
            "no-unused-vars": "warn"
        }
    }
];
1
2
3
4
5
6
7
8
9
10
11
12
13

请参阅您正在使用的可共享配置包的文档，以确定它是在导出对象还是数组。

有关如何将可共享配置与您的首选项结合使用的更多信息，请参阅组合配置。

配置文件解析

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

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

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

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

实验性配置文件解析

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

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

npx eslint --flag unstable_config_lookup_from_file .
1

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

TypeScript 配置文件

您需要通过 unstable_ts_config 功能标志启用此功能

npx eslint --flag unstable_ts_config
1

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

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

npm install -D jiti
# or
yarn add --dev jiti
# or
pnpm add -D jiti
1
2
3
4
5

然后，您可以创建一个扩展名为 .ts、.mts 或 .cts 的配置文件，并导出一个配置对象数组。以下是在 ESM 格式中的示例

import js from "@eslint/js";
import type { Linter } from "eslint";

export default [
  js.configs.recommended,
  {
    rules: {
      "no-console": [0],
    },
  },
] satisfies Linter.Config[];
1
2
3
4
5
6
7
8
9
10
11

以下是在 CommonJS 格式中的示例

import type { Linter } from "eslint";
const eslint = require("@eslint/js");

const config: Linter.Config[] = [
  eslint.configs.recommended,
  {
    rules: {
      "no-console": [0],
    },
  },
];

module.exports = config;
1
2
3
4
5
6
7
8
9
10
11
12
13

配置文件优先级

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

eslint.config.js
eslint.config.mjs
eslint.config.cjs
eslint.config.ts
eslint.config.mts
eslint.config.cts

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

npx eslint --flag unstable_ts_config --config eslint.config.ts
1

编辑此页面

配置文件

配置文件

配置对象

指定 files 和 ignores

使用 ignores 排除文件

使用任意扩展名指定文件

指定没有扩展名的文件

使用 ignores 全局忽略文件

级联配置对象

配置代码检查器选项

禁用内联配置

报告未使用的禁用指令

配置规则

配置共享设置

使用预定义配置

配置命名约定

使用可共享的配置包

配置文件解析

实验性配置文件解析

TypeScript 配置文件

配置文件优先级

指定 `files` 和 `ignores`

使用 `ignores` 排除文件

使用 `ignores` 全局忽略文件