怎么修 Bug:从读到报告到关掉它的六步回路(含每步的最低证据)

修 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 修完要不要通知用户? 如果影响到了用户已经提交的数据、金额、订单状态,要主动告知并说明补救了什么;如果是短暂不可用且已恢复,一条状态更新即可。写在版本更新记录里也顺便解决了「客户问起来有没有记录」的问题。