介绍 ESLint 配置迁移工具

我们听到你的反馈了：ESLint 用户没有升级到 ESLint v9.x 的最大原因之一是迁移配置文件似乎既困难又复杂。一些插件支持平面配置和 ESLint v9.x 的规则 API，而有些则不支持。有时你需要使用 FlatCompat，有时你需要使用 兼容性工具。虽然我们在 迁移指南 中尽可能涵盖了相关内容，但逐步检查你的配置并进行必要的更改仍然可能需要一些时间。

🌐 We’ve heard you: One of the biggest reasons ESLint users haven’t upgraded to ESLint v9.x is migrating a configuration file seems difficult and complicated. Some plugins support flat config and the ESLint v9.x rule APIs and some don’t. Sometimes you need to use FlatCompat and sometimes you need to use the compatibility utilities. While we cover as much as we can in the migration guide, it can take time to walk through your configuration and make the necessary changes.

这就是为什么我们很高兴地宣布发布 ESLint 配置迁移工具。该工具旨在将 .eslintrc.* 文件转换为 eslint.config.js 文件，包括：

🌐 That’s why we’re excited to announce the release of the ESLint Configuration Migrator. This utility is designed to translate .eslintrc.* files into eslint.config.js files, including:

• .eslintrc、.eslintrc.json、.eslintrc.yml 和 .eslintrc.yaml 文件的 1 对 1 迁移。
• 合理迁移简单的 .eslintrc.js、.eslintrc.cjs 和 .eslintrc.mjs 文件。（如果你使用变量来构建配置，这些文件通常需要进行编辑）。
• 将 .eslintignore 模式自动包含到你的新配置文件中。
• 在必要时自动使用 FlatCompat。
• 在必要时自动使用兼容性工具。

重要: 这个版本的实用程序只处理最简单的 JavaScript 配置文件（.eslintrc.js、.eslintrc.cjs、.eslintrc.mjs）。它的工作原理是评估文件然后迁移计算出的配置。因此，它不会保留文件中的任何逻辑。我们希望在将来的版本中添加此功能。

使用配置迁移器

🌐 Using the configuration migrator

你可以直接从 npm 使用配置迁移工具，而无需通过 npx 或类似命令安装它。将要转换的 .eslintrc.* 文件的位置传递进去，如下所示：

🌐 You can use the configuration migrator directly from npm without installing it via npx or similar commands. Pass the location of the .eslintrc.* file to convert, like this:

npx @eslint/migrate-config .eslintrc.json
# or
yarn dlx @eslint/migrate-config .eslintrc.json
# or
pnpm dlx @eslint/migrate-config .eslintrc.json
# or
bunx @eslint/migrate-config .eslintrc.json
1
2
3
4
5
6
7

默认情况下，此命令将输出一个 eslint.config.mjs 文件。如果你希望改为输出 CommonJS 文件，请添加 --commonjs 标志：

🌐 By default, this command will output a eslint.config.mjs file. If you’d like to output a CommonJS file instead, add the --commonjs flag:

npx @eslint/migrate-config .eslintrc.json --commonjs
# or
yarn dlx @eslint/migrate-config .eslintrc.json --commonjs
# or
pnpm dlx @eslint/migrate-config .eslintrc.json --commonjs
# or
bunx @eslint/migrate-config .eslintrc.json --commonjs
1
2
3
4
5
6
7

限制

🌐 Limitations

配置迁移工具的目标是减少你首次使用时遇到错误的可能性，因此它会积极使用 FlatCompat 和兼容性工具。这意味着生成的配置文件可能不是最优的，你可能可以自己简化它。

🌐 The goal of the configuration migrator is to reduce the likelihood of running into errors when you use it for the first time, and as a result, it aggressively employs FlatCompat and the compatibility utilities. This means that the generated configuration file may not be optimal and you may be able to simplify it yourself.

生成配置文件后，你应查看以下内容：

🌐 After generating a configuration file, you should review the following:

• 有没有更新版本的插件？ 有可能某个插件已经发布了新版本，可以完全支持 ESLint v9.x 本身，而不需要任何兼容性处理。最好始终升级到你使用插件的最新版本。
• 你在其他目录中有 .eslintrc.* 配置文件吗？ 新的配置系统不会合并来自祖级目录的配置文件。如果你使用 .eslintrc.* 文件来覆盖特定目录中的配置，你需要将这些配置移动到你的主 eslint.config.* 文件中。
• 你当时使用了 --ext CLI 标志吗？ 如果是这样，你需要在你的配置文件中创建一个条目以匹配你在命令行上传递的文件扩展名。

生成的配置文件可能在不进行某些修改的情况下无法正常工作，但它应该能让你非常接近所需的效果。

🌐 It’s possible that the generated configuration file won’t work without some modification, but it should get you very close.

结论

🌐 Conclusion

当我们发布 ESLint v9.x 时，我们认为提供配置迁移指南能够帮助大多数用户顺利过渡到新的配置系统。不幸的是，我们没有预料到大家在这个过程中会遇到的所有挑战。我们希望配置迁移工具能够让未来的迁移过程更加轻松。由于人们配置 ESLint 的方式各不相同，在迁移后让每一个配置文件 100% 正常工作是不可能的，但我们认为这个工具应该可以避免大多数繁琐的转换步骤，从而让你更快地在 ESLint v9.x 中运行起来。

🌐 When we released ESLint v9.x, we thought providing the configuration migration guide would get most users through the transition to the new configuration system. Unfortunately, we didn’t anticipate all of the challenges that folks would encounter along the way. We hope that the configuration migrator makes this transition a lot easier going forward. Getting every config file to work 100% after migration is impossible due to the various ways that people configure ESLint, but we think that this tool should avoid most tedious translation steps to get you up and running in ESLint v9.x faster.