插件迁移到扁平配置

从 ESLint v9.0.0 开始，默认配置系统将是新的扁平配置系统。为了使你的插件能够使用扁平配置文件，你需要对现有插件进行一些更改。

¥Beginning in ESLint v9.0.0, the default configuration system will be the new flat config system. In order for your plugins to work with flat config files, you’ll need to make some changes to your existing plugins.

推荐的插件结构

¥Recommended Plugin Structure

为了更轻松地在扁平配置系统中使用插件，建议你将现有插件入口点切换为如下所示：

¥To make it easier to work with your plugin in the flat config system, it’s recommended that you switch your existing plugin entrypoint to look like this:

const plugin = {
    meta: {},
    configs: {},
    rules: {},
    processors: {}
};

// for ESM
export default plugin;

// OR for CommonJS
module.exports = plugin;
1
2
3
4
5
6
7
8
9
10
11
12

在进行本页讨论的其他更改时，此结构提供了最大的灵活性。

¥This structure allows the most flexibility when making other changes discussed on this page.

添加插件元信息

¥Adding Plugin Meta Information

使用旧的 eslintrc 配置系统，ESLint 可以从包名称中提取有关插件的信息，但使用扁平配置，ESLint 不再能够访问插件包的名称。要替换丢失的信息，你应该添加至少包含 name 密钥的 meta 密钥，最好是包含 version 密钥，例如：

¥With the old eslintrc configuration system, ESLint could pull information about the plugin from the package name, but with flat config, ESLint no longer has access to the name of the plugin package. To replace that missing information, you should add a meta key that contains at least a name key, and ideally, a version key, such as:

const plugin = {
    meta: {
        name: "eslint-plugin-example",
        version: "1.0.0"
    },
    configs: {},
    rules: {},
    processors: {}
};

// for ESM
export default plugin;

// OR for CommonJS
module.exports = plugin;
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

如果你的插件作为 npm 包发布，则 name 和 version 应与 package.json 文件中的相同；否则，你可以分配任何你想要的值。

¥If your plugin is published as an npm package, the name and version should be the same as in your package.json file; otherwise, you can assign any value you’d like.

如果没有此元信息，你的插件将无法与 --cache 和 --print-config 命令行选项一起使用。

¥Without this meta information, your plugin will not be usable with the --cache and --print-config command line options.

扁平配置的迁移规则

¥Migrating Rules for Flat Config

插件中的 rules 键无需更改。一切工作与旧的 eslintrc 配置系统相同。

¥No changes are necessary for the rules key in your plugin. Everything works the same as with the old eslintrc configuration system.

迁移处理器以实现扁平化配置

¥Migrating Processors for Flat Config

只要你不使用以文件扩展名命名的处理器，就不需要对插件中的 processors 键进行任何更改。如果你有任何 文件扩展名命名的处理器，则必须将名称更新为有效的标识符（数字和字母）。以文件扩展名命名的处理器会自动应用在旧的配置系统中，但在使用扁平配置时不会自动应用。下面是一个以文件扩展名命名的处理器的示例：

¥No changes are necessary for the processors key in your plugin as long as you aren’t using file extension-named processors. If you have any file extension-named processors, you must update the name to a valid identifier (numbers and letters). File extension-named processors were automatically applied in the old configuration system but are not automatically applied when using flat config. Here is an example of a file extension-named processor:

const plugin = {
    configs: {},
    rules: {},
    processors: {

        // no longer supported
        ".md": {
            preprocess() {},
            postprocess() {}
        }
    }
};

// for ESM
export default plugin;

// OR for CommonJS
module.exports = plugin;
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

名称 ".md" 对处理器不再有效，因此必须将其替换为有效标识符，例如 markdown：

¥The name ".md" is no longer valid for a processor, so it must be replaced with a valid identifier such as markdown:

const plugin = {
    configs: {},
    rules: {},
    processors: {

        // works in both old and new config systems
        "markdown": {
            preprocess() {},
            postprocess() {}
        }
    }
};

// for ESM
export default plugin;

// OR for CommonJS
module.exports = plugin;
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

为了使用这个重命名的处理器，你还需要在配置中手动指定它，例如：

¥In order to use this renamed processor, you’ll also need to manually specify it inside of a config, such as:

import example from "eslint-plugin-example";

export default [
    {
        plugins: {
            example
        },
        processor: "example/markdown"
    }
];
1
2
3
4
5
6
7
8
9
10

如果你重命名了以文件扩展名命名的处理器，你应该更新插件的文档以告知用户。

¥You should update your plugin’s documentation to advise your users if you have renamed a file extension-named processor.

迁移扁平配置的配置

¥Migrating Configs for Flat Config

如果你的插件导出的配置引用回你的插件，那么你需要将配置更新为扁平配置格式。作为迁移的一部分，你需要直接在 plugins 键中引用你的插件。例如，以下是名为 eslint-plugin-example 的插件的旧配置系统格式的导出配置：

¥If your plugin is exporting configs that refer back to your plugin, then you’ll need to update your configs to flat config format. As part of the migration, you’ll need to reference your plugin directly in the plugins key. For example, here is an exported config in the old configuration system format for a plugin named eslint-plugin-example:

// plugin name: eslint-plugin-example
module.exports = {
    configs: {

        // the config referenced by example/recommended
        recommended: {
            plugins: ["example"],
            rules: {
                "example/rule1": "error",
                "example/rule2": "error"
            }
        }
    },
    rules: {
        rule1: {},
        rule2: {};
    }
};
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

要迁移到扁平配置格式，你需要将配置移动到推荐插件结构中 plugin 变量定义之后，如下所示：

¥To migrate to flat config format, you’ll need to move the configs to after the definition of the plugin variable in the recommended plugin structure, like this:

const plugin = {
    configs: {},
    rules: {},
    processors: {}
};

// assign configs here so we can reference `plugin`
Object.assign(plugin.configs, {
    recommended: {
        plugins: {
            example: plugin
        },
        rules: {
            "example/rule1": "error",
            "example/rule2": "error"
        }
    }
})

// for ESM
export default plugin;

// OR for CommonJS
module.exports = plugin;
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

然后，你的用户可以使用此导出的配置，如下所示：

¥Your users can then use this exported config like this:

import example from "eslint-plugin-example";

export default [

    // use recommended config
    example.configs.recommended,

    // and provide your own overrides
    {
        rules: {
            "example/rule1": "warn"
        }
    }
];
1
2
3
4
5
6
7
8
9
10
11
12
13
14

你应该更新你的文档，以便你的插件用户知道如何引用导出的配置。

¥You should update your documentation so your plugin users know how to reference the exported configs.

迁移扁平配置环境

¥Migrating Environments for Flat Config

扁平配置不再支持环境，因此我们建议将你的环境转换为导出的配置。例如，假设你导出一个 mocha 环境，如下所示：

¥Environments are no longer supported in flat config, and so we recommend transitioning your environments into exported configs. For example, suppose you export a mocha environment like this:

// plugin name: eslint-plugin-example
module.exports = {
    environments: {
        mocha: {
            globals: {
                it: true,
                xit: true,
                describe: true,
                xdescribe: true
            }
        }
    },
    rules: {
        rule1: {},
        rule2: {};
    }
};
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

要将此环境迁移到配置中，你需要在 plugin.configs 对象中添加一个新键，该对象具有包含相同信息的扁平配置对象，如下所示：

¥To migrate this environment into a config, you need to add a new key in the plugin.configs object that has a flat config object containing the same information, like this:

const plugin = {
    configs: {},
    rules: {},
    processors: {}
};

// assign configs here so we can reference `plugin`
Object.assign(plugin.configs, {
    mocha: {
        languageOptions: {
            globals: {
                it: "writeable",
                xit: "writeable",
                describe: "writeable",
                xdescribe: "writeable"
            }
        }
    }
})

// for ESM
export default plugin;

// OR for CommonJS
module.exports = plugin;
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

然后，你的用户可以使用此导出的配置，如下所示：

¥Your users can then use this exported config like this:

import example from "eslint-plugin-example";

export default [

    // use the mocha globals
    example.configs.mocha,

    // and provide your own overrides
    {
        languageOptions: {
            globals: {
                it: "readonly"
            }
        }
    }
];
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

你应该更新你的文档，以便你的插件用户知道如何引用导出的配置。

¥You should update your documentation so your plugin users know how to reference the exported configs.

向后兼容性

¥Backwards Compatibility

如果你的插件需要同时适用于新旧配置系统，那么你需要：

¥If your plugin needs to work with both the old and new configuration systems, then you’ll need to:

1. 导出 CommonJS 入口点。旧的配置系统无法加载仅以 ESM 格式发布的插件。如果你的源代码位于 ESM 中，那么你需要使用可以生成 CommonJS 版本的打包程序，并使用 package.json 文件中的 exports 密钥来确保 Node.js 可以找到 CommonJS 版本。

   ¥Export a CommonJS entrypoint. The old configuration system cannot load plugins that are published only in ESM format. If your source code is in ESM, then you’ll need to use a bundler that can generate a CommonJS version and use the exports key in your package.json file to ensure the CommonJS version can be found by Node.js.

2. 保留 environments 键。如果你的插件导出自定义环境，你应该保持它们原样，并导出如上所述的等效扁平配置。当 ESLint 在扁平配置模式下运行时，environments 键将被忽略。

   ¥Keep the environments key. If your plugin exports custom environments, you should keep those as they are and also export the equivalent flat configs as described above. The environments key is ignored when ESLint is running in flat config mode.

3. 导出 eslintrc 和 flat 配置。configs 密钥仅在使用配置时才会验证，因此你可以在 configs 密钥中提供两种格式的配置。我们建议你在旧格式配置后附加 -legacy，以明确这些配置将来将不受支持。例如，如果你的主配置名为 recommended 并且采用扁平配置格式，那么你还可以有一个名为 recommended-legacy 的配置，它是 eslintrc 配置格式。

   ¥Export both eslintrc and flat configs. The configs key is only validated when a config is used, so you can provide both formats of configs in the configs key. We recommend that you append older format configs with -legacy to make it clear that these configs will not be supported in the future. For example, if your primary config is called recommended and is in flat config format, then you can also have a config named recommended-legacy that is the eslintrc config format.

进阶读物

¥Further Reading

• 扁平配置文件格式博客文章概述

  ¥Overview of the flat config file format blog post

• 新配置系统的 API 使用博客文章

  ¥API usage of new configuration system blog post

• 新配置系统博客文章的背景

  ¥Background to new configuration system blog post