一个二十人的前端团队,代码评审里最常见的评论是「这里少个分号」「缩进不对」「单引号还是双引号」。真正需要人看的逻辑问题,比如一个没有处理的 Promise、一个永远为真的条件,反而被几十行格式 diff 淹没了。
后来团队上了 ESLint 和 Prettier。第一周更乱:两个人同时改了同一批文件,格式化把整个仓库刷了一遍,Git 历史里一半提交是「format code」;有人提交时被钩子卡了四十秒,干脆开始 git commit --no-verify。工具装上了,规范没落地,还多了一层摩擦。
这篇讲什么:Lint 和格式化各自管什么、ESLint 10 的配置怎么写、规则该开多少、提交前检查和 CI 怎么分工、老项目怎么从「三千条错误」走到「新代码零错误」。读完你能做到:配出一套跑得动又不烦人的规范;让格式问题不再进代码评审;知道哪些规则值得用类型信息换性能。
版本说明:本文按 ESLint 10 写(2026 年 2 月发布)。ESLint 10 已经彻底移除旧的 .eslintrc 配置格式,只支持 flat config;Node 低于 20.19 也不再支持。Prettier 按 3.x 写,配置形态多年没大变。
Lint 和格式化,是两件不同的事
把这两件事混在一起,是大多数规范方案失败的第一步。
格式化(Prettier)
只管排版:缩进、引号、换行、括号位置。它不做语义判断,输出是确定的,同一份代码在任何人机器上结果一样。
Lint(ESLint)
管代码质量和潜在错误:未使用变量、可疑的条件、错误的 hook 用法、没有处理的 Promise。它可以自动修一部分,但不是全部。
为什么必须分开?因为两者都能「改代码」,同时开启格式化规则时会互相打架:ESLint 说要加分号,Prettier 说不要,保存一次文件来回跳。正确分工是:Prettier 独占排版,ESLint 关掉所有排版类规则,只留质量规则。ESLint 官方提供 eslint-config-prettier,作用就是把这些冲突规则关掉,不是让 ESLint 去调用 Prettier。
分开之后还有一个好处:格式化不依赖团队讨论。引号用单还是双、行宽 80 还是 100,选一个默认值,写进配置,所有人保存时自动统一,评审时不再出现这类评论。这类问题本来就不该由人来做决定。
ESLint 10 的配置:一个文件,扁平数组
flat config 的核心是一个导出数组,每个元素是一段配置,后面的覆盖前面的。一个能跑的 TypeScript 项目配置大概长这样:
// eslint.config.js
import js from "@eslint/js";
import tseslint from "typescript-eslint";
import prettier from "eslint-config-prettier";
export default tseslint.config(
{ ignores: ["dist/**", "coverage/**", "node_modules/**"] },
js.configs.recommended,
...tseslint.configs.recommended,
{
files: ["**/*.{ts,tsx}"],
languageOptions: {
parserOptions: {
projectService: true,
tsconfigRootDir: import.meta.dirname
}
},
rules: {
"@typescript-eslint/no-unused-vars": [
"error",
{ argsIgnorePattern: "^_" }
],
"no-console": ["warn", { allow: ["warn", "error"] }]
}
},
prettier
);
几个关键点:
ignores放最前面,排除构建产物、覆盖率报告和依赖目录。不排除dist,Lint 会去检查压缩后的代码,慢且全是错。js.configs.recommended是 ESLint 官方的基础规则,抓未定义变量、重复声明这类硬错误。tseslint.configs.recommended是 TypeScript 相关规则,先不加类型信息,速度快。files限定这段配置只作用于 TS 文件,JS 配置文件本身用另一套。prettier放最后,确保它关掉的那些排版规则不会被前面的配置重新打开。
projectService: true 是开启「类型感知规则」的开关,它让 ESLint 复用 TypeScript 的项目服务,能判断一个 Promise 有没有被 await、一个变量是不是真的可空。代价是明显变慢,项目大时 CI 可能多花几十秒到几分钟。建议先不开,等基础规则稳定后再按目录逐步开。
.eslintrc.json 的写法,在 ESLint 10 里直接不生效。看到 extends、env、parserOptions 写在 JSON 里的老配置,先确认项目的 ESLint 版本,再决定是迁移还是绕开。规则不是越多越好
新手容易犯的错,是把能找到的规则全打开,几百条一起上。结果第一天三千个错误,团队第一反应不是修,而是关规则。规则一旦被大规模关闭,后面再想开就难了。
选规则的原则:先抓「会变成 bug」的,再抓「会变成维护负担」的,最后才考虑风格偏好。风格类的大部分交给 Prettier。
| 类型 | 例子 | 建议 |
|---|---|---|
| 确定性错误 | 使用未定义变量、重复声明、不可达代码 | 一开始就开,报错级别 |
| 高风险写法 | 未处理的 Promise、浮空 Promise、错误的 hook 依赖 | 需要类型信息,按目录逐步开 |
| 可维护性 | 未使用变量、过长的函数、过多的参数 | 开,但阈值放宽,避免为了过规则而拆坏代码 |
| 风格偏好 | 引号、分号、缩进、对象换行 | 交给 Prettier,ESLint 不参与 |
| 个人洁癖 | 禁止某类语法、强制某种设计模式 | 谨慎,先讨论是否真的影响团队 |
对于「警告」要特别小心。CI 里如果只卡错误,警告会越积越多,最后没人看;如果卡零警告,迁移期又会红成一片。可行的做法是:迁移期只卡错误,把警告当成待办清单;新项目直接 --max-warnings=0,不给警告留生存空间。
Prettier:把格式从讨论里拿掉
Prettier 的配置很少,常用的就几项:
// .prettierrc.json
{
"printWidth": 100,
"singleQuote": false,
"semi": true,
"trailingComma": "all"
}
配置写进仓库,编辑器开启「保存时格式化」,再在 CI 加一条 prettier --check .。三件事齐了,格式问题就基本消失。
几个实际细节:
.prettierignore要排除构建产物、生成的类型文件、锁文件。格式化锁文件会让 diff 变成几千行,且没有任何收益。- 第一次全量格式化会产生一个巨大的提交。单独提交、只做格式化、不夹带业务改动,评审时勾选「忽略空白差异」还能看。
prettier --write会真的改文件,--check只检查。CI 用后者,本地用前者。- 和 ESLint 的顺序:先 ESLint
--fix,再 Prettier--write,让排版以 Prettier 为准。
把格式化做成「保存即发生」,比写在文档里有效得多。人不会记得提交前跑命令,但编辑器每次保存都跑,习惯两周就养成了。
提交前检查:快,才有意义
提交前钩子的目的不是替代 CI,而是让问题在本地就被发现,省一次推送和等待。它最重要的指标是速度:超过三秒,人就会想办法绕过。
常见组合是 husky 管钩子,lint-staged 只处理暂存的文件:
// package.json
{
"scripts": {
"lint": "eslint .",
"format": "prettier --write .",
"format:check": "prettier --check ."
},
"lint-staged": {
"*.{js,jsx,ts,tsx}": ["eslint --fix", "prettier --write"],
"*.{css,md,json}": ["prettier --write"]
}
}
# 初始化 husky(husky 9 的写法)
npx husky init
# .husky/pre-commit
npx lint-staged
只检查暂存文件,是速度的关键。整个仓库跑一遍 ESLint,老项目动辄几十秒;只跑改动过的几个文件,通常一秒出头。
但「只检查暂存文件」有代价。类型感知规则需要完整的项目信息,单文件检查可能给出误报或漏报;有些跨文件的规则也不适合在钩子里跑。折中方案:钩子只跑快速规则和格式化,类型检查和完整 Lint 留给 CI。
提交信息规范也可以放在钩子里。用 commitlint 校验「feat:」「fix:」这类前缀,配合团队约定生成变更日志。它属于「低成本、长期收益」的规范,但要先确认团队真的会用变更日志,否则只是多一道形式。
--no-verify 的习惯。如果它经常卡住,先查是不是在跑全仓库、是不是类型检查被塞进了钩子,把耗时的部分挪到 CI,而不是关掉保护。CI 兜底,老项目渐进
本地钩子可以被绕过,CI 不能。CI 里至少要跑三条:
- run: npx eslint . --max-warnings=0
- run: npx prettier --check .
- run: npx tsc --noEmit
老项目接入,别追求「一次全绿」。三千条错误不是三天能修完的,强行全量只会让人关规则。可以按这个顺序:
「只卡新代码」在 CI 里实现起来要一点脚本,但值得。简单做法是把老目录加进 ignores,新代码目录正常检查,修完一个老目录就把它从 ignores 里删掉。另一种做法是用增量 Lint,只检查本次改动涉及的文件,但需要额外工具支持。
旧账清理要有节奏。每周固定修一个目录,或者规定「改到哪个文件就顺手修它」,不要开「Lint 专项月」,那种运动式清理通常坚持不下来。规则的价值在于长期执行,不在于一次清零。
完整场景走查:二十人团队的三周
背景:四年前端仓库,三十万行代码,二十个人提交,之前只有编辑器里的零散格式化,没有统一检查。目标不是「零错误」,而是「新代码不再产生新的格式争论和明显错误」。
第一周只做格式化。选一套 Prettier 配置,全量跑一次,单独提交,提交信息写明「仅格式化,无逻辑改动」。同时在仓库根目录加 .git-blame-ignore-revs,把这次提交的哈希写进去,让 git blame 跳过它,避免以后查历史全是格式化提交。这一周有人不习惯,但因为没有夹带业务改动,评审很快通过。
第二周加 ESLint。先只开官方推荐规则加 TypeScript 推荐规则,不启用类型感知。老目录整体加进 ignores,新代码目录正常检查。第一次跑,新代码有 37 个错误,基本是未使用变量和 any,当天修完。
同一周加钩子。lint-staged 只处理暂存文件,实测一次提交平均 1.8 秒;把 tsc 留在 CI,不塞进钩子。commitlint 校验提交前缀,规则很简单,团队半天就适应了。
第三周把 CI 卡上。流水线加 eslint . --max-warnings=0 和 prettier --check .,先只卡新代码目录。然后在一个相对稳定的服务层目录打开类型感知规则,重点加 @typescript-eslint/no-floating-promises。这条规则当天抓出三个没有 await 的异步调用,其中一个会在请求失败时静默丢数据,属于真实的线上隐患。
代价也记录一下:类型感知规则让 CI 多了二十五秒;格式化提交让一次合并冲突变多,持续了大约一周;有人提案把规则开到两百条,被否了,理由是「先让现在的规则被真正执行」。三个月后回看,代码评审里关于格式的评论基本消失,未使用变量和浮空 Promise 变成提交前就能发现的问题。
错误现象对照
| 现象 | 真实原因 | 第一步查什么 |
|---|---|---|
Parsing error: Unexpected token | 没有为 TS 或 JSX 配置文件解析器 | 看 flat config 的 files 和 languageOptions.parser |
| 保存后格式反复横跳 | ESLint 和 Prettier 同时在管排版 | 确认装了 eslint-config-prettier 并放在配置末尾 |
| 本地通过,CI 报错 | 版本不一致,或 CI 检查的文件范围更大 | 对比两边的 ESLint/Prettier 版本和实际执行命令 |
| 提交钩子要等半分钟 | 钩子在跑整个仓库,或塞进了类型检查 | 确认用的是 lint-staged,且只处理暂存文件 |
Definition for rule ... not found | 插件没装,或 flat config 里没注册 | 检查依赖和配置项,别只复制规则名 |
| 类型感知规则从不报错 | projectService 没配,或文件不在 tsconfig 范围内 | 确认 tsconfig 的 include 覆盖到该文件 |
| 开规则当天三千条错误 | 没有基线,直接全量启用 | 先忽略老目录,只卡新代码,按目录清理后再纳入 |
边界与代价
规范的价值不在「规则数量」,而在「被执行的比例」。开两百条规则、关掉一百八十条,不如开二十条、全部执行。定期统计 eslint-disable 的数量和原因,比看规则清单有用;某个规则被大量关闭,要么规则不适合这个项目,要么团队没理解它,两种情况都该处理。
类型感知规则是双刃剑。它能抓到浮空 Promise、错误的比较、不可达分支,但这些收益要用 CI 时间和配置复杂度换。小项目、纯 JS 项目没必要开;大型 TS 项目可以按目录逐步开,先开收益最高的几条,别一次全上。
格式化会留下一次性的历史噪音。全量格式化的提交要独立、要加进 blame 忽略列表、要在合并冲突少的时段做。团队如果正在赶版本,宁可等一周,也不要在发布前刷全仓库。
钩子的边界是「快」。任何超过三秒的检查,都会把人推向 --no-verify。完整检查放 CI,钩子只做能在一两秒内完成的事。这个取舍要想清楚,否则工具越装越多,绕过的理由也越来越多。
最后,Lint 不能替代测试和类型。它能抓模式化的错误,抓不到业务逻辑错、接口契约变化、交互状态问题。规范是底线,不是质量的全部。
小结
--check。当天可以做的练习:
- 在一个小 TS 项目里配 flat config,跑
eslint .,记录错误数量和类型。 - 加 Prettier,全量格式化一次,用
git diff --stat看影响范围,再跑prettier --check .。 - 加入 lint-staged 和 husky,用
time量一次提交的钩子耗时。 - 打开
no-floating-promises,在项目里找一处没有await的异步调用。 - 在 CI 加
--max-warnings=0,故意写一个未使用变量,确认流水线变红。
下一篇讲前端测试。Lint 和类型能挡住一批低级错误,但挡不住「价格算错了」「点了没反应」这类行为问题。测试是另一层保障,也是最容易变成「写了没人维护」的一层。下一篇就讲怎么用合适的测试层级,接住真正会出问题的地方。