ESLint 新版 Flat Config 实战：团队代码风格统一，从这一份配置开始

开篇

团队开发里最消磨精力的事之一，就是 Code Review 时反复纠结格式问题：

• 有人用 var 有人用 const
• 有人写单引号有人写双引号
• 有人缩进 2 格有人缩进 4 格
• 有人语句结尾加分号有人不加

这些问题不影响代码运行，但严重拉低可读性和协作效率。ESLint 就是解决这类问题的标准答案------ 它是前端工程化的基石，能强制团队写出风格一致、质量可控的代码。

随着 ESLint 进入 9.x+ 时代，官方正式主推 Flat Config（扁平配置） ，也就是 eslint.config.mjs 格式，替代了传统的 .eslintrc.js。本文就基于最新的 Flat Config 写法，从 0 到 1 拆解一份可直接落地的 ESLint 配置。

一、为什么你需要 ESLint？

在讲配置之前，先明确它的核心价值：

1. 统一代码风格：全团队同一种写法，任何人的代码看起来都像一个人写的
2. 提前发现错误：比如未定义变量、废弃语法、作用域问题，在开发阶段就拦截
3. 提升 Review 效率：不用再纠结格式，专注业务逻辑本身
4. 降低维护成本：规范的代码可读性更强，新人上手更快

二、新版 Flat Config 与旧版的区别

很多人接触 ESLint 最早是 .eslintrc.js 格式，现在官方主推的 Flat Config 有几个核心变化：

• 配置文件 ：固定为 eslint.config.mjs，不再是多种后缀并存
• 配置格式：默认导出一个数组，每一项是一个配置块，逻辑更清晰
• 模块语法 ：原生 ESM 规范，用 import/export，不再用 module.exports
• 插件引入：直接导入插件对象，不再是字符串名称
• 继承方式：通过展开配置对象实现，不再是字符串数组

简单说：新版配置更像写普通 JS 模块，语法更统一，嵌套更少，对 TypeScript 更友好。

三、从零搭建 ESLint 配置

3.1 安装依赖

我们用 pnpm 作为包管理器，安装核心依赖：

# 安装 ESLint 核心
pnpm i -D eslint

# 新版官方 JS 规则集
pnpm i -D @eslint/js

# 全局变量定义
pnpm i -D globals

# TypeScript 支持
pnpm i -D typescript-eslint

也可以直接用初始化命令向导式生成：

npx eslint --init

3.2 完整配置文件

在项目根目录新建 eslint.config.mjs，内容如下：

import js from "@eslint/js";
import globals from "globals";
import tseslint from "typescript-eslint";
import { defineConfig } from "eslint/config";

export default defineConfig([
  {
    files: ["**/*.{js,mjs,cjs,ts,mts,cts}"],
    plugins: { js },
    extends: ["js/recommended"],
    languageOptions: {
      globals: globals.browser
    },
    rules: {
      // 0 = off 关闭
      // 1 = warn 警告
      // 2 = error 错误
      "no-var": 2,
      "no-console": 1,
      "quotes": ["error", "double"],
      "semi": ["error", "always"],
      "indent": ["error", 2]
    }
  },
  ...tseslint.configs.recommended,
]);

3.3 逐行拆解配置

我们一块一块说清楚每一行的作用。

① 导入依赖

import js from "@eslint/js";          // 官方 JS 推荐规则集
import globals from "globals";         // 常用环境全局变量定义
import tseslint from "typescript-eslint"; // TypeScript 规则集
import { defineConfig } from "eslint/config"; // 配置定义辅助函数

• @eslint/js：ESLint 官方维护的 JavaScript 推荐规则，替代了旧版的 eslint:recommended
• globals：预定义各种环境的全局变量，比如 browser 环境下的 window、document，避免报「未定义变量」错误
• typescript-eslint：TS 版本的 ESLint 解析器 + 规则集，支持 TypeScript 语法检查

② defineConfig 与配置数组

export default defineConfig([
  // 配置块1：JS 通用规则
  // 配置块2：TS 规则
])

defineConfig 提供类型提示，帮助写配置时获得补全。导出的是一个配置对象数组，每一项对应一组匹配规则，后面的配置会覆盖前面的。

③ 基础 JS 配置块

{
  // 匹配哪些文件生效
  files: ["**/*.{js,mjs,cjs,ts,mts,cts}"],
  // 注册插件
  plugins: { js },
  // 继承官方推荐规则
  extends: ["js/recommended"],
  // 语言选项：全局变量
  languageOptions: {
    globals: globals.browser
  }
}

• files：指定这套规则对哪些文件生效，支持通配符
• plugins：注册使用的插件，新版必须先注册再使用
• extends：继承预设规则集，js/recommended 就是官方推荐的基础规则
• languageOptions.globals：声明运行环境的全局变量。globals.browser 会把 window、document、navigator 等浏览器 API 标记为已知全局变量，不会报 no-undef

④ TypeScript 规则继承

...tseslint.configs.recommended

用展开运算符把 TS 推荐规则集展开到配置数组里，它会自动适配 .ts 文件，提供 TS 语法校验、类型相关规则。

⑤ 自定义规则 rules

这是配置的核心，我们可以覆盖预设规则，定制自己的代码规范。

rules: {
  "no-var": 2,
  "no-console": 1,
  "quotes": ["error", "double"],
  "semi": ["error", "always"],
  "indent": ["error", 2]
}

四、规则的三种级别：0 / 1 / 2

每条规则都可以设置三种级别，这是 ESLint 的基础概念：

表格

数值	对应单词	效果
0	off	关闭这条规则，完全不检查
1	warn	警告级别，提示但不报错，不影响编译
2	error	错误级别，直接报错，终端会显示红色错误

团队规范里，强制要求的规则一律设为 error，建议性的设为 warn。

逐条解读示例规则

1. "no-var": 2

   • 含义：禁止使用 var 声明变量
   • 理由：var 存在变量提升、无块级作用域等问题，统一使用 let/const
   • 级别：error，强制禁用

2. "no-console": 1

   • 含义：不建议使用 console.log
   • 理由：开发时用来调试，生产环境通常要清理
   • 级别：warn，开发时允许用，提示上线前删除

3. "quotes": ["error", "double"]

   • 含义：字符串必须使用双引号
   • 第二个参数可选："double" 双引号 / "single" 单引号 / "backtick" 反引号
   • 级别：error，强制统一

4. "semi": ["error", "always"]

   • 含义：语句结尾必须加分号
   • 第二个参数可选："always" 总是加 / "never" 总是不加
   • 级别：error，强制统一

5. "indent": ["error", 2]

   • 含义：缩进必须是 2 个空格
   • 第二个参数是空格数，也可以设为 "tab"
   • 级别：error，强制统一缩进

五、常用运行方式

5.1 命令行直接运行

# 检查所有文件
npx eslint .

# 检查指定目录
npx eslint ./src/app

# 自动修复所有可修复的格式问题
npx eslint . --fix

--fix 可以自动修复缩进、引号、分号、var 转 const 等格式类问题；但逻辑类问题（比如未使用变量）需要手动处理。

5.2 package.json 配置脚本

在 package.json 里添加脚本，团队成员统一命令：

{
  "scripts": {
    "lint": "eslint .",
    "lint:fix": "eslint . --fix"
  }
}

之后直接运行：

pnpm lint      # 检查
pnpm lint:fix  # 自动修复

六、VSCode 集成：保存自动修复

最舒服的用法还是和编辑器集成，写完保存自动修复格式。

1. 安装 VSCode 插件：ESLint（Microsoft 官方出品）
2. 打开设置 settings.json，添加配置：

{
  // 启用新版 Flat Config 支持
  "eslint.useFlatConfig": true,
  // 保存时自动执行 ESLint 修复
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  },
  // 默认开启 ESLint
  "eslint.enable": true
}

配置完成后，只要保存文件，就会自动修复缩进、引号、分号、var 等问题，开发体验拉满。

⚠️ 关键点："eslint.useFlatConfig": true 必须开启，否则 VSCode 无法识别新版 eslint.config.mjs 配置。

七、常见踩坑与注意事项

1. 文件名必须严格正确

新版配置文件名必须是 eslint.config.mjs，少一个字母、后缀错了都不生效。

2. 不能用 module.exports

.mjs 文件是 ESM 模块，必须用 export default，不能写 module.exports，否则直接报错。

3. TypeScript 配置展开写法

...tseslint.configs.recommended 前面的扩展运算符 ... 不能丢，它是把规则数组展开合并到主配置里。

4. globals 不要漏

如果不配置 globals: globals.browser，代码里写 window、document 会报 no-undef 错误，因为 ESLint 默认不知道这些是浏览器全局变量。

5. no-console 不要一刀切

生产环境建议关闭 console，但开发时调试需要。推荐做法：

• 开发环境设为 warn
• 生产打包工具（如 Vite、Webpack）自动移除 console

八、团队落地建议

1. 配置统一维护：一份配置全团复用，不要每个人自己改规则
2. 结合 Prettier：ESLint 负责代码质量 + 部分格式，Prettier 专门负责格式化，两者配合效果最佳
3. CI 集成门禁 ：在 Git 提交或流水线里加 pnpm lint 校验，不通过不让合并，从流程上保证规范
4. 渐进式接入：老项目接入可以先把规则级别设为 warn，逐步整改，不要一上来全 error 导致大量报错

结尾

ESLint 从来不是为了限制开发者，而是用一套公认的标准，把团队从无意义的格式争论里解放出来，把精力放在真正有价值的业务逻辑上。

Flat Config 作为新版官方标准，配置更清晰、语法更统一，是现在新项目的首选。上面这份配置可以直接复制到你的项目里，再根据团队习惯调整几条规则，就能快速落地代码规范。