版本

配置迁移指南

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

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

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

迁移您的配置文件

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

npx @eslint/migrate-config .eslintrc.json

这将为您的 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
};

在扁平化配置中，您可以这样执行相同的操作

// 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"
        }
    }
];

自定义解析器

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

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

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

// .eslintrc.js

module.exports = {
    // ...other config
    parser: "@babel/eslint-parser",
    // ...other config
};

在扁平化配置中，您可以这样执行相同的操作

// eslint.config.js

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

export default [
    {
        // ...other config
        languageOptions: {
            parser: babelParser
        }
        // ...other config
    }
];

处理器

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

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

例如使用带有处理器的自定义插件

// node_modules/eslint-plugin-someplugin/index.js
module.exports = {
    processors: {
        ".md": {
            preprocess() {},
            postprocess() {}
        },
        "someProcessor": {
            preprocess() {},
            postprocess() {}
        }
    }
};

在 eslintrc 中，您将按如下方式配置

// .eslintrc.js
module.exports = {
    plugins: ["someplugin"],
    processor: "someplugin/someProcessor"
};

ESLint 还将自动添加以下内容的等效项

{
     overrides: [{
        files: ["**/*.md"],
        processor: "someplugin/.md"
     }]
}

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

// 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
    }
];

请注意，由于扁平化配置**不会**自动添加 .md 处理器，因此您还需要指定额外的配置元素

{
    files: ["**/*.md"],
    processor: somePlugin.processors[".md"]
}

基于通配符的配置

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

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

eslintrc 示例

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

// .eslintrc.js

module.exports = {
    // ...other config
    rules: {
        semi: ["warn", "always"]
    }
};

此 eslintrc 文件支持使用覆盖的多个配置

// .eslintrc.js

module.exports = {
    // ...other config
    overrides: [
        {
            files: ["src/**/*"],
            rules: {
                semi: ["warn", "always"]
            }
        },
        {
            files:["test/**/*"],
            rules: {
                "no-console": "off"
            }
        }
    ]
};

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

// 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
    }
];

一个支持针对不同通配符模式的多个配置的扁平化配置示例

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

配置语言选项

在 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
}

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

// eslint.config.js

import globals from "globals";

export default [
    {
        languageOptions: {
            ecmaVersion: 2022,
            sourceType: "module",
            globals: {
                ...globals.browser,
                ...globals.node,
                myCustomGlobal: "readonly"
            }
        }
        // ...other config
    }
];

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", () => {
        // ...
    });
});

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

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

// tests/my-file.js

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

describe("unit tests", () => {
    it("should pass", () => {
        // ...
    });
});

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

// eslint.config.js

import globals from "globals";

export default [
    // ...other config
    {
        files: [
            "tests/**"
        ],
        languageOptions: {
            globals: {
                ...globals.mocha
            }
        }
    }
];

预定义和可共享配置

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

  • "eslint:recommended"：ESLint 建议的规则
  • "eslint:all"：ESLint 附带的所有规则

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

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

npm install @eslint/js --save-dev

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

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

// .eslintrc.js

module.exports = {
    // ...other config
    extends: "eslint:recommended",
    rules: {
        semi: ["warn", "always"]
    },
    // ...other config
}

此eslintrc文件使用内置配置、本地自定义配置以及来自npm包的可共享配置

// .eslintrc.js

module.exports = {
    // ...other config
    extends: ["eslint:recommended", "./custom-config.js", "eslint-config-my-config"],
    rules: {
        semi: ["warn", "always"]
    },
    // ...other config
}

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

// 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
    }
];

请注意，因为您只是导入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"],
    },
];

在扁平化配置中使用 eslintrc 配置

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

npm install @eslint/eslintrc --save-dev

然后，导入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"),
];

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

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

忽略文件

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

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

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

# .eslintignore
temp.js
config/*
# ...other ignored files

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

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

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

export default [
    // ...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的文件。

代码检查工具选项

ESlintrc文件允许您使用noInlineConfig和reportUnusedDisableDirectives属性配置lint器本身。

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

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

// .eslintrc.js

module.exports = {
    // ...other config
    noInlineConfig: true,
    reportUnusedDisableDirectives: true
}

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

// eslint.config.js

export default [
    {
        // ...other config
        linterOptions: {
            noInlineConfig: true,
            reportUnusedDisableDirectives: "warn"
        }
    }
];

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"]
        }

    }
];

--ext

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

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

        // any additional configuration for these file types here
    }
];

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 支持

ESLint v9.x支持已添加到vscode-eslint v3.0.10中。

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

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

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

进一步阅读

编辑此页面
© OpenJS基金会和ESLint贡献者，www.openjsf.org。内容根据MIT许可证授权。
更改语言