# 配置文件（新）

警告：这是一个实验性的功能。要选择加入，请将 eslint.config.js 文件放在项目的根目录中或将 ESLINT_USE_FLAT_CONFIG 环境变量设置为 true。要选择退出，即使存在 eslint.config.js 文件，请将环境变量设置为 false。如果您使用API，您可以通过使用FlatESLint类、FlatRuleTester类或在Linter类中设置configType: "flat"来使用本页描述的配置系统。

# 配置文件

ESLint 配置文件名为 eslint.config.js，应该放在你项目的根目录下，并导出一个配置对象数组。这是一个例子：

export default [
    {
        rules: {
            semi: "error",
            "prefer-const": "error"
        }
    }
]

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

# 配置对象

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

files - 一组 glob 模式，指示配置对象应应用于的文件。如果未指定，则配置对象适用于所有文件。
ignores - 一组 glob 模式，指示配置对象不应应用于的文件。如果未指定，则配置对象适用于 files 匹配的所有文件。
languageOptions - 一个对象，包含与如何配置 JavaScript 进行 linting 相关的设置。
- ecmaVersion - 要支持的 ECMAScript 版本。可以是任何年份（即 2022）或版本（即 5）。对于最新支持的版本，设置为 "latest"。（默认："latest"）
- sourceType - JavaScript 源代码的类型。可能的值是 "script" 用于传统脚本文件，"module" 用于 ECMAScript 模块 (ESM) 和 "commonjs" 用于 CommonJS 文件。（默认："module" 表示 .js 和 .mjs 文件；"commonjs" 表示 .cjs 文件）
- globals - 指定在 linting 期间应添加到全局范围的其他对象的对象。
- parser - 包含 parse() 方法的对象或指示插件内部解析器名称的字符串（即 "pluginName/parserName"）。（默认："@/espree"）
- parserOptions - 一个指定附加选项的对象，这些选项直接传递给解析器上的 parser() 方法。可用选项取决于解析器。
linterOptions - 包含与 linting 过程相关的设置的对象。
- noInlineConfig - 一个布尔值，指示是否允许内联配置。
- reportUnusedDisableDirectives - 一个布尔值，指示是否应跟踪和报告未使用的禁用指令。
processor - 包含 preprocess() 和 postprocess() 方法的对象或指示插件内部处理器名称的字符串（即 "pluginName/processorName"）。
plugins - 一个包含插件名称到插件对象的名称-值映射的对象。指定 files 时，这些插件仅对匹配的文件可用。
rules - 包含已配置规则的对象。当指定 files 或 ignores 时，这些规则配置只对匹配的文件可用。
settings - 一个对象，包含所有规则都应该使用的名称-值对信息。

# 指定 files 和 ignores

提示： files 和 ignores 中指定的模式使用 minimatch 语法，并相对于 eslint.config.js 文件的位置进行评估。

您可以使用 files 和 ignores 的组合来确定哪些文件应该应用配置对象，哪些不应该。默认情况下，ESLint 匹配 **/*.js、**/*.cjs 和 **/*.mjs。因为未指定 files 或 ignores 的配置对象适用于已被任何其他配置对象匹配的所有文件，所以默认情况下配置对象将适用于传递给 ESLint 的任何 JavaScript 文件。例如：

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

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

# 使用 ignores 排除文件

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

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

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

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

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

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

此处，配置对象不包括以 .config.js 结尾的文件，但 eslint.config.js 除外。该文件仍将应用 semi。

如果在没有 files 和任何其他设置的情况下使用 ignores，则配置对象适用于除 ignores 中指定的文件之外的所有文件，例如：

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

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

# 使用 ignores 全局地忽略文件

如果 ignores 在配置对象中没有任何其他键的情况下使用，则模式充当全局忽略。这是一个例子：

export default [
    {
        ignores: [".config/*"]
    }
];

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

# 级联配置对象

当多个配置对象与给定文件名匹配时，配置对象将与在发生冲突时覆盖先前对象的后续对象合并。例如：

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

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

# 配置检查器选项

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

# 禁用内联配置

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

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

# 报告未使用的禁用指令

Disable 指令（例如 /*eslint-disable*/ 和 /*eslint-disable-next-line*/）用于禁用围绕某些代码部分的 ESLint 规则。随着代码的更改，可能不再需要这些指令，因为代码已更改为不再触发规则。您可以通过将 reportUnusedDisableDirectives 选项设置为 true 来启用对这些未使用的禁用指令的报告，如下例所示：

export default [
    {
        files: ["**/*.js"],
        linterOptions: {
            reportUnusedDisableDirectives: true
        }
    }
];

默认情况下，未使用的禁用指令报告为警告。您可以使用 --report-unused-disable-directives 命令行选项更改此设置。

# 配置语言选项

可以使用 languageOptions 对象配置特定于 ESLint 如何评估 JavaScript 代码的选项。

# 配置 JavaScript 版本

要配置 ESLint 用于评估 JavaScript 的 JavaScript (ECMAScript) 版本，请使用 ecmaVersion 属性。该属性确定哪些全局变量和语法在您的代码中有效，可以设置为版本号（例如 6）、年份号（例如 2022）或 "latest"（对于 ESLint 支持的最新版本）。默认情况下，ecmaVersion 设置为 "latest"，建议保留此默认值，除非您需要确保将 JavaScript 代码评估为旧版本。例如，一些较旧的运行时可能只允许 ECMAScript 5，在这种情况下，您可以像这样配置 ESLint：

export default [
    {
        files: ["**/*.js"],
        languageOptions: {
            ecmaVersion: 5
        }
    }
];

# 配置 JavaScript 源类型

ESLint 可以通过以下三种方式之一评估您的代码：

您可以通过指定 sourceType 属性来指定您的代码打算在哪些模式下运行。此属性可以设置为 "module"、"commonjs" 或 "script"。默认情况下，对于 .js 和 .mjs 文件，sourceType 设置为 "module"，对于 .cjs 文件，设置为 "commonjs"。这是一个例子：

export default [
    {
        files: ["**/*.js"],
        languageOptions: {
            sourceType: "script"
        }
    }
];

# 配置自定义解析器及其选项

在许多情况下，您可以使用 ESLint 附带的默认解析器来解析您的 JavaScript 代码。您可以选择使用 parser 属性覆盖默认解析器。parser 属性可以是 "pluginName/parserName" 格式的字符串（表示从插件中检索解析器）或包含 parse() 方法或 parseForESLint() 方法的对象。例如，您可以使用 @babel/eslint-parser 包来允许 ESLint 解析实验性语法：

import babelParser from "@babel/eslint-parser";

export default [
    {
        files: ["**/*.js", "**/*.mjs"],
        languageOptions: {
            parser: babelParser
        }
    }
];

此配置确保将使用 Babel 解析器而不是默认解析器来解析所有以 .js 和 .mjs 结尾的文件。

您还可以使用 parserOptions 属性将选项直接传递给自定义解析器。此属性是一个对象，其名称-值对特定于您正在使用的解析器。对于 Babel 解析器，您可以传入如下选项：

import babelParser from "@babel/eslint-parser";

export default [
    {
        files: ["**/*.js", "**/*.mjs"],
        languageOptions: {
            parser: babelParser,
            parserOptions: {
                requireConfigFile: false,
                babelOptions: {
                    babelrc: false,
                    configFile: false,
                    // your babel options
                    presets: ["@babel/preset-env"],
                }
            }
        }
    }
];

# 配置全局变量

要在配置对象中配置全局变量，请将 globals 配置属性设置为一个对象，该对象包含为您要使用的每个全局变量命名的键。对于每个全局变量键，设置相应的值等于 "writable" 以允许变量被覆盖或 "readonly" 不允许覆盖。例如：

export default [
    {
        files: ["**/*.js"],
        languageOptions: {
            globals: {
                var1: "writable",
                var2: "readonly"
            }
        }
    }
];

这些示例允许在您的代码中覆盖 var1，但不允许对 var2 进行覆盖。

可以使用字符串 "off" 禁用全局变量。例如，在大多数 ES2015 全局变量可用但 Promise 不可用的环境中，您可以使用以下配置：

export default [
    {
        languageOptions: {
            globals: {
                Promise: "off"
            }
        }
    }
];

由于历史原因，布尔值 false 和字符串值 "readable" 等价于 "readonly"。类似地，布尔值 true 和字符串值 "writeable" 等价于 "writable"。但是，不推荐使用旧值。

# 在配置中使用插件

插件用于跨 ESLint 项目共享规则、处理器、配置、解析器等。

# 使用插件规则

您可以使用插件中包含的特定规则。为此，请使用 plugins 键在配置对象中指定插件。plugin 键的值是一个对象，其中插件的名称是属性名称，值是插件对象本身。这是一个例子：

import jsdoc from "eslint-plugin-jsdoc";

export default [
    {
        files: ["**/*.js"],
        plugins: {
            jsdoc: jsdoc
        },
        rules: {
            "jsdoc/require-description": "error",
            "jsdoc/check-values": "error"
        }
    }
];

在此配置中，JSDoc 插件被定义为名称 jsdoc。每个规则名称中的前缀 jsdoc/ 表示该规则来自具有该名称的插件，而不是来自 ESLint 本身。

因为插件的名字和插件对象都是jsdoc，你也可以把配置简写成这样：

import jsdoc from "eslint-plugin-jsdoc";

export default [
    {
        files: ["**/*.js"],
        plugins: {
            jsdoc
        },
        rules: {
            "jsdoc/require-description": "error",
            "jsdoc/check-values": "error"
        }
    }
];

虽然这是最常见的约定，但您不需要使用插件规定的相同名称。您可以指定任何您喜欢的前缀，例如：

import jsdoc from "eslint-plugin-jsdoc";

export default [
    {
        files: ["**/*.js"],
        plugins: {
            jsd: jsdoc
        },
        rules: {
            "jsd/require-description": "error",
            "jsd/check-values": "error"
        }
    }
];

此配置对象使用 jsd 作为前缀插件，而不是 jsdoc。

# 使用插件中包含的配置

您可以通过将配置直接添加到 eslint.config.js 配置数组来使用插件中包含的配置。通常，您这样做是为了插件的推荐配置。这是一个例子：

import jsdoc from "eslint-plugin-jsdoc";

export default [
    // configuration included in plugin
    jsdoc.configs.recommended,
    // other configuration objects...
    {
        files: ["**/*.js"],
        plugins: {
            jsdoc: jsdoc
        },
        rules: {
            "jsdoc/require-description": "warn",
        }
    }
];

# 使用处理器

处理器允许 ESLint 将文本转换为 ESLint 可以 lint 的代码片段。您可以通过定义一个 processor 属性来指定用于给定文件类型的处理器，该属性包含格式为 "pluginName/processorName" 的处理器名称以引用插件中的处理器或包含 preprocess() 和 postprocess() 方法的对象。例如，要从 Markdown 文件中提取 JavaScript 代码块，您可以将其添加到您的配置中：

import markdown from "eslint-plugin-markdown";

export default [
    {
        files: ["**/*.md"],
        plugins: {
            markdown
        },
        processor: "markdown/markdown",
        settings: {
            sharedData: "Hello"
        }
    }
];

此配置对象指定在名为 "markdown" 的插件中包含一个名为 "markdown" 的处理器，并将该处理器应用于所有以 .md 结尾的文件。

处理器可以生成命名代码块，作为配置对象中的文件名，例如 0.js 和 1.js。ESLint 将这样的命名代码块作为原始文件的子文件处理。您可以为命名代码块指定其他配置对象。例如，以下对markdown文件中以.js结尾的命名代码块禁用strict规则。

import markdown from "eslint-plugin-markdown";

export default [
    {
        files: ["**/*.md"],
        plugins: {
            markdown
        },
        processor: "markdown/markdown",
        settings: {
            sharedData: "Hello"
        }
    },

    // applies only to code blocks
    {
        files: ["**/*.md/*.js"],
        rules: {
            strict: "off"
        }
    }
];

# 配置规则

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

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

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

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

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

# 规则严重性

您可以为规则指定三种可能的严重性

"error"（或 2）——报告的问题应被视为错误。使用 ESLint CLI 时，错误会导致 CLI 以非零代码退出。
"warn"（或 1）——报告的问题应被视为警告。使用 ESLint CLI 时，会报告警告，但不会更改退出代码。如果只报告警告，则退出代码将为 0。
"off"（或 0）- 应完全关闭该规则。

# 规则配置级联

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

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

使用此配置，semi 的最终规则配置是 ["warn", "always"]，因为它出现在数组的最后。该数组指示配置用于严重性和任何选项。您可以通过仅定义字符串或数字来仅更改严重性，如下例所示：

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

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

# 配置共享设置

ESLint 支持将共享设置添加到配置文件中。插件使用 settings 来指定应该在其所有规则之间共享的信息。您可以将 settings 对象添加到配置对象，它将提供给正在执行的每个规则。如果您要添加自定义规则并希望它们能够访问相同的信息，这可能会很有用。这是一个例子：

export default [
    {
        settings: {
            sharedData: "Hello"
        }
    }
];

# 使用预定义的配置

ESLint 有两个预定义的配置：

eslint:recommended - 启用 ESLint 建议所有人使用的规则以避免潜在错误
eslint:all - 启用 ESLint 附带的所有规则

要包含这些预定义配置，您可以将字符串值插入到返回的数组中，然后对后续配置对象中的其他属性进行任何修改：

export default [
    "eslint:recommended",
    {
        rules: {
            semi: ["warn", "always"]
        }
    }
];

在这里，首先应用 eslint:recommended 预定义的配置，然后另一个配置对象为 semi 添加所需的配置。

# 配置文件解析

在命令行上运行 ESLint 时，它首先检查当前工作目录中是否有 eslint.config.js，如果没有找到，将查找该文件的下一个父目录。此搜索将继续，直到找到文件或到达根目录。

您可以通过将 ESLINT_USE_FLAT_CONFIG 环境变量设置为 true 并在命令行上使用 -c 或 --config 选项指定备用配置文件来阻止对 eslint.config.js 的搜索，例如：

ESLINT_USE_FLAT_CONFIG=true npx eslint -c some-other-file.js **/*.js

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

← 核心概念配置文件 →