一个二十人的前端团队,代码评审里最常见的评论是「这里少个分号」「缩进不对」「单引号还是双引号」。真正需要人看的逻辑问题,比如一个没有处理的 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

老项目接入,别追求「一次全绿」。三千条错误不是三天能修完的,强行全量只会让人关规则。可以按这个顺序:

老项目的渐进接入顺序
先格式化全量跑一次 Prettier,单独提交
再锁新代码Lint 只卡新增和改动文件
逐步清旧账按目录修,修完一个纳入检查
最后开类型规则在稳定目录先试,观测耗时

「只卡新代码」在 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 不能替代测试和类型。它能抓模式化的错误,抓不到业务逻辑错、接口契约变化、交互状态问题。规范是底线,不是质量的全部。

小结

格式化交给 Prettier排版不需要讨论;配置写进仓库,保存即格式化,CI 用 --check。
Lint 只管质量ESLint 10 用 flat config;先开确定性错误,再按目录开类型感知规则。
钩子要快,CI 要全lint-staged 只处理暂存文件;完整检查、类型检查放 CI,别把钩子做成四十秒的关卡。
老项目渐进,不追求一次清零先格式化,再锁新代码,按目录还旧账,最后才开类型规则。

当天可以做的练习:

  1. 在一个小 TS 项目里配 flat config,跑 eslint .,记录错误数量和类型。
  2. 加 Prettier,全量格式化一次,用 git diff --stat 看影响范围,再跑 prettier --check .。
  3. 加入 lint-staged 和 husky,用 time 量一次提交的钩子耗时。
  4. 打开 no-floating-promises,在项目里找一处没有 await 的异步调用。
  5. 在 CI 加 --max-warnings=0,故意写一个未使用变量,确认流水线变红。

下一篇讲前端测试。Lint 和类型能挡住一批低级错误,但挡不住「价格算错了」「点了没反应」这类行为问题。测试是另一层保障,也是最容易变成「写了没人维护」的一层。下一篇就讲怎么用合适的测试层级,接住真正会出问题的地方。