ESLint flat config 配置实战：五大字段、规则严重级别与 --fix 能力边界详解
团队里每个人代码风格都不一样------有人单引号有人双引号，有人两空格有人四空格，
var和let混用，console.log满天飞。ESLint 就是来解决这个问题的。本文用 eslint-demo 项目真实配置讲清 flat config 的五大字段、规则严重级别 0/1/2 的含义、--fix能修什么不能修什么，以及index.mjs里的代码到底会触发哪些规则。技术栈：ESLint 10.8.1 + @eslint/js 10 + typescript-eslint 8.67 + globals 17.11，pnpm 管理。文中代码来自真实项目，运行未验证 （未实际
pnpm lint）。
文章目录
- [ESLint flat config 配置实战：五大字段、规则严重级别与 --fix 能力边界详解](#ESLint flat config 配置实战：五大字段、规则严重级别与 --fix 能力边界详解)
-
- [一、ESLint 解决什么：团队代码风格一致性 + 潜在 bug 检测](#一、ESLint 解决什么：团队代码风格一致性 + 潜在 bug 检测)
- [二、flat config 五大字段：files / plugins / extends / languageOptions / rules](#二、flat config 五大字段：files / plugins / extends / languageOptions / rules)
- [三、规则严重级别 0/1/2：error 报错、warn 警告、off 关闭](#三、规则严重级别 0/1/2：error 报错、warn 警告、off 关闭)
- 四、五条自定义规则逐条解读
- [五、--fix 能修什么不能修什么](#五、--fix 能修什么不能修什么)
- [六、index.mjs 会触发哪些规则](#六、index.mjs 会触发哪些规则)
- 七、收藏资产：排错表与配置速查表
-
- [排错表：常见错误 → 原因 → 处理](#排错表：常见错误 → 原因 → 处理)
- [flat config 五大字段速查表](#flat config 五大字段速查表)
- 规则严重级别速记
- [ESLint vs Prettier 分工](#ESLint vs Prettier 分工)
- 总结与下一步
一、ESLint 解决什么：团队代码风格一致性 + 潜在 bug 检测
ESLint 是 JavaScript/TypeScript 的静态代码分析工具，在代码运行前就检查风格和潜在 bug。它解决两件事：
- 强制团队写出一致风格的代码------引号、分号、缩进统一
- 严格检查代码找出潜在 bug ------未用变量、
var滥用、console残留
类比一下：ESLint 像代码的「语文老师」，既管标点格式（格式类规则），也管语法错误（逻辑类规则）。
二、flat config 五大字段：files / plugins / extends / languageOptions / rules
ESLint 9+ 用新的 flat config 格式，配置文件是 eslint.config.mjs，替代旧版 .eslintrc.js。核心结构是一个数组：
js
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.node },
rules: {
"no-var": 2,
"no-console": 1,
"quotes": ["error", "double"],
"semi": ["error", "always"],
"indent": ["error", 2],
},
},
tseslint.configs.recommended,
]);五大字段速查表：
| 字段 | 作用 | 示例 |
|---|---|---|
files |
匹配哪些文件 | ["**/*.{js,mjs,cjs,ts,mts,cts}"] |
plugins |
注册插件（对象形式） | { js } |
extends |
继承规则集 | ["js/recommended"] |
languageOptions.globals |
运行环境全局变量 | globals.node |
rules |
自定义规则 | {"no-var": 2} |
关键点：
defineConfig包裹一个数组，每个对象是一个配置块tseslint.configs.recommended单独作为数组的一项，给 TS 文件加规则globals.node让 ESLint 识别console、process、__dirname等 Node 全局变量，否则会误报no-undef
三、规则严重级别 0/1/2：error 报错、warn 警告、off 关闭
这是 ESLint 面试高频考点。每条规则的严重级别有三种：
| 数字 | 字符串 | 含义 | 行为 |
|---|---|---|---|
2 |
'error' |
报错 | 阻断，退出码非 0 |
1 |
'warn' |
警告 | 提示但不阻断 |
0 |
'off' |
关闭 | 不检查 |
两种写法等价，上面的配置里就混用了：
"no-var": 2------ 数字写法"quotes": ["error", "double"]------ 字符串写法
带参数的规则用数组：["error", "double"] 表示「报错 + 必须用双引号」。
记住一句话：2/1/0 对应 error/warn/off，掌握这一行就掌握了所有规则的严重级别设置方式。
四、五条自定义规则逐条解读
| 规则 | 值 | 严重级别 | 作用 |
|---|---|---|---|
no-var |
2 |
error | 禁用 var，强制 let/const |
no-console |
1 |
warn | 禁用 console，开发时用上线后不用 |
quotes |
["error", "double"] |
error | 引号必须用双引号 |
semi |
["error", "always"] |
error | 必须加分号 |
indent |
["error", 2] |
error | 缩进用 2 个空格 |
为什么 no-console 只用 warn：开发时调试需要 console，但上线后不应残留。设成 warn 提醒但不阻断开发流程，体现了「严格但不死板」的工程权衡。
五、--fix 能修什么不能修什么
--fix 是 ESLint 的自动修复能力，但它有明确边界：
能自动修（格式类）：
quotes（引号统一为双引号）semi（补分号）indent（缩进修正为 2 空格）
不能自动修（逻辑类）：
no-unused-vars（变量声明了没用------要删掉或用上，ESLint 不敢替你决定）no-var（要手动把var改成let/const）prefer-const（要手动把let改const）
命令：pnpm lint:fix（即 eslint . --fix）。
为什么逻辑类修不了？因为「未用变量是该删还是该用上」「let 该不该改 const」需要人判断，ESLint 不敢擅自删你的代码。
六、index.mjs 会触发哪些规则
被 lint 的目标代码 index.mjs：
js
let a = 1;
const name = "zhangsan";
function hello() {
console.log("hello " + name);
}
hello();基于配置的静态推断（运行未验证）：
| 行 | 代码 | 触发规则 | 严重级别 | 来源 |
|---|---|---|---|---|
| 1 | let a = 1; |
no-unused-vars（声明未用） |
error | js/recommended |
| 1 | let a = 1; |
prefer-const（a 未修改应用 const） |
error | js/recommended |
| 4 | console.log(...) |
no-console |
warn | 自定义 rules |
为什么 name、hello 不报？因为它们都被使用了（name 在第 4 行用，hello 在第 6 行调用）。
let a = 1 一行触发两条 error：既声明了没用（no-unused-vars），又该用 const 没用（prefer-const）。这是初学者最容易踩的坑。
七、收藏资产：排错表与配置速查表
排错表：常见错误 → 原因 → 处理
| 错误现象 | 原因 | 处理方法 |
|---|---|---|
console 报 no-undef |
没设 languageOptions.globals |
加 languageOptions: { globals: globals.node } |
let a = 1 报 no-unused-vars |
声明了没用 | 删掉或用上；--fix 修不了 |
let a = 1 报 prefer-const |
a 没被修改，应用 const | 改成 const a = 1 |
| CI/CD 部署被阻断 | test 脚本 exit 1 或 lint 有 error |
修 lint 错误或实现 test |
| 引号/分号报错 | 风格规则 | 用 pnpm lint:fix 自动修 |
flat config 五大字段速查表
text
files → 匹配哪些文件（glob 模式）
plugins → 装插件（提供规则能力）
extends → 继承规则集（装能力 + 开预设规则）
languageOptions → 运行环境（globals.node 等）
rules → 自定义规则（覆盖或新增）规则严重级别速记
text
2 / 'error' → 报错阻断（退出码非 0）
1 / 'warn' → 警告提示（不阻断）
0 / 'off' → 关闭不检查ESLint vs Prettier 分工
| 工具 | 管 | 不管 |
|---|---|---|
| ESLint | 代码质量 + 潜在 bug + 风格一致性 | 纯格式美化 |
| Prettier | 纯格式化（换行、对齐美化） | 代码逻辑、潜在 bug |
两者有重叠（引号/分号），通常配合用：Prettier 管格式，ESLint 管逻辑。
总结与下一步
ESLint 的价值不在「又一个格式化工具」，而在于用 flat config 的数组式配置把「团队代码风格一致性」和「潜在 bug 检测」工程化。规则的严重级别 0/1/2 决定是阻断、警告还是放行，--fix 只能修格式类问题，逻辑类问题必须人工处理。
可迁移的判断 ：写 ESLint 规则时，先问自己「这条规则是格式类还是逻辑类」------格式类可以放心设 error（反正 --fix 能修），逻辑类要谨慎（设 error 可能阻断开发，必要时用 warn 提醒）。
下一步：
- 运行
pnpm lint验证本文对index.mjs的推断 - 运行
pnpm lint:fix看哪些被自动修了 - 给
eslint.config.mjs加一条新规则（如"no-unused-vars": 2） - 研究如何用 husky + lint-staged 把 ESLint 集成到 git hook
运行未验证：本文基于配置静态分析，未实际
pnpm lint。生产环境请以 ESLint 官方文档为准。
标签：ESLint, 代码规范, flat config, 前端工程化, Node.js