修 bug 是让一个可复现的缺陷停止复现,并留下它不会复发的证据。 前半句是「改代码」,后半句是「关掉它」——大多数团队只做前半句,于是同一个问题三个月后换个入口再来一次。修复的质量不看改动有多巧妙,看的是下一轮回归、下一个接手的人、三个月后的你,能不能只靠这条记录就判断它真的没了。
本文只讲「怎么修、怎么验、怎么关」。至于「先修哪个」,属于分诊,见缺陷分诊指南;怎么写出一份能被修的 report,见缺陷报告应包含哪些内容。
六步回路
每一步都有「最低证据要求」。达不到就退回上一步,不要往下走——这是整篇文章最实用的一条规则。
| 步骤 |
做什么 |
最低证据要求 |
达不到怎么办 |
| 1 读报告 |
判断这条报告能不能开工 |
页面 URL、环境(浏览器 / 系统 / 版本)、预期与实际 |
退回补充,不要靠猜 |
| 2 复现 |
在自己手上让问题发生一次 |
一次确定的复现,或明确写下的「无法复现」结论 |
记录已试过的条件,挂起而不是关闭 |
| 3 定位 |
找到「哪一层」出的问题 |
一行报错原文、一条失败请求,或一次二分结论 |
停止改动,补观测手段 |
| 4 改 |
用最小改动修掉根因 |
一个改动只对应一个原因 |
拆成多个提交 |
| 5 验 |
证明修好了,且没弄坏别的 |
原路径再走一遍 + 边界再试一次 + 回归矩阵 |
不许「看起来好了」 |
| 6 关 |
让下一个人能读懂 |
一句 root cause + 一条证据链接 |
不许只写「已修复」 |
第 1 步:读报告,先判断能不能开工
一条能开工的报告至少三样:在哪、什么环境、期望与实际差在哪。缺任何一样,正确动作是退回补充,而不是打开代码先找找看。
「先找找看」的成本被严重低估:开发花 40 分钟猜出来的「那个页面」,有相当比例根本不是报告人说的那个页面。一轮退回的成本是 2 分钟。
第 2 步:复现,或者明确说「复现不了」
复现是修 bug 的分水岭。能稳定复现的问题,定位只是时间问题;复现不了的问题,任何改动都是赌博。
复现时有三件事要固定下来,否则你复现的不是同一个问题:
数据状态:登录哪个账号、有没有缓存、localStorage 里有没有旧版本数据。
构建版本:前端包版本、后端提交号、有没有开 feature flag。
操作时序:是刚进页面就点,还是等了几秒、切过 tab、网络慢的时候。
如果确实复现不了,把它记为「无法复现」并带上三个问题,而不是直接关掉:
- 你当时在哪个页面、哪个入口进来的?(原始 URL 常常带参数)
- 发生的时间点是什么?(能对上日志或部署时间就有线索)
第 3 步:定位,先确定「哪一层」
修得慢,八成不是因为难,而是因为在错的层里找。先用三个动作把范围压到一个层:
| 动作 |
看什么 |
能排除什么 |
| 看控制台 |
报错原文与堆栈 |
能排除「纯样式 / 纯数据」问题 |
| 看网络面板 |
有没有 4xx / 5xx,请求体与响应体对不对 |
能区分「前端没发出去」和「后端返回了错的东西」 |
| 二分 / 回滚 |
上一次正常是什么版本、什么提交 |
能排除「一直就是这样」的误解 |
报错原文怎么读,见日志等级说明与编程错误的类型;控制台怎么开见打开浏览器控制台。非开发的同事想自己先看一眼,见给非开发者的浏览器开发者工具。
一个具体的判断顺序:接口返回 500 → 后端问题;接口返回 200 但字段不对 → 契约问题;接口没发出去 → 前端逻辑或校验问题;接口正常、界面不对 → 渲染问题。 四句话能覆盖 Web 团队八成的问题。
第 4 步:改,用最小改动
「最小改动」不是保守,是可验证性。一个 PR 里同时做了三件事(修 bug、顺手重构、升了个依赖),出问题时你无法判断是哪一件导致的——于是第 5 步的「验」就不可能通过。
两条具体规则:
- 一个提交只对应一个原因。 如果你在修的过程中发现了第二个问题,单独开一条。
- 顺手重构留给专门的时间。 修 bug 时重构,等于把「已知风险」和「未知风险」混在一起。
第 5 步:验,证明「修好」而不是「藏起来」
这一步是本文和大多数「修 bug 教程」最大的区别。下面四种做法会让缺陷消失,但问题还在:
| 做法 |
表面效果 |
实际后果 |
try / catch 空捕获 |
报错没了 |
后续逻辑静默失败,数据悄悄写错 |
| 放宽校验 |
不再报错 |
脏数据进了库,几个月后才发现 |
| 隐藏入口 |
用户点不到了 |
需求还在,改从别处提,行为不一致 |
| 加一个永久关闭的开关 |
现象不出现了 |
开关本身成为一段没人敢删的代码 |
判断标准只有一条:用户原本想做的事,现在能做了吗? 而不是「这个报错还在不在」。
验证要做三件事:
原路径再走一遍 —— 报告里描述的那条路,从第一步到最后一步。
边界再试一次 —— 空值、超长文本、emoji、时区、金额小数、无权限账号。这六个是最常见的复发点。
跑一遍回归矩阵 —— 这次的改动牵连到哪些旧功能,见回归测试怎么跑。
第 6 步:关,写一句 root cause
关闭一条缺陷时只写「已修复」,等于把成本留给了下一个人。一句完整的 root cause 包含三段:
text
根因:订单提交时先清空表单再发请求,请求失败后表单已空,
用户重试时提交了空数据,接口返回 500 被前端静默吞掉。
修复:调整为先发请求、成功后清空;移除静默 catch,改为展示错误提示。
验证:Chrome 141 / macOS 14,断网重试 3 次均提示「提交失败,请重试」,
表单内容保留;回归:结算流程、优惠券、地址簿。
这三段分别回答「为什么坏的」「改了什么」「怎么证明」。它们比代码 diff 活得久——半年后 diff 被重写、文件被拆、甚至整个模块被替换,这条评论还在。
证据别只贴在聊天里。截图、录屏、失败请求要跟着这条记录一起存,否则三个月后回归失败时,你想翻「当年是什么样」,翻到的是一个失效的图床链接。BugCapturer 的浏览器扩展在提交时就把控制台报错、失败请求、页面 URL、浏览器与视口一起带走,并生成一条可分享的链接,团队档下报告长期保留——目的很单纯:让「原报告还能打开」这件事在三个月后依然成立。
复现失败的三个真实原因
「无法复现」在缺陷系统里是个黑洞。它通常不是运气问题,而是这三类差异:
1. 环境差异。 最常见的五样:构建版本(本地跑的是最新 main)、缓存(浏览器缓存、Service Worker、CDN)、feature flag、权限与角色、时区与语言。排查动作是把这五样逐条对齐,而不是「你再试一次」。
2. 数据差异。 用户的数据里有一个 300 字的备注、一个 emoji 昵称、一个 null 的中间名、一个负数金额。界面在「正常数据」上永远是对的。能复现的人通常是拿到了那条具体记录的 ID。
3. 时序差异。 异步竞争、懒加载、防抖、第三方回调的顺序。这类问题在快网络下不出现、慢网络下必现,在开发机上永远正常。排查手段是限速与人为延迟,不是加日志。
遇到「无法复现」,正确的记录方式是:挂起 + 已试条件清单 + 三个问题(入口 / 账号 / 时间点)。关闭它是最坏的选择——你会失去「这个问题发生过」这条信息,而且它一定会再来。
patch、hotfix、常规修复:三种节奏别混用
同一个 bug,走哪条路取决于影响面和紧急度,不取决于难度:
| 常规修复 |
patch |
hotfix |
| 场景 |
不影响主流程、可等版本 |
小范围但需要尽快 |
线上主流程中断 / 资损 / 安全 |
| 流程 |
正常迭代、走评审 |
随下一个小版本 |
绕过常规流程、事后补评审 |
| 必须补的 |
回归矩阵 |
回归矩阵 + 变更记录 |
回归矩阵 + 变更记录 + 事故复盘 |
| 最容易漏的 |
边界验证 |
通知到受影响用户 |
只修表面、不修根因 |
三种节奏里,hotfix 的风险不在修得快,而在修完之后没人回头:临时改动留在代码里、回归没补、复盘没写。一次 hotfix 之后至少要留三样东西——一条发布记录、一轮针对性的回归、一句「为什么会漏到线上」。发布记录怎么写见版本更新记录。
五条团队规则
如果只能带走五条:
报告不合格先退回,不要靠猜。 退回 2 分钟,猜测 40 分钟。
一个提交只对应一个原因。 混合改动让你无法验证,也无法回滚。
关闭时必写 root cause + 证据链接。 这是唯一一条能让半年后的人少花一天的规定。
「无法复现」不是关闭理由,是挂起理由。
修完不回填回归矩阵,等于没修完。 漏测的那一格,就是下次事故的入口。
缺陷和需求、错误和 bug 的边界容易混,见bug、defect、issue、error 的区别;如果你要管的是「修完之后怎么让客户知道」,见把缺陷报告分享给客户。
常见问题
修 bug 和做新功能怎么排优先级?
用影响面 × 频率,而不是「谁喊得响」。这条判断标准见缺陷分诊指南里的严重度 × 优先级矩阵。本文只强调一点:排完序之后不要中途反复插单,反复插单的团队通常两条线都做不完。
一次改多个 bug 可以吗?
只有在同一个根因、同一处改动时才可以(一个原因导致三个现象,是同一个 bug)。不同根因的缺陷放进同一个提交,会让回滚变成不可能——线上出问题时,你只能整包回退。
每个 bug 都要写单元测试吗?
不需要。值得写测试的是三类:会复发的(有过 regression 记录)、逻辑有分支的(边界条件多)、数据计算类的(金额、比例、日期)。纯展示、纯文案的修复靠回归走查就够。
修完发现还有别的问题,要不要一起修?
不要。单独开一条记录。把第二个问题混进来,等于让第一步的验证失效——你无法确定是哪个改动让问题消失的。
线上 bug 修完要不要通知用户?
如果影响到了用户已经提交的数据、金额、订单状态,要主动告知并说明补救了什么;如果是短暂不可用且已恢复,一条状态更新即可。写在版本更新记录里也顺便解决了「客户问起来有没有记录」的问题。