配置迁移指南
本指南概述了如何将你的 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 flat configuration files, refer to flat configuration files.
迁移你的配置文件
🌐 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:
npm
npx @eslint/migrate-config .eslintrc.json
yarn
yarn dlx @eslint/migrate-config .eslintrc.json
pnpm
pnpm dlx @eslint/migrate-config .eslintrc.json
bun
bunx @eslint/migrate-config .eslintrc.json
这将为你的 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:
配置格式之间的主要区别
🌐 Key Differences between Configuration Formats
eslintrc 和扁平配置格式之间的一些最显着的差异如下：
🌐 A few of the most notable differences between the eslintrc and flat config formats are the following:
导入插件和自定义解析器
🌐 Import 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
};
在扁平配置中，你会做同样的事情，如下所示：
🌐 In flat config, you would do the same thing like this:
// eslint.config.js
import { defineConfig } from "eslint/config";
import jsdoc from "eslint-plugin-jsdoc";
export default defineConfig([
{
files: ["**/*.js"],
plugins: {
jsdoc: jsdoc,
},
rules: {
"jsdoc/require-description": "error",
"jsdoc/check-values": "error",
},
},
]);
自定义解析器
🌐 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
};
在扁平配置中，你会做同样的事情，如下所示：
🌐 In flat config, you would do the same thing like this:
// eslint.config.js
import { defineConfig } from "eslint/config";
import babelParser from "@babel/eslint-parser";
export default defineConfig([
{
// ...other config
languageOptions: {
parser: babelParser,
},
// ...other config
},
]);
处理器
🌐 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() {},
},
},
};
在 eslintrc 中，你可以进行如下配置：
🌐 In eslintrc, you would configure as follows:
// .eslintrc.js
module.exports = {
plugins: ["someplugin"],
processor: "someplugin/someProcessor",
};
ESLint 还会自动添加以下等效内容：
🌐 ESLint would also automatically add the equivalent of the following:
{
overrides: [
{
files: ["**/*.md"],
processor: "someplugin/.md",
},
];
}
在扁平配置中，以下都是表达相同内容的有效方法：
🌐 In flat config, the following are all valid ways to express the same:
// eslint.config.js
import { defineConfig } from "eslint/config";
import somePlugin from "eslint-plugin-someplugin";
export default defineConfig([
{
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,
},
]);
请注意，由于 .md 处理器不会被 flat 配置自动添加，所以你还需要指定一个额外的配置元素：
🌐 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"]
}
基于通配符的配置
🌐 Glob-Based Configs
默认情况下，eslintrc 文件会对其所在目录及其子目录中的所有文件进行 lint（除了被 .eslintignore 覆盖的文件）。如果你想为不同的文件 glob 模式使用不同的配置，你可以在 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.
默认情况下，平面配置文件支持导出数组中的不同基于 glob 模式的配置。你可以在配置对象的 files 属性中包含 glob 模式。如果未指定 files 属性，配置将默认使用 glob 模式 "**/*.{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"],
},
};
此 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",
},
},
],
};
对于扁平配置，以下是具有默认通配符模式的配置：
🌐 For flat config, here is a configuration with the default glob pattern:
// eslint.config.js
import { defineConfig } from "eslint/config";
import js from "@eslint/js";
export default defineConfig([
js.configs.recommended, // Recommended config applied to all files
// Override the recommended config
{
rules: {
indent: ["error", 2],
"no-unused-vars": "warn",
},
// ...other configuration
},
]);
支持不同通配符模式的多个配置的扁平配置示例配置：
🌐 A flat config example configuration supporting multiple configs for different glob patterns:
// eslint.config.js
import { defineConfig } from "eslint/config";
import js from "@eslint/js";
export default defineConfig([
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
]);
配置语言选项
🌐 Configure 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
};
这是扁平配置中的相同配置：
🌐 Here’s the same configuration in flat config:
// eslint.config.js
import { defineConfig } from "eslint/config";
import globals from "globals";
export default defineConfig([
{
languageOptions: {
ecmaVersion: 2022,
sourceType: "module",
globals: {
...globals.browser,
...globals.node,
myCustomGlobal: "readonly",
},
},
// ...other config
},
]);
eslint-env 配置评论
🌐 eslint-env Configuration Comments
在 eslintrc 配置系统中，可以使用 eslint-env 配置注释为文件定义全局变量。
在使用 flat 配置进行 lint 检查时，这些注释不再被识别，并会被报告为错误。
因此，在从 eslintrc 迁移到 flat 配置时，应从所有文件中删除 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 and 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", () => {
// ...
});
});
在上面的例子中，describe 和 it 会因为 /* eslint-env mocha */ 注释而被识别为全局标识符。
🌐 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", () => {
// ...
});
});
另一种选择是从正在检查的文件中删除注释并在配置中定义全局变量，例如：
🌐 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 { defineConfig } from "eslint/config";
import globals from "globals";
export default defineConfig([
// ...other config
{
files: ["tests/**"],
languageOptions: {
globals: {
...globals.mocha,
},
},
},
]);
预定义和可共享的配置
🌐 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:all"：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
npm install --save-dev @eslint/js
yarn
yarn add --dev @eslint/js
pnpm
pnpm add --save-dev @eslint/js
bun
bun add --dev @eslint/js
你可以将这些配置中的每一个添加到导出的数组中，或从中公开特定规则。使用平面配置时，你必须导入本地配置文件和 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
};
此 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
};
要在扁平配置中使用相同的配置，你将执行以下操作：
🌐 To use the same configs in flat config, you would do the following:
// eslint.config.js
import { defineConfig } from "eslint/config";
import js from "@eslint/js";
import customConfig from "./custom-config.js";
import myConfig from "eslint-config-my-config";
export default defineConfig([
js.configs.recommended,
customConfig,
myConfig,
{
rules: {
semi: ["warn", "always"],
},
// ...other config
},
]);
请注意，因为你只是导入 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 { defineConfig } from "eslint/config";
import js from "@eslint/js";
import customTestConfig from "./custom-test-config.js";
export default defineConfig([
js.configs.recommended,
{
...customTestConfig,
files: ["**/*.test.js"],
},
]);
在平面配置中使用 eslintrc 配置
🌐 Use 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
npm install --save-dev @eslint/eslintrc
yarn
yarn add --dev @eslint/eslintrc
pnpm
pnpm add --save-dev @eslint/eslintrc
bun
bun add --dev @eslint/eslintrc
然后，导入 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 { defineConfig } from "eslint/config";
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 defineConfig([
// mimic ESLintRC-style extends
...compat.extends("eslint-config-my-config"),
]);
这个例子使用 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 类的更多信息，请参阅 package README。
🌐 For more information about the FlatCompat class, please see the package README.
忽略文件
🌐 Ignore 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 属性接受一个 glob 模式数组。平铺配置不支持从 .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.
例如，这里有一个你可以与 eslintrc 配置一起使用的 .eslintignore 示例：
🌐 For example, here’s a .eslintignore example you can use with an eslintrc config:
# .eslintignore
temp.js
config/*
# ...other ignored files
以下是在 .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/*"],
};
扁平配置中的等效忽略模式如下所示：
🌐 The equivalent ignore patterns in flat config look like this:
import { defineConfig } from "eslint/config";
export default defineConfig([
// ...other config
{
// Note: there should be no other properties in this object
ignores: ["**/temp.js", "config/*"],
},
]);
在 .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，你可以使用它来配置代码检查器。在 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,
};
以下是扁平配置中的相同选项：
🌐 Here’s the same options in flat config:
// eslint.config.js
import { defineConfig } from "eslint/config";
export default defineConfig([
{
// ...other config
linterOptions: {
noInlineConfig: true,
reportUnusedDisableDirectives: "warn",
},
},
]);
CLI 标志更改
🌐 CLI Flag Changes
扁平配置文件格式不再支持以下 CLI 标志：
🌐 The following CLI flags are no longer supported with the flat config file format:
--env--ignore-path--no-eslintrc--resolve-plugins-relative-to--rulesdir
--env
--env 标志用于启用特定环境的全局变量（例如，browser 或 node）。扁平配置不支持此标志。相反，请直接在你的配置中定义相关全局变量。有关更多详细信息，请参阅 指定全局变量。
🌐 The --env flag was used to enable environment-specific globals (for example, browser, or node). Flat config doesn’t support this flag. Instead, define the relevant globals directly in your configuration. See Specify Globals for more details.
例如，如果你之前使用过 --env browser,node，你需要像这样更新你的配置文件：
🌐 For example, if you previously used --env browser,node, you’ll need to update your config file like this:
// eslint.config.js
import { defineConfig } from "eslint/config";
import globals from "globals";
export default defineConfig([
{
languageOptions: {
globals: {
...globals.browser,
...globals.node,
},
},
},
]);
--ignore-path
--ignore-path 标志用于指定要将哪个文件用作你的 .eslintignore。平铺配置不会从 .eslintignore 文件加载忽略模式，也不支持此标志。如果你想包含来自 .gitignore 文件的模式，请使用 @eslint/compat 的 includeIgnoreFile()。更多细节请参见 包含 .gitignore 文件 。
🌐 The --ignore-path flag was used to specify which file to use as your .eslintignore. Flat config doesn’t load ignore patterns from .eslintignore files and does not support this flag. If you want to include patterns from a .gitignore file, use includeIgnoreFile() from @eslint/compat. See Include .gitignore Files for more details.
例如，如果你之前使用过 --ignore-path .gitignore：
🌐 For example, if you previously used --ignore-path .gitignore:
// eslint.config.js
import { defineConfig } from "eslint/config";
import { includeIgnoreFile } from "@eslint/compat";
import { fileURLToPath } from "node:url";
const gitignorePath = fileURLToPath(new URL(".gitignore", import.meta.url));
export default defineConfig([
includeIgnoreFile(gitignorePath, "Imported .gitignore patterns"),
// other configs
]);
更新 (2026-05-01)：来自 @eslint/compat 的 includeIgnoreFile() 已被弃用，取而代之的是来自 @eslint/config-helpers 的 includeIgnoreFile()（在 eslint/config 重新导出）。新的 API 更加通用，并且可以选择相对于忽略文件解释忽略模式。
🌐 Update (2026-05-01): The includeIgnoreFile() from @eslint/compat has been deprecated in favor of includeIgnoreFile() from @eslint/config-helpers (reexported at eslint/config). The new API is more versatile and has an option to interpret ignore patterns relative to the ignore file.
--no-eslintrc
--no-eslintrc 标志已被 --no-config-lookup 取代。
🌐 The --no-eslintrc flag has been replaced with --no-config-lookup.
--resolve-plugins-relative-to
--resolve-plugins-relative-to 标志用来指示在配置文件中引用的插件目录应相对于哪个目录进行解析。这是必要的，因为可共享的配置只能解析作为 peer 依赖或父包依赖的插件。
🌐 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.
--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 { defineConfig } from "eslint/config";
import myRule from "./rules/my-rule.js";
export default defineConfig([
{
// define the plugin
plugins: {
local: {
rules: {
"my-rule": myRule,
},
},
},
// configure the rule
rules: {
"local/my-rule": ["error"],
},
},
]);
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。）files选项不能再是单个字符串，它必须是一个数组。sourceType选项现在支持新值"commonjs"（.eslintrc也支持，但它从未被记录过）。
扁平配置文件的 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
ESLint v9.x 支持已在 vscode-eslint v3.0.10 中添加。
🌐 ESLint v9.x support was added in the vscode-eslint v3.0.10.
vscode-eslint 版本在 v3.0.10 之前，新的配置系统默认未启用。要启用对新配置文件的支持，请编辑你的 .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
}
在未来版本的 ESLint 插件中，你将不再需要手动启用此功能。
🌐 In a future version of the ESLint plugin, you will no longer need to enable this manually.
进阶读物
🌐 Further Reading