插件迁移到扁平化配置

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

添加插件元信息

使用旧的 eslintrc 配置系统，ESLint 可以从包名称中提取有关插件的信息，但在扁平化配置中，ESLint 无法再访问插件包的名称。为了替换此缺失的信息，您应该添加一个 meta 键，其中至少包含一个 name 键，理想情况下还包含一个 version 键，例如

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 文件中的相同；否则，您可以分配任何您喜欢的值。

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

为扁平化配置迁移规则

插件中的 rules 键无需更改。所有内容都与旧的 eslintrc 配置系统相同。

为扁平化配置迁移处理器

每个处理器都应指定一个 meta 对象。有关更多信息，请参见完整文档。

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

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

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

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

import example from "eslint-plugin-example";

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

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

为扁平化配置迁移配置

如果您的插件正在导出引用回插件的配置，则需要将配置更新为扁平化配置格式。作为迁移的一部分，您需要在 plugins 键中直接引用您的插件。例如，以下是名为 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 变量的定义之后，如下所示

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

然后，您的用户可以像这样使用此导出的配置

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

如果您的配置扩展其他配置，您可以导出一个数组

const baseConfig = require("./base-config");

module.exports = {
    configs: {
        extendedConfig: [
            baseConfig,
            {
                rules: {
                    "example/rule1": "error",
                    "example/rule2": "error"
                }
            }
        ],
    },
};
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

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

如果您的导出配置是对象，则您的用户可以将其直接插入配置数组；如果您的导出配置是数组，则您的用户应使用扩展运算符 (...) 将数组的项插入配置数组。

这是一个包含对象配置和数组配置的示例

import example from "eslint-plugin-example";

export default [
    example.configs.recommended, // Object, so don't spread
    ...example.configs.extendedConfig, // Array, so needs spreading
];
1
2
3
4
5
6

有关更多信息，请参见完整文档。

为扁平化配置迁移环境

扁平化配置中不再支持环境，因此我们建议将您的环境转换为导出的配置。例如，假设您像这样导出 mocha 环境

// 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 对象中添加一个新的键，该键具有包含相同信息的扁平化配置对象，如下所示

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

然后，您的用户可以像这样使用此导出的配置

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

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

向后兼容性

如果您的插件需要同时与旧配置系统和新配置系统一起使用，则需要

导出一个 CommonJS 入口点。旧的配置系统无法加载仅以 ESM 格式发布的插件。如果您的源代码是 ESM，则需要使用可以生成 CommonJS 版本的打包器，并在 package.json 文件中使用exports 键来确保 Node.js 可以找到 CommonJS 版本。
保留 environments 键。如果您的插件导出自定义环境，则应保留它们，并如上所述导出等效的扁平化配置。当 ESLint 在扁平化配置模式下运行时，会忽略 environments 键。
导出 eslintrc 和扁平化配置。仅当使用配置时才会验证 configs 键，因此您可以在 configs 键中提供两种格式的配置。我们建议您将旧格式的配置附加 -legacy 以明确这些配置将来将不受支持。例如，如果您的主要配置称为 recommended 并且是扁平化配置格式，则您还可以有一个名为 recommended-legacy 的配置，它是 eslintrc 配置格式。

进一步阅读

编辑此页面