ESLint v9.0 于 2024 年发布，将平面配置系统 (eslint.config.js) 设为默认值，取代了已使用十多年的旧版 .eslintrc 格式。本迁移指南涵盖了完整的迁移过程、新概念和实际示例。
为什么采用扁平化配置？
遗留的 .eslintrc 系统存在几个问题：配置级联使行为变得不可预测，基于目录的解析很复杂，JSON/YAML 缺乏对函数和注释的支持，以及难以编写可共享的配置。扁平配置通过单个配置文件、通过 JavaScript 数组的显式组合、简化的插件解析和完整的 JavaScript 原生语法来解决这些问题。
平面配置格式
新格式从 eslint.config.js 导出配置对象数组：
import js from "@eslint/js";
import typescript from "typescript-eslint";
export default [
js.configs.recommended,
...typescript.configs.recommended,
{
files: ["src/**/*.ts"],
rules: {
"@typescript-eslint/no-unused-vars": "error",
},
},
{
ignores: ["dist/**", "node_modules/**"],
},
];
每个配置对象都可以指定 files （要应用到哪些文件）、ignores （要排除哪些文件）、rules、plugins、languageOptions 和 linterOptions。 ignores 键替换 .eslintignore。
迁移步骤
转换现有 .eslintrc 项目遵循简单的模式：
| 传统概念 | 等价平面配置 |
|---|---|
| 占位符_0 | 占位符_1 |
| 占位符_0 | 占位符_1 |
| 占位符_0 | 占位符_1 |
| 占位符_0 | 配置数组组成 |
plugins（字符串） | 导入的插件对象 |
| 占位符_0 | 带有 files 的多个配置对象 |
| 占位符_0 | 配置对象中的 ignores |
// Before: .eslintrc.json
// { "env": { "browser": true }, "extends": ["eslint:recommended"] }
// After: eslint.config.js
import globals from "globals";
import js from "@eslint/js";
export default [
js.configs.recommended,
{
languageOptions: { globals: globals.browser },
},
];
TypeScript 集成
typescript-eslint v7+ 提供一流的平面配置支持：
import tseslint from "typescript-eslint";
export default tseslint.config({
files: ["src/**/*.ts"],
languageOptions: {
parserOptions: { project: true },
},
rules: {
"@typescript-eslint/no-floating-promises": "error",
},
});
tseslint.config() 帮助器提供配置对象的类型检查并简化 TypeScript 感知的 linting 设置。
插件兼容性
平面配置中的插件作为对象导入，而不是作为字符串引用：
import react from "eslint-plugin-react";
export default [
{
files: ["src/**/*.jsx"],
plugins: { react },
rules: {
"react/jsx-uses-react": "error",
},
},
];
对于尚未更新平面配置的遗留插件，请使用 @eslint/compat 的 fixupPluginRules 包装器。 FlatCompat 实用程序有助于在增量迁移期间桥接旧版 extends 链。
性能改进
与传统的 O(n) 级联系统相比，扁平配置实现了 O(1) 配置分辨率。对于大型 monorepos，这意味着 linting 速度显着加快。 ESLint v9 中的额外缓存改进进一步减少了 CI 管道中的 lint 时间。
CI配置
# .github/workflows/lint.yml
jobs:
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
- run: npm ci
- run: npx eslint src/ --cache
常见的迁移陷阱
注意缺少 @eslint/js 预设（它提供 eslint:recommended）、围绕 env 替换的混淆（使用 globals 包）以及适用于所有文件的空配置对象。故障排除时使用 --debug 标志：npx eslint --debug src/。
结论
迁移到平面配置可以简化 ESLint 设置、提高性能并提供更易于维护的配置格式。最初的迁移工作通过更清晰的配置组合、更快的 linting 和更好的工具集成获得了回报。从单个项目开始，验证输出是否与您的旧配置相匹配，然后在您的代码库中推广。