插件迁移到扁平配置

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

添加插件元信息

使用旧的 eslintrc 配置系统，ESLint 可以从包名称中提取有关插件的信息，但使用扁平配置，ESLint 不再有权访问插件包的名称。为了替换丢失的信息，您应该添加一个包含至少一个 name 键的 meta 键，理想情况下，还应该有一个 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 版本的打包器，并使用 exports 键在您的 package.json 文件中，以确保 Node.js 可以找到 CommonJS 版本。
保留 environments 键。 如果您的插件导出自定义环境，您应该保留它们原样，并同时导出如上所述的等效扁平配置。当 ESLint 在扁平配置模式下运行时，environments 键将被忽略。
同时导出 eslintrc 和扁平配置。 configs 键仅在配置被使用时才会被验证，因此您可以在 configs 键中提供两种格式的配置。我们建议您在旧格式配置后附加 -legacy，以明确表示这些配置在未来将不受支持。例如，如果您的主要配置名为 recommended 并且是扁平配置格式，那么您还可以有一个名为 recommended-legacy 的配置，它是 eslintrc 配置格式。

延伸阅读

编辑此页