别让 Agent 写的代码越长越乱:ESLint + Prettier 提交门禁实战
Agent 写代码快、改得多、风格不统一。Prettier 管格式、ESLint 管对错、husky + lint-staged 管提交、CI 兜底:三天搭好一道门禁,让格式问题和低级错误进不了仓库。

划界:这篇和已发的代码质量指南有什么不同
先说清楚这篇指南的位置。站里已经有几篇代码质量相关的指南,各管一摊:《vibe-project-ai-code-review-before-merge-guide》讲合并之前怎么做 AI 代码评审,看的是逻辑对不对、设计合不合理;《solo-ai-git-workflow-guide》讲一个人的 Git 工作流,看的是分支、提交和合并的节奏;《reading-ai-generated-code-guide》讲怎么读懂 AI 生成的代码,看的是理解;《vibe-project-ai-review-second-check-guide》讲评审完再查一遍,看的是复核。本篇不讲评审、不讲分支策略、不讲读代码的方法,只讲一件事:用机器规则把格式问题和低级错误挡在提交之前,让“代码越长越乱”这件事在到达评审之前就被拦住。
这件事值得单独写一篇,是因为评审和门禁是两道不同的防线,很多人只建了第一道。评审是人看的,一次能看几百行就不错了,而且人的注意力会花在“这个功能对不对”上,不会花在“这里少了个分号、那里多了两个空格”上。门禁是机器跑的,不累、不漏、不讲情面,几秒钟扫完整个改动,把格式和低级错误一次性挡回去。没有门禁的项目,评审会上总有一半时间在吵格式;有了门禁,评审才能真正去聊逻辑。
依据是两份官方文档:ESLint 的 Getting Started(eslint.org/docs/latest/use/getting-started)和 Prettier 的 Install(prettier.io/docs/install)。本文提到的 ESLint 的安装方式、扁平配置、规则三档、Prettier 的安装与锁定版本、.prettierignore、--write 与 --check 的区别、husky 与 lint-staged 的提交前钩子、eslint-config-prettier 的作用,都出自这两份文档。文中的落地建议(比如“规则先 warn 后 error”)是基于这些机制的做法,会说明哪些是文档原话、哪些是建议。例子里的“小记账”项目是虚构的,仅用于演示。
为什么 vibe 项目最需要门禁
vibe 项目的代码有一个特点:写得快、改得多、风格不统一。同一段功能,今天让 Agent 写是两格缩进、单引号,明天换个会话写就变成四格缩进、双引号,后天你自己顺手补两行又是另一种风格。Agent 没有“我们项目一贯怎么写”的记忆,每次都是凭当时的习惯现写。一个人写的项目尚且会风格漂移,Agent 参与的项目漂移得更快。
风格不统一的代价不是“不好看”这么简单。第一,代码评审的时候,格式噪音会淹没真正的改动:一个文件改了 5 行逻辑、带了 40 行格式变化,评审的人根本看不出那 5 行在哪。第二,合并冲突会变多:两个人改了同一个文件,一个用了制表符、一个用了空格,Git 会把整段标成冲突,明明逻辑上不冲突。第三,低级错误会溜过去:没用到的变量、没定义的变量名、写错的比较,这些错误不影响 Agent 把代码交出来,但会在运行时炸掉。
门禁解决的就是这三件事,而且解决的方式很便宜:规则写进配置文件,检查交给机器,失败了不让提交。规则一旦定下来,Agent 生成的代码不管风格怎么飘,提交之前都会被统一收敛到同一套样子;低级错误在提交之前就被揪出来,不会等到用户报错才发现。门禁不是为了“管住 Agent”,而是为了让 Agent 的产出稳定可用——你让它自由发挥想法,但不让它自由发挥格式。
分清两件事:格式和规则不是一回事
动手之前先分清两个概念,很多人把它们混在一起,结果配错了地方。格式(formatting)管的是代码长什么样:缩进几格、引号用单还是双、行尾加不加分号、一行多长就换行。格式问题不影响程序运行,只影响人读起来顺不顺眼。规则(linting)管的是代码对不对:变量用之前有没有定义、定义了有没有用、是不是写了危险的写法、是不是用了已经废弃的 API。规则问题可能直接导致 bug。
Prettier 管格式,ESLint 管规则,这是标准分工。Prettier 是个“有主见的格式化工具”:它不跟你商量,对同一段代码永远输出同一种样子,你只需要决定少数几个选项(比如缩进宽度、引号风格),剩下的全部交给它。ESLint 是个“可插拔的检查器”:它的每一条规则都可以单独开关,你可以只开推荐集,也可以一条一条按自己的需要配。Prettier 的文档里有一句很关键的话:如果你用 ESLint,要装 eslint-config-prettier,让 ESLint 和 Prettier 和平共处——它会关掉所有和 Prettier 冲突的 ESLint 格式规则,免得两个工具对同一段代码下相反的命令。
分工不清的典型症状是:用 ESLint 去管缩进和引号,结果规则文件越写越长,Agent 每次提交都被一堆格式报错拦住;或者只装了 Prettier,以为代码就“检查过了”,结果没用到的变量、拼错的变量名一路畅通无阻。正确的做法是:格式交给 Prettier 全权处理,ESLint 只保留和对错有关的规则,两个工具各管一摊,互不越界。
第一步:先装 Prettier,把格式统一了
先装 Prettier,因为它是三步里最简单、见效最快的一步。按官方文档的安装方法,先在本地安装并锁定版本:
npm install --save-dev --save-exact prettier@3.10.1
注意这里用了 --save-exact 而不是普通的 --save-dev。文档特意提醒:Prettier 的每个版本格式化结果都可能略有不同,所以项目里要锁定一个确切的版本,不然不同的人装了不同的版本,会把彼此的格式改来改去。版本号以安装时文档所写为准,上面这行就是本文写作时文档里给的版本。
装完之后建两个文件。第一个是空的配置文件 .prettierrc,告诉编辑器和其他工具“这个项目在用 Prettier”:
node --eval "fs.writeFileSync('.prettierrc','{}\n')"
第二个是 .prettierignore,告诉 Prettier 哪些文件不要碰,比如构建产物和覆盖率报告:
node --eval "fs.writeFileSync('.prettierignore','# Ignore artifacts:\nbuild\ncoverage\n')"
文档里还提了一句很实用的细节:如果项目里已经有 .gitignore,Prettier 会自动遵守它的规则;也可以直接把 .prettierignore 写成和 .eslintignore 一致。生成的文件、第三方代码、体积很大的数据文件,都应该进 ignore 列表,不要让格式化工具去碰它们。
然后跑一次全量格式化,把历史遗留的格式问题一次性清掉:
npx prettier . --write
这一步会在全仓库范围内把格式统一。注意:第一次全量格式化要单独提交一次,不要和功能改动混在同一个提交里。混在一起的话,这个提交的 diff 会同时包含格式变化和逻辑变化,之后出问题回看历史的时候分不清哪一行是格式、哪一行是逻辑。单独提交一次之后,往后的每次提交就都只有真正的改动,历史干净得多。
检查格式用的命令是 --check,只检查、不改写:
npx prettier . --check
文档的说法是:--write 和 --check 是最常用的两种用法,前者改写文件,后者只检查。--check 的返回值可以直接用在 CI 里:格式没问题就返回成功,有问题就返回失败,流水线直接拦住。这就是第四步 CI 门禁里要用的命令,先在这里记住它。
第二步:再装 ESLint,把低级错误拦住
格式统一之后再装 ESLint。按官方文档的快速开始,Node.js 的版本有要求:需要 ^20.19.0、^22.13.0 或者 >=24 的版本,装之前先确认自己的 Node 版本够不够。安装和配置用一条向导命令:
npm init @eslint/config@latest
向导会问你几个问题,比如代码跑在什么环境(浏览器还是 Node)、用不用 TypeScript,问完之后生成一个 eslint.config.js(或者 eslint.config.mjs)配置文件。文档给的例子是这样的:选了浏览器环境之后,配置文件里会有 globals.browser 这一行,意思是告诉 ESLint 浏览器里有哪些全局变量(比如 window、document),用到了不算“未定义”。
import { defineConfig } from "eslint/config";
import globals from "globals";
import js from "@eslint/js";
export default defineConfig([
{ files: ["**/*.js"], languageOptions: { globals: globals.browser } },
{ files: ["**/*.js"], plugins: { js }, extends: ["js/recommended"] },
]);
这里的 js/recommended 是 ESLint 官方的推荐规则集,打开它等于打开所有被标记为推荐的规则。文档里明确提醒:ESLint 不会凭空检查你的代码,除非你继承了一个共享配置、或者明确打开了某条规则。只装了 ESLint、不配规则,跑起来是什么都不查的——这是新手最容易踩的坑,装完跑了一次、没报错,就以为代码没问题了。
规则也可以一条一条单独配,每条规则有三个档位:off(0)关掉,warn(1)打开但只警告、不影响退出码,error(2)打开且作为错误、退出码为 1。文档里的例子是这样的:
{
rules: {
"no-unused-vars": "warn",
"no-undef": "warn",
},
}
no-unused-vars 是“定义了但没用到的变量”,no-undef 是“用到了但没定义的变量”,这两条是 vibe 项目最值得先开的规则。Agent 生成代码的时候经常留下没用完的变量、或者凭印象编一个不存在的变量名,这两条规则正好卡住这两类错误。起步的时候先用 warn,等团队习惯了再把真正会出 bug 的规则升到 error。
手动安装的方式文档里也给了:先装 eslint 和 @eslint/js 两个包,再自己写 eslint.config.js,再用 npx eslint 检查指定文件或目录。向导和手动两种方式效果一样,选哪个看习惯。有一点要注意:如果用 pnpm,文档要求在项目里放一个 .npmrc 文件,写上 auto-install-peers=true 和 node-linker=hoisted 两行,不然依赖装出来可能不兼容、容易报错。
两者共处:别让两个工具打架
Prettier 和 ESLint 装好之后,第一件事是让它们别打架。两个工具都管“代码长什么样”的那部分:ESLint 里有一些规则也是管格式的,比如缩进、引号、行尾分号。如果 ESLint 的格式规则和 Prettier 的输出不一致,同一段代码就会陷入死循环:Prettier 改成 A 样子,ESLint 说不对、改成 B 样子,下次 Prettier 又改回 A 样子。
官方的解法是装 eslint-config-prettier。Prettier 的安装文档里写得很清楚:如果你用 ESLint,装这个包来让两者和平共处,它会关掉所有不必要的、或者可能和 Prettier 冲突的 ESLint 规则。装完之后,格式问题只由 Prettier 说了算,ESLint 只保留和对错有关的规则。分工一旦定下来,两个工具就不会再对同一段代码下相反的命令。
判断分工有没有配对的方法很简单:跑一遍 prettier --write,再跑一遍 eslint,如果 ESLint 还在报格式问题,说明冲突规则没关干净,回去检查 eslint-config-prettier 是不是真的接上了。反过来,如果 ESLint 一条都不报,也别急着高兴——先确认推荐规则集是不是真的继承了,没继承共享配置的 ESLint 是什么都不查的。
第三步:提交前钩子,只检查改动的文件
工具装好了,规则配好了,下一步是让检查在每次提交之前自动跑,而不是靠人每次手动跑。Prettier 的安装文档里给了标准做法:用 husky 管 Git 钩子,用 lint-staged 只检查本次改动的文件。安装命令是:
npm install --save-dev husky lint-staged
npx husky init
node --eval "fs.writeFileSync('.husky/pre-commit','npx lint-staged\n')"
然后在 package.json 里加一段 lint-staged 的配置,告诉它对改动的文件做什么:
{
"lint-staged": {
"**/*": "prettier --write --ignore-unknown"
}
}
这段配置的意思是:提交之前,对所有被改动的文件跑一遍 prettier --write,格式不对的当场改好再提交。--ignore-unknown 是让 Prettier 跳过它不认识的文件类型,不要对着图片、二进制文件报错。文档里还特意提醒了一句:如果同时用 ESLint,lint-staged 里要让 ESLint 先跑、Prettier 后跑,顺序别反了——先把对错问题修好,再统一格式,格式工具最后收尾。
为什么是 lint-staged 而不是在钩子里直接跑全量检查?因为全量检查慢,而且会把别人还没改完的文件也算进来。lint-staged 只对本次提交里改动的文件动手,改了三个文件就只检查三个文件,几秒钟跑完,不耽误提交。Agent 一次改几十个文件的时候,这个区别更明显:全量检查要扫整个仓库,lint-staged 只扫改动的部分。
钩子装好之后要亲手验证一次:故意改乱一个文件的格式、留一个没用到的变量,然后提交,看钩子是不是真的拦住了、是不是真的自动修好了格式、是不是真的报出了那条没用到的变量。没验证过的钩子等于没装——husky 没初始化成功、钩子文件没写对、lint-staged 配置放错了位置,都有可能让钩子悄悄失效,而你直到几个月后才发现这段时间提交的代码根本没被检查过。
第四步:CI 再加一道,全量检查兜底
提交前钩子是第一道关,但它有个弱点:钩子是装在本地的,换台电脑、重新克隆仓库、有人绕过钩子提交(git commit --no-verify),这道关就没了。所以还要在 CI 里再加一道全量检查,作为兜底。Prettier 的文档里明确建议:如果有 CI,就在里面跑 prettier --check,确保所有人都跑过 Prettier,避免合并冲突和其他协作问题。
CI 里要跑的两条命令是:
npx prettier . --check
npx eslint .
第一条检查全仓库的格式,第二条检查全仓库的规则。两条都过了才算通过,任何一条失败,合并请求就合不进去。CI 的检查是全量的,和提交前钩子的“只查改动文件”正好互补:钩子负责快、负责及时,CI 负责全、负责兜底。有人绕过钩子提交了格式不对的代码,CI 会在合并之前拦住;有人在新电脑上没装钩子就提交了,CI 同样会拦住。
CI 的规则档位要和本地保持一致:本地是 warn 的规则,CI 里也是 warn;本地升到 error 的,CI 里同样升到 error。两边不一致最容易出怪事:本地提交一路绿灯,到了 CI 全是红灯,或者反过来。规则的唯一来源应该是配置文件本身,本地和 CI 只是同一个配置文件的两种跑法。
规则怎么定:先宽后严,别一上来就全开 error
规则定多少、定多严,是门禁成败的关键。最常见的失败方式是一上来就把所有规则开成 error:第一次提交满屏报错,Agent 为了过检查开始乱改代码,把能跑的代码改成不能跑的,把警告修成了 bug。门禁的目的是让代码变好,不是让提交变难。
推荐的顺序是:第一周只开推荐集(js/recommended),格式全交给 Prettier,规则里真正会出 bug 的那几条(比如 no-undef)先设成 warn,让大家先看到问题、习惯被提醒。第二周把 warn 里反复出现、确实是错误的规则升到 error,比如没用到的变量、没定义的变量。第三周开始,根据项目自己的踩坑记录加规则:Agent 反复写错的地方,就加一条对应的规则;团队约定的写法,就写进配置里。
有三条规则不建议一上来就开成 error。第一,和风格有关的规则,一律交给 Prettier,不要在 ESLint 里再开一遍。第二,Agent 经常触发、但修起来要改结构的规则,先 warn、后 error,给团队留出适应的时间。第三,任何一条你说不清“它防的是什么 bug”的规则,先不要开。规则文件里的每一条规则都应该能讲出它防住过哪类真实错误,讲不出来的规则就是噪音,迟早会被人绕过。
五个坑:门禁装好了也可能白装
第一个坑:生成的文件没进 ignore。构建产物、第三方库、自动生成的类型定义、体积很大的数据文件,这些都不应该被检查。Prettier 有 .prettierignore,ESLint 有自己的忽略配置,两个地方都要配。漏配的后果是检查越来越慢,最后慢到没人愿意等,钩子就被绕过了。
第二个坑:编辑器插件用的不是项目本地版本。Prettier 的文档里特意提醒:编辑器插件会用你本地装的 Prettier 版本,千万别让编辑器用了一个比项目更新的版本,不然编辑器保存时改出来的格式和项目里的版本不一致,提交时钩子又改回去,两个人来回打架。正确做法是编辑器只用项目本地装的版本,版本跟着 package.json 走。
第三个坑:全量格式化和功能改动混在同一个提交里。前面说过,第一次全量格式化要单独提交,之后也一样:不要在一次功能提交里顺手把整个文件的格式全改了。格式变化和逻辑变化混在一起,评审看不出改了什么,出问题回滚的时候也不敢回滚。想统一格式就单独提一个“格式化”提交,写清楚只改格式、不改逻辑。
第四个坑:规则太多,警告太多,没人看了。警告(warn)不影响退出码,所以攒几百条警告也不会拦住提交,时间一长大家就学会了无视警告。警告要定期清:每周花十分钟,把反复出现的警告修掉、或者把规则升成 error、或者把规则关掉。三选一,不要让警告一直挂着。
第五个坑:只给新代码立规矩,老代码不管。门禁只检查新改动的文件,老文件里的历史问题没人碰,这是对的——不要为了过检查去动没问题的老代码。但老文件一旦被改动,lint-staged 就会检查整个文件,包括里面历史遗留的问题。这时候不要为了提交去修整文件里所有历史问题,只修本次改动引入的问题,历史问题记下来、单独排期修。
一个完整的例子:虚构的“小记账”接入门禁的三天
下面用一个虚构的“小记账”项目走一遍完整流程。这个例子是编的,项目名、文件名和数字都是为了演示,别当成真实数据。“小记账”是一个记账小工具,代码 mostly 是 Agent 生成的,已经写了三个月,风格越来越乱。
第一天,装 Prettier:按文档装好、锁定版本,建好 .prettierrc 和 .prettierignore,跑一次 npx prettier . --write 全量格式化,单独提交一次。这一天结束,仓库里所有文件的格式都统一了,提交历史里多了一个“格式化”的提交,之后每次提交的 diff 都只剩真正的改动。
第二天,装 ESLint:跑向导生成 eslint.config.js,继承 js/recommended,装上 eslint-config-prettier 关掉冲突规则,把 no-unused-vars 和 no-undef 先设成 warn。第一次跑 npx eslint .,报出来 47 条警告:其中 31 条是没用到的变量,16 条是没定义的变量名。修掉其中 40 条,剩下 7 条是 Agent 凭印象编出来的变量名,对照着改掉了。这一天结束,低级错误清零了。
第三天,装钩子和 CI:按文档装好 husky 和 lint-staged,配好 pre-commit 钩子,验证了一次——故意留一个没用到的变量提交,钩子当场拦住;改好之后提交通过。CI 里加上 prettier --check 和 eslint 两条命令。这一天结束,门禁正式生效:之后每次提交都会先过钩子、再过 CI,格式问题和低级错误再也进不了仓库。
这个例子里有两点值得注意。第一,三步是按顺序来的:先格式、再规则、最后钩子,每一步都能独立验证,不用一次全配好。第二,数字是虚构的,但流程是照着文档走的:安装命令、配置文件、钩子写法、CI 命令,全部出自 ESLint 和 Prettier 的官方文档,照抄就能跑。
检查清单:三天落地一张表
最后是一份可以直接用的检查清单。第一天:装 Prettier 并锁定版本,建 .prettierrc 和 .prettierignore,全量格式化一次、单独提交。第二天:装 ESLint,跑向导生成配置,继承推荐规则集,装 eslint-config-prettier 关掉冲突规则,先把 no-unused-vars 和 no-undef 开成 warn,清掉存量警告。第三天:装 husky 和 lint-staged,配好 pre-commit 钩子(ESLint 先跑、Prettier 后跑),亲手验证一次钩子真的会拦,CI 里加上 prettier --check 和 eslint 两条全量命令。
还有三条是给“门禁失灵”的时候准备的。提交没被拦,先检查钩子文件在不在 .husky/pre-commit、lint-staged 的配置在不在 package.json、husky 有没有初始化成功,三个地方缺一个钩子就失效。ESLint 和 Prettier 打架,先检查 eslint-config-prettier 装没装、接没接上,格式问题只应该由 Prettier 说了算。CI 红了本地绿了,先对照两边的规则档位和版本是不是一致,版本不一致先统一版本,档位不一致先统一配置。
评论 (0)
原始来源
相关文章
2026 年 11 月 11 日,AWS 开源 UAEF:先把 LangGraph、LangChain、Strands、Bedrock AgentCore 等框架的运行记录翻成统一格式,再用 36 个指标、7 个维度打分,回归超过 5% 就亮灯。评审模型本身也被防了一手:打分要引原文作证,分数不能用来决定安全放行。
函数你每天都在调,这篇把你一直在做的事讲清楚。本文按 MDN 的《Functions》《Arrow function expressions》《Rest parameters》三篇官方文档讲清楚:声明与表达式、参数与实参、默认值、剩余参数、展开语法、返回值、箭头函数省写规则、this 的坑、回调与高阶函数、作用域。
JavaScript 里数字只有一种类型 Number,存成 64 位浮点数,所以 0.1 + 0.2 等于 0.30000000000000004。本文按 MDN 的《Basic math in JavaScript》《Math》《Number》三篇官方文档讲清楚:一种数字类型、浮点误差、钱改成分算、字符串转数字、NaN 与 Infinity、安全整数、四种取整、Math.random、Math 工具箱与显示格式化。