配置迁移指南

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

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

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

迁移您的配置文件

要开始使用，请在您现有的配置文件 (.eslintrc, .eslintrc.json, .eslintrc.yml) 上使用配置迁移器，如下所示

npm

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

yarn

yarn dlx  @eslint/migrate-config .eslintrc.json 
1

pnpm

pnpm dlx  @eslint/migrate-config .eslintrc.json 
1

bun

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

这将为您的 eslint.config.js 文件创建一个起点，但不保证立即工作而无需进一步修改。但是，它将自动完成本指南中提到的大部分转换工作。

开始使用扁平配置文件

自 ESLint v9.0.0 以来，扁平配置文件格式已成为默认配置文件格式。您可以开始使用扁平配置文件格式，而无需任何其他配置。

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

配置格式之间未更改的内容

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

配置规则的语法。
配置处理器的语法。
CLI，除了 CLI 标志更改中指出的标志更改之外。
全局变量的配置方式相同，但在不同的属性上（请参阅配置语言选项）。

配置格式之间的主要差异

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

导入插件和自定义解析器

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

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

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

// .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

在扁平配置中，您将像这样执行相同的操作

// 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

自定义解析器

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

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

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

// .eslintrc.js

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

在扁平配置中，您将像这样执行相同的操作

// 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

处理器

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

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

以带有处理器的自定义插件为例

// 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 中，您将配置如下

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

ESLint 还会自动添加以下等效项

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

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

// 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 处理器不是由扁平配置自动添加的，因此您还需要指定一个额外的配置元素

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

基于 Glob 的配置

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

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

eslintrc 示例

例如，此 eslintrc 文件适用于放置它的目录及其子目录中的所有文件

// .eslintrc.js

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

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

// .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

对于扁平配置，这是一个具有默认 glob 模式的配置

// 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

一个扁平配置示例配置，支持用于不同 glob 模式的多个配置

// 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

配置语言选项

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

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

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

// .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

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

// 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` 配置注释

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

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

// 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 将被识别为全局标识符。

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

// 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

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

// 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

预定义和可共享配置

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

"eslint:recommended"：ESLint 推荐的规则。
"eslint:all"：ESLint 附带的所有规则。

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

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

npm

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

yarn

yarn add --dev @eslint/js
1

pnpm

pnpm add --save-dev @eslint/js
1

bun

bun add --dev @eslint/js
1

您可以将每个配置添加到导出的数组中，或从中公开特定规则。您必须使用扁平配置导入本地配置文件和 npm 包配置的模块。

例如，这是一个使用内置 eslint:recommended 配置的 eslintrc 文件

// .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 包的可共享配置

// .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

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

// 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 使用配置对象之前对其进行修改。例如，您可能希望某个配置对象仅适用于您的测试文件

// 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

在扁平配置中使用 eslintrc 配置

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

npm

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

yarn

yarn add --dev @eslint/eslintrc
1

pnpm

pnpm add --save-dev @eslint/eslintrc
1

bun

bun add --dev @eslint/eslintrc
1

然后，导入 FlatCompat 并创建一个新实例以转换现有的 eslintrc 配置。例如，如果 npm 包 eslint-config-my-config 是 eslintrc 格式，您可以编写此代码

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 插入到扁平配置数组中。

有关 FlatCompat 类的更多信息，请参阅包 README。

忽略文件

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

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

例如，这是一个 .eslintignore 示例，您可以将其与 eslintrc 配置一起使用

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

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

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

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

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 的文件。

Linter 选项

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

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

例如，这是一个启用了 linter 选项的 eslintrc 文件

// .eslintrc.js

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

这是扁平配置中的相同选项

// 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 标志不再受扁平配置文件格式支持

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

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

`--rulesdir`

--rulesdir 标志用于从指定目录加载其他规则。使用扁平配置时，不再支持此功能。您可以改为创建一个包含您配置中直接拥有的本地规则的插件，如下所示

// 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 标志用于指定当命令行上传递目录（例如 npx eslint .）时，ESLint 应搜索的其他文件扩展名。使用扁平配置时，不再支持此功能。相反，直接在您的配置中指定您希望 ESLint 搜索的文件模式。例如，如果您以前使用 --ext .ts,.tsx，那么您将需要更新您的配置文件，如下所示

// 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 键来确定应检查哪些文件。

`--resolve-plugins-relative-to`

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

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

不再支持 `package.json` 配置

使用 eslintrc，可以使用 package.json 文件，使用 eslintConfig 键来配置 ESLint。

使用扁平配置，不再可以使用 package.json 文件来配置 ESLint。您需要将您的配置移动到单独的文件中。

其他更改

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

root 选项不再存在。（扁平配置文件就像设置了 root: true 一样。）
files 选项不能再是单个字符串，它必须是一个数组。
sourceType 选项现在支持新值 "commonjs"（.eslintrc 也支持它，但从未记录在案）。

扁平配置文件的 TypeScript 类型

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

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

Visual Studio Code 支持

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

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

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

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

进一步阅读

编辑此页面

配置迁移指南

迁移您的配置文件

npm

yarn

pnpm

bun

开始使用扁平配置文件

配置格式之间未更改的内容

配置格式之间的主要差异

导入插件和自定义解析器

自定义解析器

处理器

基于 Glob 的配置

eslintrc 示例

配置语言选项

eslint-env 配置注释

预定义和可共享配置

npm

yarn

pnpm

bun

在扁平配置中使用 eslintrc 配置

npm

yarn

pnpm

bun

忽略文件

Linter 选项

CLI 标志更改

--rulesdir

--ext

--resolve-plugins-relative-to

不再支持 package.json 配置

其他更改

扁平配置文件的 TypeScript 类型

Visual Studio Code 支持

进一步阅读

`eslint-env` 配置注释

`--rulesdir`

`--ext`

`--resolve-plugins-relative-to`

不再支持 `package.json` 配置