配置迁移指南

本指南概述了如何将 ESLint 配置文件从 eslintrc 格式（通常在 .eslintrc.js 或 .eslintrc.json 文件中配置）迁移到新的扁平配置格式（通常在 eslint.config.js 文件中配置）。

¥This guide provides an overview of how you can migrate your ESLint configuration file from the eslintrc format (typically configured in .eslintrc.js or .eslintrc.json files) to the new flat config format (typically configured in an eslint.config.js file).

要了解有关扁平配置格式的更多信息，请参阅这篇博文。

¥To learn more about the flat config format, refer to this blog post.

有关这些配置格式的参考信息，请参阅以下文档：

¥For reference information on these configuration formats, refer to the following documentation:

迁移你的配置文件

¥Migrate Your Config File

要开始使用，请在现有配置文件（.eslintrc、.eslintrc.json、.eslintrc.yml）上使用配置迁移器，如下所示：

¥To get started, use the configuration migrator on your existing configuration file (.eslintrc, .eslintrc.json, .eslintrc.yml), like this:

npx @eslint/migrate-config .eslintrc.json
1

这将为你的 eslint.config.js 文件创建一个起点，但不能保证在没有进一步修改的情况下立即工作。但是，它会自动补齐本指南中提到的大部分转换工作。

¥This will create a starting point for your eslint.config.js file but is not guaranteed to work immediately without further modification. It will, however, do most of the conversion work mentioned in this guide automatically.

开始使用扁平配置文件

¥Start Using Flat Config Files

自 ESLint v9.0.0 以来，扁平配置文件格式一直是默认配置文件格式。你可以开始使用扁平配置文件格式，无需任何其他配置。

¥The flat config file format has been the default configuration file format since ESLint v9.0.0. You can start using the flat config file format without any additional configuration.

要将扁平配置与 ESLint v8 结合使用，请将 eslint.config.js 文件放置在项目的根目录中或将 ESLINT_USE_FLAT_CONFIG 环境变量设置为 true。

¥To use flat config with ESLint v8, place a eslint.config.js file in the root of your project or set the ESLINT_USE_FLAT_CONFIG environment variable to true.

配置文件格式之间没有改变的事情

¥Things That Haven’t Changed between Configuration File Formats

虽然配置文件格式已从 eslintrc 更改为扁平配置，但以下内容保持不变：

¥While the configuration file format has changed from eslintrc to flat config, the following has stayed the same:

配置规则的语法

¥Syntax for configuring rules
配置处理器的语法

¥Syntax for configuring processors
CLI，除了 CLI 标志更改中提到的标志更改之外。

¥The CLI, except for the flag changes noted in CLI Flag Changes.
全局变量的配置方式相同，但属性不同（参见配置语言选项）。

¥Global variables are configured the same way, but on a different property (see Configuring Language Options).

配置格式之间的主要区别

¥Key Differences between Configuration Formats

eslintrc 和扁平配置格式之间的一些最显着的差异如下：

¥A few of the most notable differences between the eslintrc and flat config formats are the following:

导入插件和自定义解析器

¥Importing Plugins and Custom Parsers

Eslintrc 文件在 plugins 属性内使用基于字符串的导入系统来加载插件，在 extends 属性内使用基于字符串的导入系统来加载外部配置。

¥Eslintrc files use string-based import system inside the plugins property to load plugins and inside the extends property to load external configurations.

扁平配置文件将插件和解析器表示为 JavaScript 对象。这意味着你可以使用 CommonJS require() 或 ES 模块 import 语句从外部文件加载插件和自定义解析器。

¥Flat config files represent plugins and parsers as JavaScript objects. This means you can use CommonJS require() or ES module import statements to load plugins and custom parsers from external files.

例如，此 eslintrc 配置文件加载 eslint-plugin-jsdoc 并配置该插件的规则：

¥For example, this eslintrc config file loads eslint-plugin-jsdoc and configures rules from that plugin:

// .eslintrc.js

module.exports = {
    // ...other config
    plugins: ["jsdoc"],
    rules: {
        "jsdoc/require-description": "error",
        "jsdoc/check-values": "error"
    }
    // ...other config
};
1
2
3
4
5
6
7
8
9
10
11

在扁平配置中，你会做同样的事情，如下所示：

¥In flat config, you would do the same thing like this:

// eslint.config.js

import jsdoc from "eslint-plugin-jsdoc";

export default [
    {
        files: ["**/*.js"],
        plugins: {
            jsdoc: jsdoc
        },
        rules: {
            "jsdoc/require-description": "error",
            "jsdoc/check-values": "error"
        }
    }
];
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

自定义解析器

¥Custom Parsers

在 eslintrc 文件中，导入自定义解析器与导入插件类似：你使用字符串来指定解析器的名称。

¥In eslintrc files, importing a custom parser is similar to importing a plugin: you use a string to specify the name of the parser.

在扁平配置文件中，将自定义解析器作为模块导入，然后将其分配给配置对象的 languageOptions.parser 属性。

¥In flat config files, import a custom parser as a module, then assign it to the languageOptions.parser property of a configuration object.

例如，此 eslintrc 配置文件使用 @babel/eslint-parser 解析器：

¥For example, this eslintrc config file uses the @babel/eslint-parser parser:

// .eslintrc.js

module.exports = {
    // ...other config
    parser: "@babel/eslint-parser",
    // ...other config
};
1
2
3
4
5
6
7

在扁平配置中，你会做同样的事情，如下所示：

¥In flat config, you would do the same thing like this:

// eslint.config.js

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

export default [
    {
        // ...other config
        languageOptions: {
            parser: babelParser
        }
        // ...other config
    }
];
1
2
3
4
5
6
7
8
9
10
11
12
13

处理器

¥Processors

在 eslintrc 文件中，必须在插件中定义处理器，然后在配置中按名称引用。以点开头的处理器表示文件扩展名为处理器，ESLint 会自动配置该文件扩展名。

¥In eslintrc files, processors had to be defined in a plugin, and then referenced by name in the configuration. Processors beginning with a dot indicated a file extension-named processor which ESLint would automatically configure for that file extension.

在扁平配置文件中，处理器仍然可以通过插件的名称引用，但现在也可以直接插入配置中。处理器永远不会自动配置，必须在配置中显式设置。

¥In flat config files, processors can still be referenced from plugins by their name, but they can now also be inserted directly into the configuration. Processors will never be automatically configured, and must be explicitly set in the configuration.

作为带有处理器的自定义插件的示例：

¥As an example with a custom plugin with processors:

// node_modules/eslint-plugin-someplugin/index.js
module.exports = {
    processors: {
        ".md": {
            preprocess() {},
            postprocess() {}
        },
        "someProcessor": {
            preprocess() {},
            postprocess() {}
        }
    }
};
1
2
3
4
5
6
7
8
9
10
11
12
13

在 eslintrc 中，你可以进行如下配置：

¥In eslintrc, you would configure as follows:

// .eslintrc.js
module.exports = {
    plugins: ["someplugin"],
    processor: "someplugin/someProcessor"
};
1
2
3
4
5

ESLint 还会自动添加以下等效内容：

¥ESLint would also automatically add the equivalent of the following:

{
     overrides: [{
        files: ["**/*.md"],
        processor: "someplugin/.md"
     }]
}
1
2
3
4
5
6

在扁平配置中，以下都是表达相同内容的有效方法：

¥In flat config, the following are all valid ways to express the same:

// eslint.config.js
import somePlugin from "eslint-plugin-someplugin";

export default [
    {
        plugins: { somePlugin },
        processor: "somePlugin/someProcessor"
    },
    {
        plugins: { somePlugin },
        // We can embed the processor object in the config directly
        processor: somePlugin.processors.someProcessor
    },
    {
        // We don't need the plugin to be present in the config to use the processor directly
        processor: somePlugin.processors.someProcessor
    }
];
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

请注意，由于 .md 处理器不会通过扁平配置自动添加，因此你还需要指定一个额外的配置元素：

¥Note that because the .md processor is not automatically added by flat config, you also need to specify an extra configuration element:

{
    files: ["**/*.md"],
    processor: somePlugin.processors[".md"]
}
1
2
3
4

基于通配符的配置

¥Glob-Based Configs

默认情况下，eslintrc 文件会检查它们所在目录及其子目录中的所有文件（.eslintignore 覆盖的文件除外）。如果你想对不同的文件通配符模式有不同的配置，可以在 overrides 属性中指定它们。

¥By default, eslintrc files lint all files (except those covered by .eslintignore) in the directory in which they’re placed and its child directories. If you want to have different configurations for different file glob patterns, you can specify them in the overrides property.

默认情况下，扁平配置文件在导出的数组中支持不同的基于通配符模式的配置。你可以将通配符模式包含在配置对象的 files 属性中。如果你不指定 files 属性，则配置默认为通配符模式 "**/*.{js,mjs,cjs}"。基本上，扁平配置文件中的所有配置都类似于 eslintrc overrides 属性。

¥By default, flat config files support different glob pattern-based configs in exported array. You can include the glob pattern in a config object’s files property. If you don’t specify a files property, the config defaults to the glob pattern "**/*.{js,mjs,cjs}". Basically, all configuration in the flat config file is like the eslintrc overrides property.

eslintrc 示例

¥eslintrc Examples

例如，这个 eslintrc 文件适用于它所在目录及其子目录中的所有文件：

¥For example, this eslintrc file applies to all files in the directory where it is placed and its child directories:

// .eslintrc.js

module.exports = {
    // ...other config
    rules: {
        semi: ["warn", "always"]
    }
};
1
2
3
4
5
6
7
8

此 eslintrc 文件支持多个具有覆盖的配置：

¥This eslintrc file supports multiple configs with overrides:

// .eslintrc.js

module.exports = {
    // ...other config
    overrides: [
        {
            files: ["src/**/*"],
            rules: {
                semi: ["warn", "always"]
            }
        },
        {
            files:["test/**/*"],
            rules: {
                "no-console": "off"
            }
        }
    ]
};
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

对于扁平配置，以下是具有默认通配符模式的配置：

¥For flat config, here is a configuration with the default glob pattern:

// eslint.config.js

import js from "@eslint/js";

export default [
    js.configs.recommended, // Recommended config applied to all files
    // Override the recommended config
    {
        rules: {
            indent: ["error", 2],
            "no-unused-vars": "warn"
        }
        // ...other configuration
    }
];
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

支持不同通配符模式的多个配置的扁平配置示例配置：

¥A flat config example configuration supporting multiple configs for different glob patterns:

// eslint.config.js

import js from "@eslint/js";

export default [
    js.configs.recommended, // Recommended config applied to all files
    // File-pattern specific overrides
    {
        files: ["src/**/*", "test/**/*"],
        rules: {
            semi: ["warn", "always"]
        }
    },
    {
        files:["test/**/*"],
        rules: {
            "no-console": "off"
        }
    }
    // ...other configurations
];
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

配置语言选项

¥Configuring Language Options

在 eslintrc 文件中，你可以跨 env、globals 和 parserOptions 属性配置各种语言选项。特定运行时的全局变量组（例如浏览器 JavaScript 的 document 和 window；Node.js 的 process 和 require）使用 env 属性进行配置。

¥In eslintrc files, you configure various language options across the env, globals and parserOptions properties. Groups of global variables for specific runtimes (e.g. document and window for browser JavaScript; process and require for Node.js) are configured with the env property.

在扁平配置文件中，globals 和 parserOptions 合并在 languageOptions 键下；env 属性不存在。特定运行时的全局变量组从 globals npm 包导入并包含在 globals 属性中。你可以使用展开运算符 (...) 一次导入多个全局变量。

¥In flat config files, the globals, and parserOptions are consolidated under the languageOptions key; the env property doesn’t exist. Groups of global variables for specific runtimes are imported from the globals npm package and included in the globals property. You can use the spread operator (...) to import multiple globals at once.

例如，这是一个带有语言选项的 eslintrc 文件：

¥For example, here’s an eslintrc file with language options:

// .eslintrc.js

module.exports = {
    env: {
        browser: true,
        node: true
    },
    globals: {
        myCustomGlobal: "readonly",
    },
    parserOptions: {
        ecmaVersion: 2022,
        sourceType: "module"
    }
    // ...other config
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

这是扁平配置中的相同配置：

¥Here’s the same configuration in flat config:

// eslint.config.js

import globals from "globals";

export default [
    {
        languageOptions: {
            ecmaVersion: 2022,
            sourceType: "module",
            globals: {
                ...globals.browser,
                ...globals.node,
                myCustomGlobal: "readonly"
            }
        }
        // ...other config
    }
];
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

`eslint-env` 配置注释

¥eslint-env Configuration Comments

在 eslintrc 配置系统中，可以使用 eslint-env 配置注释来定义文件的全局变量。使用扁平配置进行 linting 时，将不再识别这些注释：在 ESLint 的未来版本中，eslint-env 注释将被报告为错误。因此，从 eslintrc 迁移到扁平配置时，应从所有文件中删除 eslint-env 配置注释。它们可以替换为等效但更详细的 global 配置注释，或者删除以支持配置文件中的 globals 定义。

¥In the eslintrc config system it was possible to use eslint-env configuration comments to define globals for a file. These comments are no longer recognized when linting with flat config: in a future version of ESLint, eslint-env comments will be reported as errors. For this reason, when migrating from eslintrc to flat config, eslint-env configuration comments should be removed from all files. They can be either replaced with equivalent but more verbose global configuration comments, or dropped in favor of globals definitions in the config file.

例如，当使用 eslintrc 时，要检查的文件可能如下所示：

¥For example, when using eslintrc, a file to be linted could look like this:

// tests/my-file.js

/* eslint-env mocha */

describe("unit tests", () => {
    it("should pass", () => {
        // ...
    });
});
1
2
3
4
5
6
7
8
9

在上面的示例中，由于 /* eslint-env mocha */ 注释，describe 和 it 将被识别为全局标识符。

¥In the above example, describe and it would be recognized as global identifiers because of the /* eslint-env mocha */ comment.

使用带有 global 配置注释的扁平配置可以实现相同的效果，例如：

¥The same effect can be achieved with flat config with a global configuration comment, e.g.:

// tests/my-file.js

/* global describe, it -- Globals defined by Mocha */

describe("unit tests", () => {
    it("should pass", () => {
        // ...
    });
});
1
2
3
4
5
6
7
8
9

另一种选择是从正在检查的文件中删除注释并在配置中定义全局变量，例如：

¥Another option is to remove the comment from the file being linted and define the globals in the configuration, for example:

// eslint.config.js

import globals from "globals";

export default [
    // ...other config
    {
        files: [
            "tests/**"
        ],
        languageOptions: {
            globals: {
                ...globals.mocha
            }
        }
    }
];
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

预定义和可共享的配置

¥Predefined and Shareable Configs

在 eslintrc 文件中，使用 extends 属性来使用预定义和可共享的配置。ESLint 附带两个预定义的配置，你可以将其作为字符串访问：

¥In eslintrc files, use the extends property to use predefined and shareable configs. ESLint comes with two predefined configs that you can access as strings:

"eslint:recommended"：ESLint 推荐的规则

¥"eslint:recommended": the rules recommended by ESLint
"eslint:all"：所有规则均随 ESLint 一起提供

¥"eslint:all": all rules shipped with ESLint

你还可以使用 extends 属性来扩展可共享配置。可共享的配置可以是局部配置文件的路径或 npm 包名称。

¥You can also use the extends property to extend a shareable config. Shareable configs can either be paths to local config files or npm package names.

在扁平配置文件中，预定义的配置从单独的模块导入到扁平配置文件中。recommended 和 all 规则配置位于 @eslint/js 包中。你必须导入此包才能使用这些配置：

¥In flat config files, predefined configs are imported from separate modules into flat config files. The recommended and all rules configs are located in the @eslint/js package. You must import this package to use these configs:

npm install @eslint/js --save-dev
1

你可以将这些配置中的每一个添加到导出的数组中或公开其中的特定规则。你必须使用扁平配置导入局部配置文件和 npm 包配置的模块。

¥You can add each of these configs to the exported array or expose specific rules from them. You must import the modules for local config files and npm package configs with flat config.

例如，以下是使用内置 eslint:recommended 配置的 eslintrc 文件：

¥For example, here’s an eslintrc file using the built-in eslint:recommended config:

// .eslintrc.js

module.exports = {
    // ...other config
    extends: "eslint:recommended",
    rules: {
        semi: ["warn", "always"]
    },
    // ...other config
}
1
2
3
4
5
6
7
8
9
10

此 eslintrc 文件使用内置配置、局部自定义配置和 npm 包中的可共享配置：

¥This eslintrc file uses built-in config, local custom config, and shareable config from an npm package:

// .eslintrc.js

module.exports = {
    // ...other config
    extends: ["eslint:recommended", "./custom-config.js", "eslint-config-my-config"],
    rules: {
        semi: ["warn", "always"]
    },
    // ...other config
}
1
2
3
4
5
6
7
8
9
10

要在扁平配置中使用相同的配置，你将执行以下操作：

¥To use the same configs in flat config, you would do the following:

// eslint.config.js

import js from "@eslint/js";
import customConfig from "./custom-config.js";
import myConfig from "eslint-config-my-config";

export default [
    js.configs.recommended,
    customConfig,
    myConfig,
    {
        rules: {
            semi: ["warn", "always"]
        },
        // ...other config
    }
];
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

请注意，因为你只是导入 JavaScript 模块，所以你可以在 ESLint 使用配置对象之前更改它们。例如，你可能希望某个配置对象仅适用于你的测试文件：

¥Note that because you are just importing JavaScript modules, you can mutate the config objects before ESLint uses them. For example, you might want to have a certain config object only apply to your test files:

// eslint.config.js

import js from "@eslint/js";
import customTestConfig from "./custom-test-config.js";

export default [
    js.configs.recommended,
    {
        ...customTestConfig,
        files: ["**/*.test.js"],
    },
];
1
2
3
4
5
6
7
8
9
10
11
12

在 Flat Config 中使用 eslintrc 配置

¥Using eslintrc Configs in Flat Config

你可能会发现你依赖的可共享配置尚未更新为扁平配置格式。在这种情况下，你可以使用 FlatCompat 实用程序将 eslintrc 格式转换为扁平配置格式。首先，安装 @eslint/eslintrc 包：

¥You may find that there’s a shareable config you rely on that hasn’t yet been updated to flat config format. In that case, you can use the FlatCompat utility to translate the eslintrc format into flat config format. First, install the @eslint/eslintrc package:

npm install @eslint/eslintrc --save-dev
1

然后，导入 FlatCompat 并创建一个新实例来转换现有的 eslintrc 配置。例如，如果 npm 包 eslint-config-my-config 是 eslintrc 格式，则可以这样写：

¥Then, import FlatCompat and create a new instance to convert an existing eslintrc config. For example, if the npm package eslint-config-my-config is in eslintrc format, you can write this:

import { FlatCompat } from "@eslint/eslintrc";
import path from "path";
import { fileURLToPath } from "url";

// mimic CommonJS variables -- not needed if using CommonJS
const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

const compat = new FlatCompat({
    baseDirectory: __dirname
});

export default [

    // mimic ESLintRC-style extends
    ...compat.extends("eslint-config-my-config"),
];
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

此示例使用 FlatCompat#extends() 方法将 eslint-config-my-config 插入到扁平配置数组中。

¥This example uses the FlatCompat#extends() method to insert the eslint-config-my-config into the flat config array.

有关 FlatCompat 类的更多信息，请参阅包自述文件。

¥For more information about the FlatCompat class, please see the package README.

忽略文件

¥Ignoring Files

使用 eslintrc，你可以通过在项目的根目录中创建单独的 .eslintignore 文件来使 ESLint 忽略文件。.eslintignore 文件使用与 .gitignore 文件相同的通配符模式语法。或者，你可以在 eslintrc 文件中使用 ignorePatterns 属性。

¥With eslintrc, you can make ESLint ignore files by creating a separate .eslintignore file in the root of your project. The .eslintignore file uses the same glob pattern syntax as .gitignore files. Alternatively, you can use an ignorePatterns property in your eslintrc file.

要忽略具有扁平配置的文件，你可以在没有其他属性的配置对象中使用 ignores 属性。ignores 属性接受一组通配符模式。扁平配置不支持从 .eslintignore 文件加载忽略模式，因此你需要将这些模式直接迁移到扁平配置中。

¥To ignore files with flat config, you can use the ignores property in a config object with no other properties. The ignores property accepts an array of glob patterns. Flat config does not support loading ignore patterns from .eslintignore files, so you’ll need to migrate those patterns directly into flat config.

例如，下面是一个 .eslintignore 示例，你可以将其与 eslintrc 配置一起使用：

¥For example, here’s a .eslintignore example you can use with an eslintrc config:

# .eslintignore
temp.js
config/*
# ...other ignored files
1
2
3
4

以下是 .eslintrc.js 文件中表示为 ignorePatterns 的相同模式：

¥Here are the same patterns represented as ignorePatterns in a .eslintrc.js file:

// .eslintrc.js
module.exports = {
    // ...other config
    ignorePatterns: ["temp.js", "config/*"],
};
1
2
3
4
5

扁平配置中的等效忽略模式如下所示：

¥The equivalent ignore patterns in flat config look like this:

export default [
    // ...other config
    {
        // Note: there should be no other properties in this object
        ignores: ["**/temp.js", "config/*"]
    }
];
1
2
3
4
5
6
7

在 .eslintignore 中，temp.js 忽略所有名为 temp.js 的文件，而在扁平配置中，你需要将其指定为 **/temp.js。扁平配置中的模式 temp.js 仅忽略与配置文件位于同一目录中名为 temp.js 的文件。

¥In .eslintignore, temp.js ignores all files named temp.js, whereas in flat config, you need to specify this as **/temp.js. The pattern temp.js in flat config only ignores a file named temp.js in the same directory as the configuration file.

Linter 选项

¥Linter Options

ESlintrc 文件允许你使用 noInlineConfig 和 reportUnusedDisableDirectives 属性配置 linter 本身。

¥ESlintrc files let you configure the linter itself with the noInlineConfig and reportUnusedDisableDirectives properties.

扁平配置系统引入了一个新的顶层属性 linterOptions，你可以使用它来配置 linter。在 linterOptions 对象中，你可以包含 noInlineConfig 和 reportUnusedDisableDirectives。

¥The flat config system introduces a new top-level property linterOptions that you can use to configure the linter. In the linterOptions object, you can include noInlineConfig and reportUnusedDisableDirectives.

例如，以下是启用了 linter 选项的 eslintrc 文件：

¥For example, here’s an eslintrc file with linter options enabled:

// .eslintrc.js

module.exports = {
    // ...other config
    noInlineConfig: true,
    reportUnusedDisableDirectives: true
}
1
2
3
4
5
6
7

以下是扁平配置中的相同选项：

¥Here’s the same options in flat config:

// eslint.config.js

export default [
    {
        // ...other config
        linterOptions: {
            noInlineConfig: true,
            reportUnusedDisableDirectives: "warn"
        }
    }
];
1
2
3
4
5
6
7
8
9
10
11

CLI 标志更改

¥CLI Flag Changes

扁平配置文件格式不再支持以下 CLI 标志：

¥The following CLI flags are no longer supported with the flat config file format:

--rulesdir
--ext
--resolve-plugins-relative-to

标志 --no-eslintrc 已替换为 --no-config-lookup。

¥The flag --no-eslintrc has been replaced with --no-config-lookup.

`--rulesdir`

--rulesdir 标志用于从指定目录加载附加规则。使用扁平配置时不再支持此功能。你可以创建一个包含直接在配置中的局部规则的插件，如下所示：

¥The --rulesdir flag was used to load additional rules from a specified directory. This is no longer supported when using flat config. You can instead create a plugin containing the local rules you have directly in your config, like this:

// eslint.config.js
import myRule from "./rules/my-rule.js";

export default [
    {
        // define the plugin
        plugins: {
            local: {
                rules: {
                    "my-rule": myRule
                }
            }
        },

        // configure the rule
        rules: {
            "local/my-rule": ["error"]
        }

    }
];
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

`--ext`

--ext 标志用于指定在命令行上传递目录时 ESLint 应搜索的其他文件扩展名，例如 npx eslint .。使用扁平配置时不再支持此功能。相反，指定你希望 ESLint 直接在配置中搜索的文件模式。例如，如果你之前使用的是 --ext .ts,.tsx，那么你将需要像这样更新你的配置文件：

¥The --ext flag was used to specify additional file extensions ESLint should search for when a directory was passed on the command line, such as npx eslint .. This is no longer supported when using flat config. Instead, specify the file patterns you’d like ESLint to search for directly in your config. For example, if you previously were using --ext .ts,.tsx, then you will need to update your config file like this:

// eslint.config.js
export default [
    {
        files: ["**/*.ts", "**/*.tsx"]

        // any additional configuration for these file types here
    }
];
1
2
3
4
5
6
7
8

ESLint 使用配置文件中的 files 键来确定应检查哪些文件。

¥ESLint uses the files keys from the config file to determine which files should be linted.

`--resolve-plugins-relative-to`

--resolve-plugins-relative-to 标志用于指示应相对于配置文件中的哪个目录插件引用进行解析。这是必要的，因为可共享配置只能解析作为对等依赖或父包依赖的插件。

¥The --resolve-plugins-relative-to flag was used to indicate which directory plugin references in your configuration file should be resolved relative to. This was necessary because shareable configs could only resolve plugins that were peer dependencies or dependencies of parent packages.

使用扁平配置，可共享配置可以直接指定其依赖，因此不再需要此标志。

¥With flat config, shareable configs can specify their dependencies directly, so this flag is no longer needed.

`package.json` 不再支持配置

¥package.json Configuration No Longer Supported

借助 eslintrc，可以使用 package.json 文件通过 eslintConfig 密钥配置 ESLint。

¥With eslintrc, it was possible to use a package.json file to configure ESLint using the eslintConfig key.

使用扁平配置，不再可能使用 package.json 文件来配置 ESLint。你需要将配置移至单独的文件中。

¥With flat config, it’s no longer possible to use a package.json file to configure ESLint. You’ll need to move your configuration into a separate file.

额外的变化

¥Additional Changes

从 eslintrc 到扁平配置文件格式进行了以下更改：

¥The following changes have been made from the eslintrc to the flat config file format:

root 选项不再存在。（扁平配置文件的行为就像设置了 root: true 一样。）

¥The root option no longer exists. (Flat config files act as if root: true is set.)
files 选项不能再是单个字符串，它必须是一个数组。

¥The files option cannot be a single string anymore, it must be an array.
sourceType 选项现在支持新值 "commonjs"（.eslintrc 也支持它，但从未记录在案）。

¥The sourceType option now supports the new value "commonjs" (.eslintrc supports it too, but it was never documented).

扁平配置文件的 TypeScript 类型

¥TypeScript Types for Flat Config Files

你可以在 GitHub 上的 lib/types 源文件夹中看到扁平配置文件格式的 TypeScript 类型。配置数组中对象的接口称为 Linter.Config。

¥You can see the TypeScript types for the flat config file format in the lib/types source folder on GitHub. The interface for the objects in the config’s array is called Linter.Config.

你可以在 lib/types/index.d.ts 中查看类型定义。

¥You can view the type definitions in lib/types/index.d.ts.

Visual Studio Code 支持

¥Visual Studio Code Support

vscode-eslint v3.0.10 中添加了对 ESLint v9.x 的支持。

¥ESLint v9.x support was added in the vscode-eslint v3.0.10.

在 v3.0.10 之前的 vscode-eslint 版本中，新配置系统默认未启用。要启用对新配置文件的支持，请编辑 .vscode/settings.json 文件并添加以下内容：

¥In versions of vscode-eslint prior to v3.0.10, the new configuration system is not enabled by default. To enable support for the new configuration files, edit your .vscode/settings.json file and add the following:

{
  // required in vscode-eslint < v3.0.10 only
  "eslint.experimental.useFlatConfig": true
}
1
2
3
4

在未来版本的 ESLint 插件中，你将不再需要手动启用此功能。

¥In a future version of the ESLint plugin, you will no longer need to enable this manually.

进阶读物

¥Further Reading