文章目录写在前面一、什么是 ESLint为什么它是工程质量的重要保证1.1 它是什么二、快速上手安装与初始化2.1 安装2.2 初始化配置文件2.3 在 package.json 里加两个脚本三、认识配置文件 eslint.config.mjs四、添加规则让 ESLint 替你守住代码质量4.1 规则的三个级别4.2 逐条拆解五个高频规则① no-var禁止使用 var② no-console提示残留的 console 调试语句③ quotes统一引号风格④ semi统一句末分号⑤ indent统一缩进4.3 规则的两种写法小结五、实战一键检查与修复5.1 先检查npm run lint5.2 再修复npm run lint:fix全文总结核心知识点复盘写在前面一个项目从「能跑」到「能长期维护」中间隔着一条鸿沟这条鸿沟的名字叫代码工程质量。而 ESLint就是横在这条鸿沟上最常用的一座桥。它到底解决什么问题官方一句话就能概括强制团队写出一致风格的代码严格检查代码提前发现潜在 bug。本文会用最少的配置、最直白的例子带你理解 ESLint 是什么、为什么重要以及最核心的——怎么给项目添加规则。一、什么是 ESLint为什么它是工程质量的重要保证1.1 它是什么ESLint 是一个静态代码检查工具Linter。所谓「静态」是指它不运行你的代码而是直接分析源码文本找出里面不符合规则、可能出错的地方。它可以做到三件事这三件事也正好对应工程质量最关心的三个维度统一代码风格整个团队都写「双引号」还是「单引号」、句末加不加分号、缩进几个空格……这些琐碎的风格差异交给 ESLint 统一约束避免每个人各写各的。严格检查代码一些明显不规范、有隐患的写法直接在提交前就被拦下来。提前发现潜在 bug很多 bug 不是跑起来才暴露的而是「一看写法就有问题」。ESLint 能在编码阶段就把它们揪出来。一句人话ESLint 相当于在代码提交前请了一个严格的「代码审查员」24 小时盯着你写代码不规范的当场提示。二、快速上手安装与初始化2.1 安装在项目根目录执行npminstall-Deslint-D表示装到devDependencies因为 ESLint 只在开发阶段用不需要打进生产包。2.2 初始化配置文件ESLint 从v9 开始初始化方式变了不再用旧的eslint --init而是npminit eslint/configlatest它会以交互问答的方式问你要检查什么语言、用什么模块规范、是否用 TypeScript 等最后自动生成一个eslint.config.mjs配置文件。注意如果你装的是 ESLint 9 或 10直接敲eslint --init会报「找不到命令」因为没全局安装或提示改用上面的新命令2.3 在 package.json 里加两个脚本为了方便我们通常会在package.json里加两条命令{scripts:{lint:eslint .,lint:fix:eslint . --fix}}npm run lint只检查报告问题不改代码。npm run lint:fix检查后把能自动修的问题直接帮你改掉。三、认识配置文件eslint.config.mjsESLint 9/10 采用的是Flat Config扁平配置配置文件通常是eslint.config.mjs或.js。一个最小可用的配置长这样// eslint.config.mjsimportjsfromeslint/js;// 官方提供的推荐规则集importglobalsfromglobals;// 全局变量集合如浏览器里的 window、documentexportdefault[js.configs.recommended,// ① 引入官方推荐规则{files:[**/*.{js,mjs,cjs}],// ② 这些规则作用于哪些文件languageOptions:{globals:globals.browser,// ③ 声明运行环境是浏览器避免误报},rules:{// ④ 自定义规则这是本文重点},},];几个关键字段先有个印象字段作用js.configs.recommended引入官方内置的一套推荐规则开箱即用files指定这些规则检查哪些文件这里用通配符覆盖了 js/mjs/cjslanguageOptions.globals声明全局变量否则window、document会被误报成「未定义」rules自定义规则逐条开关或微调这是本文的核心四、添加规则让 ESLint 替你守住代码质量这是 ESLint 最核心、也最实用的部分——在rules里一条一条地加规则。4.1 规则的三个级别每条规则都可以配一个「级别」决定它检查的严格程度级别数字级别英文含义影响0off关闭完全不检查这条规则1warn警告提示你但不会阻断lint 仍然通过2error错误报错通常会导致 lint 失败退出码非 0所以你在代码里看到no-var: 2意思就是「把 no-var 这条规则设为 error 级别」no-console: 1就是「设为 warn 级别」。数字和英文是等价的2和error可以互换。4.2 逐条拆解五个高频规则下面用一份真实项目配置逐条讲清楚「为什么加它、它有什么用」。// eslint.config.mjsimportjsfromeslint/js;importglobalsfromglobals;exportdefault[js.configs.recommended,{files:[**/*.{js,mjs,cjs}],languageOptions:{globals:globals.browser},rules:{no-var:error,// 不能用 varno-console:warn,// 开发时用上线后关掉quotes:[error,double],// 强制双引号semi:[error,always],// 强制句末分号indent:[error,2],// 2 空格缩进},},];①no-var禁止使用var这是「提前发现潜在 bug」的典型代表。为什么不能用var因为它有几个历史遗留的坑没有块级作用域var只在函数作用域内有效在if、for代码块里声明的变量会「漏」到外面容易造成变量污染变量提升var会被提升到作用域顶部在声明之前访问得到undefined而不是报错埋下隐患可以重复声明同名var重复声明不会报错反而静默覆盖很难排查。而let/const有块级作用域、不会重复声明、const还能防止误改是更安全的选择。所以团队会要求一律用let/const禁用var。varnamezmt_ai;// ❌ ESLint 报错Unexpected var, use let or const insteadconstnamezmt_ai;// ✅ 正确②no-console提示残留的console调试语句开发时我们常用console.log打印调试信息但这些语句不应该带上线。配置成warn级别 1就很合适开发阶段能看到警告提醒你「这里有个 console」但不影响运行上线 / CI 阶段可以把级别调成error或干脆off严格拦截或放开。console.log(hello);// ⚠️ ESLint 警告Unexpected console statementwarn 级别不阻断小结no-console配warn是「开发友好、上线可收紧」的经典用法也体现了「分级控制」的思想——不是所有规则都要一上来就 error。③quotes统一引号风格团队里有人写单引号、有人写双引号代码就会显得杂乱。quotes: [error, double]表示「强制使用双引号违反就报错」。它的写法是数组形式第一个元素是级别第二个元素是选项。constmsghello;// ❌ 报错Strings must use doublequoteconstmsghello;// ✅ 正确④semi统一句末分号semi: [error, always]表示「每条语句末尾都要有分号」。分号到底加不加一直是社区争议点但关键在于团队统一ESLint 就是帮你把「统一」这件事变成硬约束。constnamezmt_ai// ❌ 报错Missing semicolonconstnamezmt_ai;// ✅ 正确⑤indent统一缩进indent: [error, 2]表示「用 2 个空格缩进」。缩进不一致会让代码层级看起来混乱尤其是多人协作时。functionhello(){console.log(hi);// ❌ 报错Expected indentation of 2 spaces but found 4console.log(hi);// ✅ 正确}4.3 规则的两种写法小结只有级别no-var: error或no-var: 2二选一。级别 选项quotes: [error, double]数组形式第一项是级别后面是参数。五、实战一键检查与修复理解了规则之后我们用一个真实的「违规文件」走一遍完整流程。假设我们的index.mjs写了这样一段「问题代码」varnamezmt_aifunctionhello(){console.log(helloname)}hello();5.1 先检查npm run lintnpmrun lint输出这是我在项目里真实跑出来的结果index.mjs 1:1 error Unexpected var, use let or const instead no-var 1:20 error Missing semicolon semi 3:1 error Expected indentation of 2 spaces but found 4 indent 3:5 warning Unexpected console statement no-console 3:17 error Strings must use doublequote quotes 3:32 error Missing semicolon semi ✖ 6 problems (5 errors, 1 warning)逐条对照正好对应我们配置的规则报错信息对应规则级别Unexpected var, use let or const insteadno-varerrorMissing semicolonsemierrorExpected indentation of 2 spaces but found 4indenterrorStrings must use doublequotequoteserrorUnexpected console statementno-consolewarning注意最后一行1 warning因为no-console我们配的是warn所以它是警告、不是错误不会让 lint 失败。5.2 再修复npm run lint:fixnpmrun lint:fixESLint 会把「能自动修」的问题直接改掉。执行后index.mjs变成了letnamezmt_ai;functionhello(){console.log(helloname);}hello();发生了什么var→letno-var自动修复单引号 → 双引号quotes自动修复补上了分号semi自动修复4 空格 → 2 空格indent自动修复但再跑一次npm run lint还剩一条3:3 warning Unexpected console statement no-console ✖ 1 problem (0 errors, 1 warning)为什么no-console没被自动修掉因为--fix只能修复「机械性」的问题改引号、加分号、调缩进而「要不要删掉 console」涉及开发意图ESLint 不敢替你乱删所以这类规则只能人工处理。核心认知--fix能改风格改不了意图。能用--fix的是 quotes / semi / indent 这类格式规则no-var、no-console这类涉及语义的要么靠规则自动改写no-var可改成let要么只能人工判断。全文总结本文围绕 ESLint 的核心价值讲清了「是什么、为什么、怎么用」ESLint 是什么静态代码检查工具不运行代码就能发现风格问题、不规范写法、潜在 bug。为什么重要它把「一致风格、严格检查、提前发现 bug」这三件事从靠自觉变成靠工具强制是工程质量的重要保证。怎么用装好 eslint、生成eslint.config.mjs在rules里逐条添加规则规则分off / warn / error0 / 1 / 2三级用npm run lint检查、npm run lint:fix自动修复。并通过no-var、no-console、quotes、semi、indent五个真实规则完整演示了「配置 → 检查 → 修复」的闭环。核心知识点复盘ESLint 三大价值统一代码风格、严格检查代码、提前发现潜在 bug。安装npm install -D eslint初始化用npm init eslint/configlatestv9 不再用eslint --init。配置核心eslint.config.mjs里js.configs.recommended引推荐规则rules里自定义规则files指定作用文件languageOptions.globals声明环境。规则级别0/off关闭、1/warn警告不阻断、2/error错误阻断。规则写法no-var: 2只有级别或quotes: [error, double]级别 选项。五个高频规则no-var禁 var、no-console提示 console、quotes统一引号、semi统一分号、indent统一缩进。检查与修复eslint .只检查eslint . --fix自动修--fix只改格式类问题改不了语义类问题。