介绍 ESLint 兼容性工具

ESLint v9.0.0 的发布带来了新配置系统的推出，同时也对规则 API进行了一系列更改。这些更改是为了让 ESLint 为实现语言插件做好准备，这将使 ESLint 能够原生地检查除 JavaScript 之外的其他语言。因此，插件作者需要更新他们的规则以适用于 v9.0.0，不幸的是，这意味着你依赖的一些插件可能还没有更新。这就是我们发布兼容性工具的原因。

🌐 The release of ESLint v9.0.0 brought with it the rollout of the new configuration system, but also a series of changes to the rules API. These changes are necessary in order to prepare ESLint for implementing language plugins, which will give ESLint the ability to natively lint languages other than JavaScript. As a result, plugin authors needed to update their rules to work with v9.0.0, and unfortunately, that means some of the plugins you rely on may not have been updated yet. That’s why we’re releasing the compatibility utilities.

如何判断兼容性工具是否有帮助

🌐 How to know if the compatibility utilities will help

如果在运行 ESLint 时遇到以下任何错误，这些工具可能会有所帮助：

🌐 These utilities may help if you encounter any of the following errors while running ESLint:

TypeError: context.getScope is not a function
TypeError: context.getAncestors is not a function
TypeError: context.markVariableAsUsed is not a function
TypeError: context.getDeclaredVariables is not a function
1
2
3
4

这些错误意味着插件规则尚未更新到最新的 ESLint 规则 API。

🌐 These errors mean that the plugin rules have not been updated to the latest ESLint rule API.

使用兼容性工具

🌐 Using the compatibility utilities

首先，使用 npm 或任何兼容 npm 的命令行工具安装 @eslint/compat 包：

🌐 First, install the @eslint/compat package using npm or any npm-compatible CLI:

npm install @eslint/compat -D
# or
yarn add @eslint/compat -D
# or
pnpm install @eslint/compat -D
# or
bun install @eslint/compat -D
1
2
3
4
5
6
7

然后，在你的 eslint.config.js 文件中使用 fixupPluginRules() 函数将插件封装在兼容层中：

🌐 Then, use the fixupPluginRules() function in your eslint.config.js file to wrap the plugin in a compatibility layer:

// eslint.config.js
import { fixupPluginRules } from "@eslint/compat";
import example from "eslint-plugin-example";

export default [
    {
        plugins: {
            example: fixupPluginRules(example)
        }
    },

    // other config
];
1
2
3
4
5
6
7
8
9
10
11
12
13

之后，该插件应该会按预期工作。

🌐 After that, the plugin should work as expected.

修复导入的配置

🌐 Fixing an imported configuration

如果你正在从引用插件的另一个包导入扁平样式配置，你可以使用 fixupConfigRules() 函数来封装找到的所有插件，像这样：

🌐 If you are importing a flat-style configuration from another package that references plugins, you can use the fixupConfigRules() function to wrap all of the plugins found, like this:

// eslint.config.js
import { fixupConfigRules } from "@eslint/compat";
import recommended from "eslint-plugin-example/configs/recommended.js";

export default [

    ...fixupConfigRules(recommended)

    // other config
];
1
2
3
4
5
6
7
8
9
10

fixupConfigRules() 函数既接受单个对象，也接受对象数组，以便轻松更新你正在使用的任何配置。

🌐 The fixupConfigRules() function accepts both a single object and an array of objects to easily update any configuration you’re using.

与 FlatCompat 一起使用

🌐 Using with FlatCompat

如果你正在使用 @eslint/eslintrc 包中的 FlatCompat，你可能无法访问 eslintrc 风格配置中引用的每个插件。在这种情况下，你可以使用 fixupConfigRules() 函数来封装所有插件，如下面的示例所示：

🌐 If you are using FlatCompat from the @eslint/eslintrc package, you may not be able to access each of the plugins that are referenced inside of an eslintrc-style configuration. In that case, you can use the fixupConfigRules() function to wrap all plugins, as in this example:

// eslint.config.js
import { fixupConfigRules } from "@eslint/compat";
import { FlatCompat } from "@eslint/eslintrc";

const flatCompat = new FlatCompat();

export default [

    ...fixupConfigRules(
        flatCompat.extends("my-config")
    )

    // other config
];
1
2
3
4
5
6
7
8
9
10
11
12
13
14

虽然这个例子展示了如何使用 fixupConfigRules() 与 extends() 方法，但 FlatCompat 上的任何方法都可行。

🌐 While this example shows how to use fixupConfigRules() with the extends() method, any method on FlatCompat works.

结论

🌐 Conclusion

新配置系统的一个好处是，它使我们能够修补尚未被其维护者更新的插件和配置。我们知道迁移到 ESLint v9.0.0 并发现你的配置无法使用可能会令人沮丧，这就是为什么我们致力于提供像 @eslint/eslintrc 和 @eslint/compat 这样的包来帮助过渡的原因。

🌐 One of the benefits of the new configuration system is that it allows us the ability to patch plugins and configs that haven’t yet been updated by their maintainers. We know it can be frustrating to migrate to ESLint v9.0.0 and have your configuration not work, and that’s why we’re committed to providing packages like @eslint/eslintrc and @eslint/compat to help aid the transition.