ESLint 的新配置系统，第 3 部分：开发者预览

在我之前的帖子中，我解释了使用新的“扁平化”配置系统的基本概念。新的配置系统尚未与 CLI 集成，因为我们还在进行更多的内部测试，但我们确实希望给 ESLint 社区一个机会，在我们将其纳入 CLI 的过程中尝试扁平化配置。因此，ESLint v8.21.0 在我们开发扁平化配置的同时，提供了几种方式来尝试它。请记住，本文中提到的所有内容都是实验性的，我们非常希望在你尝试时收到你的反馈。

🌐 In my previous post, I explained the fundamental concepts of using the new “flat” config system. The new config system isn’t yet tied into the CLI while we do more internal testing, but we did want to give the ESLint community a chance to experiment with flat config while we work on incorporating it into the CLI. So ESLint v8.21.0 incorporates several ways to try out flat config as we work on it. Please keep in mind that everything mentioned in this post is experimental and we would love your feedback as you try it out.

使用 Linter 类的平面配置

🌐 Using flat config with the Linter class

如果你当前正在使用 eslint 包中的 Linter，可以通过在构造函数上将 configType: "flat" 设置为一个选项来启用扁平配置。示例如下：

🌐 If you are currently using Linter from the eslint package, you can enable flat config by setting configType: "flat" as an option on the constructor. Here’s an example:

const linter = new Linter({ configType: "flat" });

const messages = linter.verify("new Map()", {
    languageOptions: {
        ecmaVersion: 5,
        sourceType: "script"
    },
    rules: {
        "no-undef": "error"
    }
}, "filename.js");
1
2
3
4
5
6
7
8
9
10
11

当你将 configType: "flat" 作为一个选项传递时，Linter 期望传递给 verify() 的任何配置对象都采用扁平配置格式。在这个示例中，verify() 的第二个参数是一个扁平配置对象（你可以传递单个对象或对象数组）。对 verify() 的任何调用都会假设正在检查的文本是一个以 .js 结尾的 JavaScript 文件，但通常最好将明确的文件名作为第三个参数传入。

🌐 When you pass configType: "flat" as an option, Linter expects that any configuration objects that are passed to verify() will be in flat config format. In this example, the second argument to verify() is a flat config object (you can pass either a single object or an array of objects). Any call to verify() will assume that the text being linted is a JavaScript file whose filename ends with .js, but it’s always a good idea to pass in an explicit filename as the third argument.

虽然这个基本情况无论你使用哪个配置系统都适用，但还是有一些重要的区别：

🌐 While this base case works the same regardless of which config system you’re using, there are some important differences:

• defineRule()、defineRules() 和 defineParser() 现在会抛出错误。运行时插件（在我之前的帖子中讨论过）使这些方法变得过时。
• getRules() 也会抛出错误。此方法会根据调用时间返回不同的数据，因此不能与扁平配置一起使用。

使用 ESLint 类的平面配置

🌐 Using flat config with the ESLint class

在实现平面配置时，我们发现创建一个选项来像对 Linter 那样在配置系统之间切换会太困难。相反，我们创建了一个 FlatESLint 类，它封装了 ESLint 中的所有现有功能，但使用平面配置而不是 eslintrc。FlatESLint 类仅用于功能预览；一旦我们永久切换到平面配置，当前的 ESLint 类将被删除，FlatESLint 将被重命名为 ESLint。

🌐 While implementing flat config we discovered that it would be too difficult to create an option to switch between config systems like we did for Linter. Instead, we created a FlatESLint class that encapsulates all of the existing functionality in ESLint but uses flat config instead of eslintrc. The FlatESLint class is intended only as a preview of functionality; once we switch over to flat config permanently, the current ESLint class will be deleted and FlatESLint will be renamed to ESLint.

目前，你可以通过 use-at-your-own-risk 入口访问 FlatESLint，如下所示：

🌐 For now, you can access FlatESLint through the use-at-your-own-risk entrypoint, like this:

// ESM
import pkg from "eslint/use-at-your-own-risk";
const { FlatESLint } = pkg;

// CommonJS
const { FlatESLint } = require("eslint/use-at-your-own-risk");
1
2
3
4
5
6

之后，你可以以与 ESLint 相同的方式使用 FlatESLint，例如：

🌐 After that, you can use FlatESLint in the same way as ESLint, such as:

const eslint = new FlatESLint({
    cwd: originalDir,
    overrideConfigFile: "other.config.js"
});
const results = await eslint.lintText("foo");
1
2
3
4
5

与 Linter 一样，FlatESLint 和 ESLint 之间也有一些值得指出的差异：

🌐 As with Linter, there are a few differences between FlatESLint and ESLint worth pointing out:

1. FlatESLint 中尚未实现缓存，因此 cache: true 会抛出错误。
2. useEslintrc 选项已被移除。如果你想在不指定备用配置文件的情况下避免自动加载 eslint.config.js，请设置 overrideConfigFile: true。
3. envs 选项已被移除。
4. resolvePluginsRelativeTo 选项已被移除。
5. rulePaths 选项已被移除。自定义规则必须直接通过配置添加。

使用扁平配置和 RuleTester 类测试规则

🌐 Testing rules with flat config and the RuleTester class

类似于 ESLint 类，没有简单的方法提供在 eslintrc 和 flat 配置之间切换的选项，因此我们创建了一个单独的 FlatRuleTester 类。同样类似于 ESLint，FlatRuleTester 类是临时的，一旦我们完全切换到 flat 配置，它最终将被重命名为 RuleTester。你可以这样访问 FlatRuleTester：

🌐 Similar to the ESLint class, there was no easy way to provide an option to switch between eslintrc and flat config, so we created a separate FlatRuleTester class. Also similar to ESLint, the FlatRuleTester class is temporary and will eventually be renamed RuleTester once we have switched completely over to flat config. You can access FlatRuleTester like this:

// ESM
import pkg from "eslint/use-at-your-own-risk";
const { FlatRuleTester } = pkg;

// CommonJS
const { FlatRuleTester } = require("eslint/use-at-your-own-risk");
1
2
3
4
5
6

任何可以在 RuleTester 中指定 eslintrc 配置的地方，在 FlatRuleTester 中都需要是平面配置。以下是一些示例：

🌐 Any place where you could specify an eslintrc config in RuleTester needs to be a flat config in FlatRuleTester. Here are some examples:

const ruleTester = new FlatRuleTester({
    languageOptions: {
        ecmaVersion: 5,
        sourceType: "script"
    }
});

ruleTester.setDefaultConfig({
    languageOptions: {
        ecmaVersion: 5,
        sourceType: "script"
    }
});
1
2
3
4
5
6
7
8
9
10
11
12
13

在单独测试中，你可以在每个测试中直接使用 languageOptions：

🌐 In individual tests, you can use languageOptions directly in each test:

ruleTester.run("my-rule", rule, {
    valid: [
        {
            code: "var test = 'foo'",
            languageOptions: {
                sourceType: "script"
            }
        },
        {
            code: "var test2 = 'bar'",
            languageOptions: {
                globals: { test: true }
            }
        }
    ],
    invalid: [
        {
            code: "bar",
            languageOptions: {
                sourceType: "script"
            },
            errors: 1
        }
    ]
});
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

使用 FlatRuleTester 时需要注意的一些事项：

🌐 Some things to keep in mind when using FlatRuleTester:

1. 默认的 ecmaVersion 现在是 "latest"，所以如果你在测试中没有指定 ecmaVersion，可能会存在不兼容，因为 eslintrc 的默认 ecmaVersion 是 5。
2. 默认的 sourceType 现在是 "module"，所以如果你在测试中没有指定 sourceType，可能会存在不兼容，因为 eslintrc 的默认 sourceType 是 "script"。这主要在处理全局作用域中的变量时出现。

结论

🌐 Conclusion

我们认为新的配置系统将为 ESLint 用户带来极佳的体验，但为了实现这一点，我们必须确保 ESLint 生态系统已经为这些更改做好准备。这就是为什么我们准备了这个开发者预览版，让我们所有的插件、自定义规则、解析器和可共享配置的作者能够提前了解他们的包将在新配置系统中的运行情况。这是你提供反馈的机会，并帮助解决平面配置中的任何不兼容或问题。

🌐 We think that the new config system will be a great experience for ESLint users, but in order for that to happen, we have to make sure that the ESLint ecosystem is ready for these changes. That’s why we’ve put together this developer preview to let all of our plugin, custom rule, parser, and shareable config authors get an early look at how their packages will work in the new config system. This is your opportunity to give us your feedback and help work through any incompatibilities or problems with flat config.

请尝试使用平铺配置与你的软件包，并通过发起讨论告诉我们进展，或者如果有问题，可以到Discord #developers 通道咨询，或者如果发现问题，请提交问题。

🌐 Please try out flat config with your packages and let us know how it goes by starting a discussion or stopping by the Discord #developers channel if you have questions or opening an issue if you discover a problem.

我们感谢你的帮助和反馈！

🌐 We appreciate your help and feedback!