ESLint 3400条告警整改实战：配置排障、自动修复与门禁

1. 接手一个满是告警的仓库我先做了什么去年冬天我接手了一个迭代了三年多的中后台项目仓库里积压的 ESLint 告警数量是 3400 多条分布在 600 多个文件里。第一次跑npx eslint .的时候终端刷了将近四十秒才停下来同事在旁边看了一眼说这玩意儿早就没人管了。这句没人管其实很典型——大多数项目的 ESLint 整改都不是从零开始配置而是从一个已经被反复// eslint-disable-next-line糊满的历史状态里往外捞。所以这篇内容讲的是 ESLint 整改代码过程中真实会遇到的问题和解决方案偏向实战排障不是配置教程。如果你手上正好有一个告警数量在三位数以上、--fix跑完还剩一大半、团队里没人愿意接的仓库那这篇基本就是为你写的。零基础也能看懂因为我会把每条规则为什么报、报完之后该怎么处理都拆开讲。先说清楚一个认知ESLint 整改不是把红色波浪线消掉而是把代码里潜在的问题显性化并逐条做出决策。3400 条告警里有大概 40% 是真问题未使用变量、错误依赖数组、隐式 any30% 是风格不一致引号、分号、import 顺序剩下 30% 是老代码用了新规则自然会触发的东西。这三类处理方式完全不同混在一起改改到最后一定是越改越乱。我当时的做法是先不动代码花半天时间把告警长什么样摸清楚再决定从哪儿下刀。下面这条路线是我踩了两轮之后总结出来的后面会一节一节展开。1.1 整改前的三件准备工作第一件事是锁定版本。很多人整改到一半发现规则突然变多原因是package.json里写的是eslint: ^8.0.0某次npm install之后小版本跳了新版本默认规则集变了。我的做法是把 eslint、parser、各个 plugin 全部改成精确版本去掉^和~同时在 CI 里加一条npm ls eslint的检查。这件事听起来很琐碎但它决定了你后面所有的统计数字是否可信。第二件事是确认当前配置到底生效了哪些规则。别相信README里写的直接跑npx eslint --print-config src/main.ts /tmp/effective-config.json这条命令会输出某个文件最终合并后的完整配置包括 extends 链路里带进来的所有规则。我当时就是这么发现项目里同时装了eslint-config-airbnb和另一个团队自定义的 config两边的quotes规则互相覆盖最终生效的是后者但很多人还按 airbnb 的写法在改。规则冲突是整改期最浪费时间的坑之一早点用--print-config看一眼能省掉大量我明明改了怎么还报的困惑。第三件事是导出一份 JSON 报告做基线。这一步是后面所有分批操作的依据npx eslint . -f json -o eslint-baseline.json有了这份文件你才能做统计、做对比、做改完前后告警是否真的减少的验证。我记得第一次整改完提交,同事 review 的时候问你确定减少了吗我直接把两份 JSON 用脚本 diff 出来的表格甩过去比任何口头说明都有说服力。1.2 我给自己定的整改顺序整改顺序这件事我试过两种极端。第一种是按目录推从src/utils开始一个目录一个目录清好处是范围可控坏处是同一个规则问题会在不同目录反复出现改到第十个目录的时候人会麻。第二种是按规则推先把no-unused-vars全部清掉再清import/order好处是同类问题集中处理效率极高坏处是一次性改动面太大review 成本高出问题不好回滚。最后我采用的是混合策略先按规则统计出 Top 10把其中可自动修复的规则用--fix一把梭剩下的按规则 目录交叉切分一次提交只处理一条规则在一个模块内的问题。这样每次 PR 的 diff 大概在 200 到 500 行之间review 的人能看得完出问题也能精准回滚。这里有个经验值可以参考单次提交的 diff 控制在 500 行以内告警消除量控制在 100 到 200 条之间。超过这个量级人脑已经无法有效 review 了你只是在制造看起来改了的假象。1.3 先跑统计再谈方案统计脚本很简单但对后续决策帮助巨大// scripts/eslint-stats.js const fs require(fs); const report JSON.parse(fs.readFileSync(eslint-baseline.json, utf8)); const byRule {}; const byDir {}; let total 0; for (const file of report) { const dir file.filePath.split(/src/)[1]?.split(/)[0] || root; for (const msg of file.messages) { const rule msg.ruleId || fatal; byRule[rule] (byRule[rule] || 0) 1; byDir[dir] (byDir[dir] || 0) 1; total; } } const sorted Object.entries(byRule).sort((a, b) b[1] - a[1]); console.log(总告警数:, total); console.table(Object.fromEntries(sorted.slice(0, 15))); console.table(byDir);跑出来的结果里前五名占了总量的 70% 左右typescript-eslint/no-explicit-any、no-unused-vars、import/order、react-hooks/exhaustive-deps、prettier/prettier。这个分布非常典型基本可以说明后面的整改重点在哪。有了这张表你跟团队同步进度的时候就不再是改了一半而是no-explicit-any从 800 降到 300量化之后推动力完全不一样。2. 配置文件本身的坑比代码还多真正开始改代码之前配置层面的问题必须先解决干净。我遇到的情况是代码改完了告警没减少一查发现规则压根没生效或者本地不报CI 报两边跑出来的结果差了一大截。这一类问题的根因几乎都在配置上。2.1.eslintrc和 flat config 的代际差异现在处于两代配置并存的状态。老项目基本是.eslintrc.js/.eslintrc.json新版 ESLintv9 之后默认只认eslint.config.js这种 flat config。我接手那个项目是 v8 .eslintrc.js升级到 v9 的时候踩了一串坑最典型的是extends的写法变了。老写法// .eslintrc.js module.exports { extends: [eslint:recommended, plugin:typescript-eslint/recommended], parser: typescript-eslint/parser, };新写法// eslint.config.mjs import js from eslint/js; import tseslint from typescript-eslint; export default tseslint.config( js.configs.recommended, ...tseslint.configs.recommended, { files: [**/*.{ts,tsx}], rules: { no-unused-vars: off, typescript-eslint/no-unused-vars: [error, { argsIgnorePattern: ^_ }], }, }, );这里有两个必须知道的细节。第一flat config 里不能再写parser字段parser 是通过 config 对象里的languageOptions.parser或者 preset 带进来的直接写parser: xxx会被忽略而且不报错——这属于沉默失败排查起来非常折磨。第二ignorePatterns变成了独立的ignores字段而且在 flat config 里ignores只有放在单独的 config 对象里才表示全局忽略跟别的配置混在一起会被当成 scoped 忽略。我第一次迁移的时候把ignores和rules写在一个对象里结果dist目录被一起 lint 了告警数从 3400 直接飙到 12000。2.2 规则集的取舍别一口气上 recommendedeslint:recommended和plugin:typescript-eslint/recommended是好东西但一次性全部打开会让存量项目瞬间爆炸。我的做法是分三档档位处理方式适用规则举例第一档必须报 error阻塞合并立刻修no-undef、no-dupe-keys、no-unreachable第二档先 warn不阻塞逐步清理no-unused-vars、import/order、prefer-const第三档关掉或延后存量太多先不管no-explicit-any、react-hooks/exhaustive-deps这个分档不是拍脑袋判断标准是**这条规则报的是不是真正的运行时风险**。no-undef报出来说明代码里引用了不存在的变量这种大概率是 bug必须 error。import/order纯粹是风格报 error 只会让所有人骂你warn 就够了。no-explicit-any严格说要处理但存量项目里 800 个 any 一夜之间全改完不现实所以先 warn设置一个季度清理目标。提示把规则从 error 降成 warn 只是争取时间不是终点。如果一年之后还是 warn那这条规则等于没加。我一般会在 issue 里挂一个带日期的清理任务到期就升 error。2.3 用 overrides 做局部豁免而不是全局关规则这是我觉得最值得分享的一条经验。很多人的处理方式是某条规则太吵了全局关掉结果就是新代码也不受约束了。正确做法是用 scoped config让规则只在特定目录下降级export default tseslint.config( js.configs.recommended, { files: [src/legacy/**/*.ts], rules: { typescript-eslint/no-explicit-any: off, no-console: off, }, }, { files: [src/**/*.ts], rules: { typescript-eslint/no-explicit-any: warn, }, }, );这样老代码区域保持宽松新写的东西逐渐收紧团队不会因为一上来就报几百个错而集体抵触。我把它叫做**隔离区策略**——把历史债务圈起来新代码按新标准走两边互不干扰。这个策略推下去阻力明显小很多因为没人会觉得你在给他添麻烦。同样的手法也适用于测试文件、构建脚本、类型声明文件它们对规则的要求本来就不一样。*.d.ts里大量any是正常的scripts/*.js里console.log也是正常的这些都应该用files精确圈定而不是简单粗暴地写/* eslint-disable */。3. 高频报错逐个拆解报错的真实原因代码层面的整改80% 的时间花在前 5 条规则上。我把每一条的处理逻辑都整理出来了包括什么情况下该改代码、什么情况下该改规则。3.1no-unused-vars不能无脑删这条规则报的是声明了但没用到。看起来最好处理实际上最容易改出 bug。原因是有些变量被隐式使用了比如通过解构把属性从对象里摘出来的场景剩下的属性用 rest 收集// 报错password is assigned a value but never used const { password, ...rest } user;这里的password确实没直接用到但它的作用是从rest里剔除删掉它会让rest里多出password字段可能造成敏感信息泄露。这种情况下正确做法是配置ignoreRestSiblings: truetypescript-eslint/no-unused-vars: [error, { argsIgnorePattern: ^_, varsIgnorePattern: ^_, ignoreRestSiblings: true, }],另一种高频情况是函数参数。事件回调里经常写成(e) {...}但实际没用到e或者接口约定必须有三个参数你只用了两个。我的处理原则是如果是回调签名必须保留的位置用下划线命名(_e, _index)配合argsIgnorePattern如果是真正多余的死参数直接删同时检查所有调用点如果是catch (err)但没处理考虑改成catch {}前提是运行环境支持可选 catch binding注意argsIgnorePattern只对未使用但位置靠后的参数生效如果你改成(_a, b)调用方传参位置不能变。别为了消告警把参数顺序调了那是纯粹的破坏性改动。还有一类是只写不读的变量比如let result;后面只做result x但从没被读取。这种 ESLint 报no-unused-vars是对的因为整段逻辑都是死代码删掉反而让代码更干净。所以遇到这条告警我的判断流程是先问这个变量有没有副作用没有副作用就删有副作用就改配置。3.2no-explicit-any从 any 迁移到 unknown 的实操这是存量项目里数量最多的一条。800 多个any不可能全靠手工改我的做法是分三批。第一批只在函数边界上处理也就是参数和返回值。这类位置改成unknown之后编译器会强制调用方做类型收窄收益最大// 改前 function parseConfig(raw: any) { return raw.data.items; } // 改后 function parseConfig(raw: unknown) { if (typeof raw ! object || raw null) { throw new TypeError(config must be an object); } const data (raw as { data?: { items?: unknown[] } }).data; return data?.items ?? []; }第二批处理泛型约束位置。很多any出现在Recordstring, any这种地方换成Recordstring, unknown基本不影响使用但能拦住把值随手传给别人的行为。第三批是真的没法改的比如第三方库的类型声明本身就有问题或者动态 key 访问。这类我的处理是保留any但加注释说明原因同时在配置里用/* eslint-disable-next-line typescript-eslint/no-explicit-any -- 第三方 SDK 类型缺失 */。注意我在 disable 后面加了--和原因这是 ESLint 支持的行内说明语法review 的时候一眼就能看出是有意为之还是忘了改。这里补一个细节unknown不是any的替代品。any可以直接访问任意属性、可以直接赋值给任何类型unknown必须先收窄。所以从any到unknown的迁移本质上是在逼你补上运行时校验这一步。这一步不做改了也是白改。3.3import/order路径别名和自动排序的冲突import/order是那种改起来没难度但数量巨大的规则。开--fix大部分能自动排好但有个坑路径别名解析不出来。项目里用/components/Button这种别名时如果 ESLint 不知道指向哪里会把它归类到external结果就是内部模块和react、lodash混在一起排序看着乱七八糟。解决方式是给 resolver 配别名settings: { import/resolver: { alias: { map: [[, ./src]], extensions: [.ts, .tsx, .js, .jsx], }, }, },配完之后/开头的会被正确识别为internal排序才对。另外import/order的groups配置建议写清楚我常用的是import/order: [warn, { groups: [builtin, external, internal, parent, sibling, index], newlines-between: always, alphabetize: { order: asc, caseInsensitive: true }, }],newlines-between: always会让每组之间空一行视觉上更容易扫读。这个设置一开始会被同事吐槽太占地方但坚持两周之后几乎没人再说了因为找 import 的速度确实快了。提示import/order的--fix是安全的它只调整顺序不改语义。但如果你有import ./polyfill这类副作用导入顺序是有语义的需要给它单独分组或者加/* eslint-disable */。我见过一次因为自动排序导致 polyfill 排到后面、老浏览器直接白屏的事故。3.4react-hooks/exhaustive-deps最容易被错误处理的一条这条规则报的是useEffect依赖数组不完整。绝大多数人的第一反应是加一行 disable 注释然后告警就消失了——但 bug 还在。我处理这条规则的流程是三步判断第一步看这个 effect 是不是只在挂载时执行一次。如果是说明依赖数组设计从根上就有问题应该改成useEffect(() {...}, [])并在内部用 ref 或者函数式更新来避免闭包陷阱而不是靠 disable 掩盖。第二步看缺失的依赖是不是函数。如果是组件内定义的函数加进依赖数组会导致每次渲染都重建、effect 无限执行。这时候正确做法是用useCallback把函数稳定下来或者把逻辑挪到 effect 内部。第三步只有在依赖确实是稳定的但 ESLint 无法推断的情况下才用 disable并且必须写原因useEffect(() { // ... // eslint-disable-next-line react-hooks/exhaustive-deps -- dispatch 来自 useReducer引用恒定 }, []);我统计过那次整改600 多条exhaustive-deps告警里真正需要 disable 的不到 50 条剩下的都是真 bug 或者代码结构问题。这条规则的价值就在于此它逼你把闭包问题想清楚。3.5 Prettier 和 ESLint 打架这个问题的表现是改完格式ESLint 说不对按 ESLint 改Prettier 又说不符合。根因是两套规则在争同一个格式决定权。解决方案很明确让 Prettier 负责格式ESLint 只负责代码质量。具体做法是装eslint-config-prettier放在 extends 的最后一位它会把所有跟 Prettier 冲突的格式类规则关掉import prettier from eslint-config-prettier; export default tseslint.config( js.configs.recommended, // ... 其他配置 prettier, // 必须是最后一个 );然后编辑器里装 Prettier 插件设成保存时格式化ESLint 插件设成保存时修复。两者的分工明确了就不会再打架。还有一种情况是项目里同时有.prettierrc和 ESLint 的quotes/semi规则这种情况必须二选一。我的选择是删掉 ESLint 里的格式规则全部交给 Prettier因为 Prettier 的格式化是可预测的而 ESLint 的--fix在复杂表达式上偶尔会给出奇怪的结果。4. 自动化整改的实操路径手工改 3400 条告警按每条 30 秒算也要 28 个小时。所以核心思路一定是能自动的自动不能自动的批量处理剩下的人工收尾。4.1--fix的能力边界--fix只对标记了可修复的规则生效。哪些可修复在 ESLint 官方文档的规则列表里带扳手图标的都是。常见的可自动修复规则规则是否可自动修复备注prefer-const是安全quotes/semi是注意与 Prettier 冲突import/order是副作用导入需注意no-var是安全no-unused-vars否删除有语义风险no-explicit-any否需要人工判断react-hooks/exhaustive-deps否必须人工分析执行的时候不要直接npx eslint . --fix一把梭因为格式规则和逻辑规则混在一起改完根本没法 review。我的做法是先关掉所有格式规则只让逻辑类规则的可修复项跑一遍npx eslint . --fix --rule {quotes:off,semi:off,indent:off}这样 diff 里就只剩下prefer-const、no-var这类真正有语义意义的改动review 起来清爽很多。格式统一放到最后一步单独提交用 Prettier 一次性刷。4.2 分批整改的脚本设计我的批次划分逻辑是按文件 按规则二维切分。先选一条规则再选出这条规则告警最集中的 20 个文件作为一批// scripts/pick-batch.js const fs require(fs); const report JSON.parse(fs.readFileSync(eslint-baseline.json, utf8)); const TARGET_RULE process.argv[2]; const LIMIT Number(process.argv[3] || 20); const hits report .filter(f f.messages.some(m m.ruleId TARGET_RULE)) .map(f ({ file: f.filePath, count: f.messages.filter(m m.ruleId TARGET_RULE).length, })) .sort((a, b) b.count - a.count) .slice(0, LIMIT); console.log(hits.map(h h.file).join(\n));拿到文件列表之后可以只对这些文件跑 fixnode scripts/pick-batch.js import/order 20 | xargs npx eslint --fix这样一批一批推每批都能独立提交、独立验证。我大概用了三周时间每天中午花一个小时处理两三批整个过程没有加过班也没有一次因为改动太大而出事故。4.3 利用 ESLint 的抑制机制做渐进式整改ESLint 新版本里有个功能叫 bulk suppressions可以把现存的所有告警一键冻结npx eslint . --suppress-all执行后会生成一个eslint-suppressions.json里面记录每一条现存告警的位置和规则。之后跑 lint 的时候这些问题不再报错但新增的问题会正常报。这个机制的价值在于你可以立刻让 CI 变绿同时保证新代码不再产生新的债务。我一般把它当作过渡手段用在两种场景一是团队需要立刻恢复提交不阻塞的时候二是大规模重构期间老文件的告警暂时顾不上。但要记住这是冻结不是清理冻结之后必须有计划地解冻否则一年后就是另一堆 3400。解冻的方法是配合--prune-suppressionsnpx eslint . --prune-suppressions这个命令会删掉那些已经不再触发的抑制记录让 JSON 文件逐渐瘦身。我一般每两周跑一次顺便看看哪些文件可以整体移出抑制列表。4.4 提交门禁让整改成果不再流失整改完最大的风险是过两个月又变回去了。所以必须把门禁做上。我用的方案是lint-stagedhusky只对暂存区的文件跑 lint{ lint-staged: { *.{ts,tsx,js,jsx}: [ eslint --fix --max-warnings0 --no-eslintrc -c eslint.config.mjs ] } }这里--max-warnings0是关键它让任何 warn 级别的告警也变成阻塞。这个设置要有心理准备刚开始团队会有意见需要配合前面的隔离区策略一起用老代码区域的规则已经降级了新代码区域卡严格一点是合理的。CI 侧再补一层全量检查npx eslint . --cache --cache-location node_modules/.cache/eslint/ --max-warnings0--cache这个参数一定要加它会把每个文件的检查结果缓存起来第二次跑只处理改动过的文件。我们这个项目加缓存之后CI 里的 lint 时间从 47 秒降到 6 秒。缓存目录放在node_modules/.cache里的好处是自动被清理不用额外写.gitignore。5. 常见问题与排查技巧实录这一节是我整个整改过程中攒下来的问题清单按出现频率排。5.1 问题速查表现象可能原因排查命令解决方向改了代码告警没减少规则未生效 / 文件被 ignorenpx eslint --print-config file检查 config 合并链路和ignores本地不报CI 报两边 ESLint 版本或配置不同npm ls eslint锁定版本CI 用同一个 config--fix跑完没变化该规则不支持自动修复查规则文档的扳手图标改为手工处理或降级告警数量突然暴涨ignore 配置写错把dist也扫了npx eslint . -f json | jq .[].filePath修正ignores位置lint 特别慢没开缓存 / 扫描了 node_modulesnpx eslint . --debug加--cache检查 ignoresno-undef在 TS 文件里误报没配 TS 的 globalsnpx eslint --print-config x.ts引入globals配置或关掉该规则5.2 我踩过的三个具体坑第一个坑eslint --fix把代码改坏了。那次是no-extra-parens规则对一段涉及??和||混用的表达式做了自动修复加了几行括号之后优先级变了业务逻辑跟着变。当时单元测试覆盖不足直接发到测试环境才发现。教训是--fix之后必须跑一遍测试再提交尤其是涉及运算符、可选链、逻辑表达式的自动修复。现在我的习惯是 fix 完先git diff扫一眼看有没有非预期的改动再跑测试。第二个坑禁用了规则但禁用错了位置。有些时候// eslint-disable-next-line放在函数外层其实只对紧接着的那一行生效如果目标行中间隔了注释或空行注释就失效了。更隐蔽的情况是// eslint-disable-next-line写在了return之后那一行是空行注释对着空行生效真正的代码行还在报。排查办法是看 ESLint 报错的行号对照着改实在找不准用npx eslint file --format json看具体的line和column。第三个坑多个 config 文件的优先级。项目里同时存在.eslintrc.js、.eslintrc.local.js还有package.json里的eslintConfig字段。ESLint 的规则是就近生效越靠近被检查文件的配置优先级越高。结果就是src/admin目录下的文件用的是src/admin/.eslintrc跟主配置完全不是一回事。这种情况在新项目里不该出现但存量项目里几乎一定有。排查靠--print-config加--debug后者会打印每个文件加载了哪些配置。5.3 关于eslint-disable的纪律我最后在团队里定了一条规矩所有eslint-disable必须带原因且原因写在同一行的--后面。这条规矩配合一个简单的 grep 检查就能落地grep -rn eslint-disable src --include*.ts --include*.tsx \ | grep -v \-\- \ echo 存在未注明原因的 disable exit 1这条命令放在 CI 里没写原因的 disable 直接让流水线红掉。规矩执行了两个月项目里 disable 注释从 400 多条降到 90 多条其中大部分是真的必要第三方类型问题、确实需要绕过的钩子依赖。另一个细节是优先用eslint-disable-next-line而不是eslint-disable。行级 disable 作用范围精确块级 disable 容易误伤后面新增的代码。我在 review 里见过一段/* eslint-disable */开在文件头三年没人敢删里面的所有规则全关了等于这个文件从来没被 lint 过。5.4 性能优化让 lint 跑得动最后一个实用技巧是关于速度的。大项目里 ESLint 慢是普遍问题几个立竿见影的优化--cache必加效果最明显ignores里加上构建产物dist、build、coverage、*.min.js避免在files里写**/*能限定到具体扩展名就限定**/*.{ts,tsx}比**/*快一截因为不用去读 CSS、MD、图片多项目分开跑如果仓库是 monorepo按 package 分别跑 lint利用--cache的目录隔离比一次性全量扫快得多我们那个项目做完这四项优化本地全量 lint 从 38 秒降到 4 秒CI 里从 47 秒降到 6 秒。速度上来之后大家才愿意在提交前主动跑一次这件事对整改成果不流失的意义比任何规矩都大。6. 一些不太适合写进规范的个人体会整改这件事技术难度其实只占三成剩下七成是节奏和预期管理。我最大的体会是不要把 ESLint 整改当成一个任务要当成一次代码审计。3400 条告警里藏着的那些未使用变量、错误的依赖数组、隐式的 any本身就是代码质量问题的清单。你按着清单一条一条过顺手就能发现一堆潜在 bug。我那次整改过程中光靠no-unused-vars就翻出来三处变量声明了但赋值逻辑写错了导致后续判断永远为真的问题这种问题跑测试跑不出来但上生产就是事故。另一个体会是别追求 100% 零告警。有些告警注定是要用 disable 绕过的比如第三方类型缺失、某些必须用 any 的动态场景。追求零告警的结果往往是写一堆毫无意义的包装类型反而让代码更难读。我给自己定的目标是告警数量稳定在 50 条以内且每条都有注释说明这个目标比零告警现实得多也健康得多。还有个操作上的小建议整改期间把git blame用起来。删一个变量之前看一眼它是谁加的、为什么加经常能发现这个是留给某个未上线功能用的这种信息。花十秒钟看 blame比事后回滚一次强太多。工具不会替你判断语义它只告诉你哪里可能有坑跳不跳还得自己看。