插件迁移到扁平配置
从 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;
在进行本页讨论的其他更改时，此结构提供了最大的灵活性。
🌐 This structure allows the most flexibility when making other changes discussed on this page.
添加插件元信息
🌐 Adding Plugin Meta Information
在旧的 eslintrc 配置系统中，ESLint 可以从包名中获取有关插件的信息，但在使用平面配置时，ESLint 不再能够访问插件包的名称。为补充缺失的信息，你应该添加一个 meta 键，该键至少包含一个 name 键，理想情况下还应包含一个 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;
如果你的插件作为 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
每个处理器应指定一个 meta 对象。更多信息，请参见完整文档。
🌐 Each processor should specify a meta object. For more information, see the full documentation.
只要你没有使用以文件扩展名命名的处理器，你的插件中 processors 键不需要其他更改。如果你有任何以文件扩展名命名的处理器，必须将名称更新为有效标识符（数字和字母）。在旧的配置系统中，以文件扩展名命名的处理器会自动应用，但在使用平面配置时不会自动应用。下面是一个以文件扩展名命名的处理器示例：
🌐 No other 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;
处理器的名称 ".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;
为了使用这个重命名的处理器，你还需要在配置中手动指定它，例如：
🌐 In order to use this renamed processor, you’ll also need to manually specify it inside of a config, such as:
import { defineConfig } from "eslint/config";
import example from "eslint-plugin-example";
export default defineConfig([
{
files: ["**/*.md"],
plugins: {
example,
},
processor: "example/markdown",
},
]);
如果你重命名了以文件扩展名命名的处理器，你应该更新插件的文档以告知用户。
🌐 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: {};
}
};
要迁移到扁平配置格式，你需要将配置移到推荐插件结构中 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;
然后，你的用户可以使用此导出的配置，如下所示：
🌐 Your users can then use this exported config like this:
import { defineConfig } from "eslint/config";
import example from "eslint-plugin-example";
export default defineConfig([
// use recommended config and provide your own overrides
{
files: ["**/*.js", "**/*.cjs", "**/*.mjs"],
plugins: {
example,
},
extends: ["example/recommended"],
rules: {
"example/rule1": "warn",
},
},
]);
如果你的配置扩展了其他配置，则可以导出一个数组：
🌐 If your config extends other configs, you can export an array:
const baseConfig = require("./base-config");
module.exports = {
configs: {
extendedConfig: [
baseConfig,
{
rules: {
"example/rule1": "error",
"example/rule2": "error",
},
},
],
},
};
你应该更新你的文档，以便你的插件用户知道如何引用导出的配置。
🌐 You should update your documentation so your plugin users know how to reference the exported configs.
有关更多信息，请参阅完整文档。
🌐 For more information, see the full documentation.
迁移扁平配置环境
🌐 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: {};
}
};
要将此环境迁移到配置中，你需要在 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;
然后，你的用户可以使用此导出的配置，如下所示：
🌐 Your users can then use this exported config like this:
import { defineConfig } from "eslint/config";
import example from "eslint-plugin-example";
export default defineConfig([
{
files: ["**/tests/*.js"],
plugins: {
example,
},
// use the mocha globals
extends: ["example/mocha"],
// and provide your own overrides
languageOptions: {
globals: {
it: "readonly",
},
},
},
]);
你应该更新你的文档，以便你的插件用户知道如何引用导出的配置。
🌐 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:
- 导出一个 CommonJS 入口点。 旧的配置系统无法加载仅以 ESM 格式发布的插件。如果你的源代码是 ESM，那么你需要使用一个能够生成 CommonJS 版本的打包工具，并在你的
package.json文件中使用exports键，以确保 Node.js 可以找到 CommonJS 版本。 - 保留
environments键。 如果你的插件导出自定义环境，你应该保持它们的原样，同时也导出上述所述的等效平面配置。当 ESLint 以平面配置模式运行时，environments键会被忽略。 - 导出 eslintrc 和 flat 配置。
configs键只有在使用配置时才会被验证，因此你可以在configs键中提供两种格式的配置。我们建议在旧格式配置前加上前缀legacy-。例如，如果你的主配置名为recommended并且是 flat 配置格式，那么你也可以有一个名为legacy-recommended的配置，它是 eslintrc 配置格式。如果你不想更新配置名称，也可以在 configs 对象中创建一个带前缀"flat/"的额外条目（例如"flat/recommended"）。更多详情请参见 Legacy Configs 的向后兼容性。
进阶读物
🌐 Further Reading