ESLint 配置文件名变更与迁移指南

ESLint 作为流行的 JavaScript 代码检查工具，在版本 9.x 中引入了重大的配置系统变更。本文将详细介绍新旧配置文件的区别，以及如何正确迁移到新的配置系统。

配置系统的重大变更

ESLint 9.x 版本对配置文件系统进行了重构，主要变化包括：

1. 引入了全新的扁平化配置系统（Flat Config）
2. 逐步淘汰传统的 .eslintrc.* 格式配置文件
3. 改变了配置文件解析和合并的机制

新旧配置文件对比

传统配置文件（已弃用）

• 文件名示例：.eslintrc.js, .eslintrc.json, .eslintrc.yml
• 支持多级目录中的配置文件合并
• 使用 extends 和 plugins 字段扩展配置

新式扁平化配置

• 文件名应为 eslint.config.js
• 不再支持配置文件自动合并
• 采用显式导入和组合配置的方式

常见问题解析

当用户在 ESLint 9.x 中使用旧式配置文件时，可能会遇到以下错误：

TypeError [ERR_IMPORT_ASSERTION_TYPE_MISSING]

这是因为新版本默认期望使用扁平化配置系统。要临时使用旧式配置，可以设置环境变量：

ESLINT_USE_FLAT_CONFIG=false npx eslint -c ~/.eslintrc.json file.js

但会收到警告提示：

ESLintRCWarning: You are using an eslintrc configuration file, which is deprecated...

迁移建议

1. 立即行动：虽然旧式配置在 9.x 中仍可用，但将在 10.0.0 版本中完全移除

2. 配置文件重命名：将现有配置文件重命名为 eslint.config.js

3. 配置结构调整：参考官方迁移指南调整配置语法

4. 环境变量设置：在过渡期可设置 ESLINT_USE_FLAT_CONFIG=false 保持兼容

最佳实践

• 避免在用户主目录(~)放置全局配置文件
• 优先使用项目根目录下的 eslint.config.js
• 对于团队项目，确保所有成员使用相同版本的 ESLint
• 在 CI/CD 流程中明确指定配置系统类型

通过遵循这些指南，开发者可以顺利过渡到 ESLint 的新配置系统，避免常见的配置错误和兼容性问题。