版本

配置迁移指南

本指南概述了如何将您的 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 属性配置 linter 本身。

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

例如，以下是一个启用了 linter 选项的 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 许可证 获得许可。
更改语言