插件迁移至扁平化配置

从 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 配置格式。

进一步阅读

编辑此页面