前端项目的代码评审说实话在很多团队里就是个形式主义重灾区。MR 挂一天没人理临上线前 Reviewer 匆匆扫一眼回个 LGTM合并完功能上线三周后新同事改这段代码时才发现当初的设计全是坑。尤其是前端这个问题比其他岗位更严重——你光看代码 diff 根本看不出页面长什么样看不出交互流不流畅更看不出这个组件三个月后还能不能改。今天想分享的是我们团队沉淀下来的一套前端 Review 方案我把它整理成了一份 open-code-review 版的前端团队评审指南核心是把评审从“走过场”变成真正能卡住缺陷、提升工程质量的机制。这套方案适合谁适合 5 到 20 人规模的前端团队适合已经有基础规范但评审流于形式的团队也适合想从零搭一套评审流程的技术 Leader 参考。它不是某个开箱即用的工具而是“流程规范 人工检查清单 自动化工具链”的组合你完全可以根据自己团队的情况裁剪。我把它拆成几个部分先聊清楚评审到底要解决什么问题再讲 MR 流转节奏怎么设计接着给一份可以直接复制的前端评审检查清单最后说下自动化工具怎么配、实操中会踩到哪些坑。1. 前端代码评审最大的坑先想清楚评审到底要解决什么1.1 为什么前端评审比其他岗位更难做后端代码评审可以盯着接口返回、数据结构、事务边界一点点抠逻辑写错了就是明摆着的 Bug。前端不一样前端代码写出来最终呈现的是一个页面、一组交互、一串用户感受。你在 diff 里看到一个display: flex根本不知道它在真实屏幕上是不是把布局撑塌了看到一段useEffect也不知道它是不是导致页面卡顿的元凶。我见过太多团队的前端评审评论集中在“这个变量名不规范”“这里应该加个注释”这种层面。不是说这些不重要而是当评审长期停留在这种表面问题上大家慢慢就觉得评审没价值。真正的严重问题——组件边界没划清、状态管理混乱、没有任何错误处理、首屏体积暴涨——反而没人发现。open-code-review 这套方案要解决的第一个问题就是把评审的关注点从“代码长什么样”转移到“变更会带来什么影响”。1.2 评审目标必须分层不然 Reviewer 抓不住重点我们内部把评审目标分成三层每一层的优先级和通过标准都不一样层级关注内容典型问题是否阻塞合并第一层阻塞性缺陷功能正确性、数据安全、明显性能问题接口字段拼错、并发提交、XSS 注入是必须修第二层工程质量可维护性、复用性、可扩展性、规范性组件职责混乱、魔法数字遍地、样式硬编码原则上修改可分批第三层体验细节视觉还原、交互反馈、可访问性loading 缺失、键盘无法操作、颜色对比度不足核心路径必须达标很多评审垮掉就是因为 Reviewers 在同一时间把三层混在一起看。看到一个小样式问题就阻塞合并真正的接口错误反而没人提或者反过来体验问题一律忽略只盯着逻辑。我们现在的做法是MR 描述里直接声明变更涉及哪些层级Reviewer 按层级表逐项核对阻塞性问题必须要修非阻塞的可以打上“建议”标签后续处理。这样评审效率高了很多大家不用凭感觉找问题。1.3 这套方案适合什么样的团队如果你在一个人数较少、还在跑业务验证阶段的团队我建议你先别急着上全套流程。open-code-review 方案只适合已经有基础开发规范、组件库有一定沉淀、团队愿意投入时间做质量建设的场景。如果项目还在天天赶原型、连 ESLint 都没配齐你强行推评审流程只会变成大家的负担项目组对你的印象就是“那个人天天让我们写文档”。反过来如果团队已经吃过几次线上事故的亏或者发版后频繁要修回归问题那就非常适合引入这套方案。我们在落地时做的第一件事不是写规范文档而是把所有 Reviewers 拉在一起对齐了一个认知评审的目的是减少变更带来的风险不是评判代码作者的水平。这句话一定要写在团队 wiki 最显眼的地方因为它决定了整个评审文化的基调。2. 把评审流程落进 MR 流转里节奏、角色和完成标准2.1 一次评审的完整流转路径open-code-review 把评审流程拆成五个阶段每个阶段都有明确动作和产出。这里我用 GitLab 为例GitHub 或内部平台类似节点换成对应的概念就行。先看全流程开发自测 → 创建 MR → 自动分配 Reviewer → 异步评审 定时扫尾会 → 合并与复盘。开发自测阶段是最容易被忽略、但对评审质量影响最大的环节。我们在规范里强制要求开发者在提交 MR 之前必须自己把变更涉及到的页面在本地跑一遍关键的交互路径录一段短视频或者截几张关键状态图贴到 MR 描述里。这个动作一加上真人 Review 时就不需要重复验证“这个按钮点了到底有没有反应”Reviewer 能直接看到作者自测的痕迹很多低级错误在这个阶段就被作者自己消灭了。创建 MR 时我们使用一个统一的模板要求填写变更背景、影响范围、自测结果、是否需要视觉验收。如果你的 MR 描述只写了一句“fix bug”Reviewer 得从代码里反推你的意图评审效率自然低下。模板可以做成这样变更背景为什么要改、影响点改了哪些页面/组件、自测方式手动/自动化/录屏链接、风险点是否需要回归、是否涉及数据迁移。2.2 评审角色别混着来很多小团队没有角色之分谁有空谁 Review。这个模式在 3 人团队没问题到 10 人以上就会出现责任真空。我们把角色分成三类角色核心职责关注重点Author作者自测、写清 MR 描述、及时回应评论提供上下文解释设计意图Reviewer评审者按检查清单审代码、提意见、确认修改功能正确性、工程质量、体验细节Maintainer合并人最终把关合并处理冲突和回滚风险变更兼容性、回归风险、发布顺序Reviewer 自动分配的策略是与变更模块代码有过交集的人优先而不是随机分配。这样可以保证评审者对这个模块的上下文有基本认知提出的意见更有针对性。Maintainer 一般由团队技术负责人或者模块 Owner 担任他不需要逐行看代码但要确认一个事情这个变更合进去后万一出问题我们的回滚方案是什么。2.3 评审节奏异步为主会议为辅我们的评审以异步评论为主绝不开大型代码评审会。为什么因为评审会开到半小时以上后半段的评论基本都是客套话信息密度极低。异步评审给双方留了思考和回复的时间Reviewer 可以自己在本地跑一下代码Author 也可以冷静地回应质疑而不是在会议上被围攻。但纯异步也有个问题评论挂在 MR 上没人管一拖就是好几天。我们的解决办法是每周安排两次固定的“评审扫尾会”时长限制在 20 分钟只处理一件事把那些超过两个工作日仍未关闭的评审评论逐条过一遍能当场答复的当场答复需要深入讨论的拉当事人另外开小会。扫尾会不是追责会目的纯粹是避免评审积压。对于线上紧急 Bug 修复我们设有快速通道。流程可以简化但有一条红线绝对不能踩核心交易路径、涉及用户数据的变更无论如何都要过评审哪怕事后补评也要过。这里的逻辑是紧急修复本身出错的概率就比正常开发高如果因为紧急而不评审等于在最该把关的时候把门敞开了。3. 前端评审清单到底查什么20 个高频检查点拆解3.1 结构语义与可访问性第一眼看 HTML 结构先说 HTML。这块很多前端评审根本没人看但它实际上是影响后续可维护性的基础。评审时我会先问三个问题这个页面的结构是不是用语义化标签搭的焦点管理对不对表单控件有没有关联 label实操中经常看到的典型问题整页都是div嵌套没有任何header、main、nav语义弹窗关闭之后焦点没有回到触发元素上键盘用户下一次 Tab 不知道落在哪表单输入框没有对应的 label读屏用户完全不知道要在这个框里填什么。这些问题在上线前不抓后面做 SEO 优化、做无障碍改造时全都要返工。顺便提一个高频的键盘可达性问题下拉菜单、Tab 切换这类组件很多实现是鼠标点击正常、键盘操作完全没用。评审时你可以直接问作者“这个组件键盘能不能操作”答不上来基本就是没做。这块我们不强求每个页面都达到 WCAG AAA但核心用户路径——注册、登录、下单、表单提交——必须键盘可达。3.2 样式与视觉还原CSS 评审要点CSS 评审是前端独有、且最容易出问题的部分。我们踩过的坑集中在三个方面布局稳定性、样式隔离、响应式表现。布局稳定性上最常见的是 flex/grid 排列和 min-width/max-width 缺失导致的内容挤压。一个典型场景列表项里有一行文本较长在宽屏下正常一缩窄就撑破容器。评审时看到新的布局组件要求作者本地至少过一遍三种宽度375px手机、768px平板、1280px桌面。样式隔离这块要重点看组件样式会不会污染全局。早年吃过一次大亏一个页面里的.content样式把另一个页面同类名的样式覆盖了排查了两天才发现是全局选择器冲突。现在评审统一要求新组件样式必须使用 CSS Modules、Scoped 或者 BEM 规范严禁裸写全局 class。除非是设计系统级的全局 token。视觉还原的评审我们鼓励用“还原度截图”来对比。作者在 MR 描述里贴设计稿和实现截图的对比图Reviewer 只需要快速扫一眼有没有明显偏差。这个动作看起来简单实际效果非常好能把很多“细节没调”的问题提前暴露。3.3 交互状态不能只看正常流程前端页面开发有个通病主流程跑通了就收工Loading、空数据、报错三个状态完全不处理。评审时这是必查项尤其是这三点异步请求时有没有 Loading 反馈数据为空时页面是白屏还是有空状态引导接口报错时有没有错误提示和重试入口我评审过太多组件正常数据下光鲜亮丽数据一空就渲染出一片空白。这种问题在需求文档里往往不会写但不处理就是体验事故。在 open-code-review 清单里我们把这些状态统称为“三态检查”请求中、成功态、失败态一个组件接数据了就必须把三态都做出来。按钮的防重复提交也是高频问题。用户点了一下“提交”接口没返回用户又点了一下结果后端收到两条订单。这个在前端是非常容易避免的缺陷进入提交态后按钮置灰或者加 loading评审时看到任何表单提交逻辑都提醒自己检查一遍这个点。3.4 组件设计与数据流逻辑层的评审重点Vue、React 项目里组件设计是评审的重头戏。我会重点关注组件 props 是否设计合理、组件是否做了它不该做的事、数据流是否清晰单向。先说 props 设计。一个典型反例某个按钮组件为了适应各种场景塞了十几个 props调用时根本不知道哪些组合是合法的。我们在评审中提倡“暴露最小化”原则——props 宁少勿多能内部收敛的逻辑不要外抛。另一个问题是组件里直接发请求、直接操作全局状态这种组件基本没法复用。合理的做法数据获取放在页面容器层组件只接收数据和回调。数据流这块不管是 Redux、Pinia 还是 Zustand评审时问一句这个状态真的需要全局共享吗很多场景 localStorage 就能解决或者父组件通过 props 传递即可。全局状态滥用是前端代码腐化的头号原因评审必须对这个点保持敏感。副作用处理这块我列几个 Reviewer 要特别留意的场景定时器有没有在组件卸载时清除事件监听有没有 removeEventListener订阅有没有退订我们曾经遇到过一个很隐蔽的内存泄漏一个组件在useEffect里注册了全局键盘事件但只在特定条件下才卸载结果用户在不同页面间切换后同一个事件被注册了几十次页面越来越卡。3.5 性能与安全的基线指标性能评审不能靠感觉要定指标。我们在 open-code-review 的规范里明确了几条基线单页面首屏 JS 体积不超过 250KBgzip 前单张图片超过 100KB 必须走懒加载新增接口请求必须评估缓存策略。评审时看到超过阈值的变更Reviewer 有责任阻塞合并要求作者做拆包或懒加载优化。安全这块前端也不能完全甩给后端。特别关注三个点dangerouslySetInnerHTML或v-html的使用只要有用户输入拼接进 HTML 的场景就存在 XSS 风险敏感信息token、密钥有没有被塞进前端代码或者 localStorageiframe 嵌入外部页面时有没有配置sandbox权限。还有一个容易被忽视的点新引入的 npm 包。评审时如果发现 package.json 里多了依赖Reviewer 应该追问一句这个包解决了什么问题有没有更轻量的替代方案我们每周用依赖安全扫描工具检查一遍发现过几次有已知漏洞的依赖被质量不高的团队无意识地引入生产环境。3.6 前端评审检查清单速查表把上面提到的高频检查点整理成一张速查表可以直接打印出来贴在工位上模块检查项阻塞级别结构语义语义化标签、表单 label、焦点管理核心路径阻塞样式样式隔离、响应式三档验证、z-index 治理阻塞无隔离交互三态齐全、防重复提交、动画可关闭核心三态阻塞数据流props 最小化、状态归属、副作用清理阻塞内存泄漏性能首屏体积、图片懒加载、依赖合理性超过基线阻塞安全文本渲染、密钥泄露、iframe 权限任何一项都阻塞可访问性键盘可达、颜色对比度、读屏语义核心路径阻塞工程质量命名规范、注释意义、复用性建议不阻塞4. 用自动化把 60% 的评审意见前置消灭4.1 提交前钩子让低级问题根本到不了 Reviewer 手里open-code-review 的核心理念是人工评审很贵自动化很便宜凡是机器能判断的问题尽量别让人类花时间。我们通过 Husky lint-staged 在提交阶段自动跑三个检查ESLint代码规范与错误拦截、Stylelint样式规范、Prettier格式化。这里有个经验之谈。lint-staged 只对暂存区文件生效所以速度很快不会让你等太久。如果你在 CI 里才跑全量 lint发现错了还得改完再推一次来回成本高。在本地提交前直接拦截能最大程度减少“Reviewer 因为一个分号/引号问题给你打回”的尴尬局面。Prettier 推荐直接用默认配置不要花大量时间在代码风格争论上。我们在评审中有一条不成文的规定风格问题不讨论格式化交给工具。谁的 IDE 和 Prettier 配置不一致那是他本地环境问题不是代码评审该管的事。4.2 CI 流水线里加什么检查性价比最高提交后我们在 CI 里加了四道关卡每一道都有明确目的第一道是类型检查。TypeScript 项目跑tsc --noEmitJavaScript 项目跑 JSDoc 类型检查如果有。这能拦住一批很低级但很常见的错误——方法签名不一致、枚举值错写、空值未处理。第二道是测试。我们不强求覆盖率指标达到多少但要求所有工具函数、公共组件必须有至少一个核心行为测试。评审时看到新增了一个纯函数却没有对应的单测这个 MR 会被打回要求补测试。这里的关键逻辑纯函数是最容易测试的单元你不给它写测试说明你对这段代码没有信心。第三道是构建产物对比。我们用 CI 跑一次build对比这次变更前后的各 chunk 体积变化超过阈值就在 MR 评论区自动提醒。这个自动化能第一时间暴露“随手 import 了一个大库导致首屏体积暴涨”之类的问题。第四道有点特别我们检查变更文件范围。如果 MR 描述说“修复登录按钮样式”但 diff 里混进了 10 个无关文件CI 会直接标记。这条规则逼着开发者养成小步提交的习惯也让 Reviewer 不用浪费时间排查无关改动。4.3 自动化能做到什么做不到什么自动化解决了“显性错误”语法错误、类型错误、常用模式的反模式比如 console.log 遗留、debugger 语句、体积超标、安全依赖。大概能拦截掉我们日常评审意见的 60% 左右效果非常明显。但自动化解决不了设计层面的问题组件拆分合不合理这个功能放在这个模块里是否合适现在的状态管理方案三个月后还扛不扛得住这些只能靠有经验的人来回答。所以我们在团队里反复强调一句话自动化是为了给人工评审腾出时间让人去思考真正重要的问题而不是为了减少人工评审。如果配合 CI 检查之后Reviewer 反而觉得“反正自动化已经检查过了我可以随便看一眼”那就走偏了。在我们的流程里自动化检查通过只是“可以开始人工评审”的条件不是“可以通过评审”的充分条件。5. 实操中踩过的坑评审冲突、紧急发布和新人保护5.1 评审意见吵起来了怎么收场评审不是辩论赛但实际操作中作者和 Reviewer 意见冲突的情况非常多。最常见的桥段作者认为自己的方案没问题Reviewer 认为有隐患双方在 MR 评论区一来一回从技术讨论逐渐变成面子之争。我们定了两条规则来避免这种僵局。第一条一切以证据说话。觉得方案有问题就给出具体场景、具体数据、或者一段最小复现代码。光说“我觉得这么写不好”是没有说服力的。反过来作者如果觉得 Reviewer 的意见不合理也要用场景说明“在什么条件下你的方案更优”。双方如果直接搬代码样本出来对比讨论会高效得多。第二条评审意见要有级别标签。我们在评论开头用[Block]、[Suggestion]、[Nit]标注意见级别。Block 表示必须修改才能合并Suggestion 表示建议修改但不阻塞Nit 表示纯风格/小问题可自行决定。有了这个约定作者不会把每一条意见都当成必须修改的“圣旨”Reviewer 也不会因为小问题过度使用阻塞权。5.2 紧急修复到底能不能跳过评审能跳但是要跳对。我们团队把变更分为三类绿色变更文案修改、样式调整、纯加代码不涉及删改、黄色变更涉及组件逻辑修改、但影响范围可控、红色变更核心流程、数据写入、权限相关。绿色变更可以走极简流程——直接合同事写一句同步到群里即可黄色变更需要有另一位同事快速看一眼红色变更无论如何都要正常评审没有例外。这个分类的价值在于不会因为一个文案修改非要凑两个人走全流程也不会因为“紧急”就把核心交易的改动作弊过关。我们经历过一次线上事故就是某个“十万火急”的修复没走评审直接上线结果匆忙之下改错了一个字段名反而加速了故障扩散。从那以后全员达成了共识越是紧急越是不能省评审——紧急时刻你的判断力最不可靠。5.3 新人被评审到自闭怎么办前端评审在推进过程中最痛苦的问题之一是新人改了一天代码提交 MR 后被 Reviewer 提了十几条意见改完第二轮又是几条第三次终于合并了但新人的自信也被打击得差不多了。更麻烦的是如果 Reviewer 的态度是挑刺式的新人下次都不敢提交代码了所有改动都偷偷找人私下看。open-code-review 的经验是两条线同时做。第一条线评审意见要写成“教方法”而不是“判对错”。比如把“这里有问题”改成“这里有一个边缘情况你可能没考虑到当用户快速点击两次时候会发生什么”前者是评价后者是引导效果完全不同。第二条线给新人安排结对评审。第一次走完整流程时由一位老同事带着新人一起评审别人的 MR让新人先看别人怎么被评、怎么回复再变成他被评时心里就有底了。我们还会每月做一次“高频评审意见复盘”把当月出现次数最多的十类评审意见整理成文档放进团队 wiki。半年下来这份文档已经沉淀成团队的《前端开发避坑手册》新同学入职看一遍就能避开一大半常见问题评审中的重复劳动大幅减少。5.4 评审意见怎么写对方才愿意听最后分享几个写评审意见的实操技巧。第一先说影响后说建议。不要上来就“你应该用 xx”而是“这样写会导致用户在弱网环境下看到空白页我建议加一个 loading 状态”。第二能贴代码就贴代码。评论里给一小段示意代码比写五百字说明效果更好但注意只是示意不要直接替作者重写整个方案。第三别在评论里用反问句。“你为什么不用 xxx”这句话无论语气多温和阅读时都会带刺改成“这里用 xxx 会不会更合适”就完全不一样。我们团队内部甚至总结了一句话评审意见是对代码说的不是对写代码的人说的。只要坚持这个原则评审氛围会明显变好。最后分享一点个人体会这套 open-code-review 方案在我们团队落地了半年多效果最直观的体现是线上回归事故减少了大概一半新人的代码质量曲线明显更陡峭。但这套方案不是一落地就完美的中间我们调了很多细节比如评审意见级别从三种改成三种中间试过五种维护成本太高又撤回、自动分配的算法也换过一版。所以我的建议是先从小团队试点把你觉得最重要、最痛的那几个检查点先立起来跑两个迭代后再逐步加上流程和工具。评审方法和代码一样要靠迭代来打磨指望一步到位设计出完美方案本身就不现实。
