你在深夜收到一条消息“这个需求怎么成这样了”或者“线上有个Bug你看一下”然后你打开日志发现一切都很正常你刷新页面问题消失了你顺手点了一遍接口发现数据又是对的。等你准备回复“我这边复现不了”的时候用户又甩过来一张截图上面只有一个被红圈圈住的位置而红圈下面还有一行更让人头大的话——“这Bug太气人了”。这句话几乎是所有开发者的共鸣。Bug本身并不会说话真正让人觉得气人的是它出现的前提、环境、时序都不在同一个上下文里你这边没有人家那边有代码半年没动今天突然报错开发环境一切正常测试环境一跑就崩。这种Bug最折磨人的地方不是修复的那几行代码而是排查过程中巨大的不确定性。这篇文章不打算只讲“态度要端正”这种虚话而是把“这Bug太气人了”这件事拆成一整套可落地的排障流程先定性、再复现、后定位、再修复、最后回归。我会结合常见的前端Bug、后端Bug、依赖问题、内存问题、基础设施状态问题以及这两年很容易出现的AI模型推理类问题给你一份可以直接抄到工作里的排查框架。读完你应该能搞清楚一个Bug从“气人”到“好查”中间到底差了什么。1. Bug真正的杀伤力不确定性的成本1.1 会报错的Bug并不可怕先纠正一个错觉报错越明确Bug越好修。如果前端按下按钮后明显请求失败后端的错误日志指向/api/order/123然后告诉你SQL里表不存在这种情况下通常不会有太多抱怨——问题清楚修复方案明确改完上线测试即可。真正让人崩溃的是那种“什么都不报错但结果就是不对”的问题。举一个很常见的场景用户在某个旧版本的App里登录后界面空白测试环境用同一个账号却正常后端日志显示请求已经响应状态码200前端控制台也没有红色报错唯一不对劲的是接口返回的内容和浏览器实际渲染的内容对不上。这种问题有一个共同特征每一个环节单独看都是正常的但组合在一起就出错。你花费大量时间不是在“修复”Bug而是在“寻找”Bug。可问题是Bug不会主动告诉你它藏在哪一层。1.2 让Bug气人的是“隐性前提”如果一个Bug需要满足特定版本、特定数据、特定操作顺序才会触发那么整个排查过程会迅速从“看日志”变成“猜谜”。开发环境复现不了因为数据不同测试环境又稳定复现因为数据里有脏数据生产环境偶尔出现因为你只测了三次而用户点了三十次。这就是“隐性前提”。它不一定是什么高深的技术问题很可能只是用户上传了一个文件名特别长的附件某个字段在极端条件下变成了null多线程场景下共享变量被并发修改一个全局单例在重启后没有清空缓存组件A先于组件B挂载而代码默认B先完成。所以这篇文章的第一个核心判断是处理Bug的能力本质上不是代码写得快而是压缩不确定性空间的速度。你能多快把一个“偶现、无报错、只有用户能复现”的问题变成一个“稳定复现、有日志、有明确断言”的问题你就能多快下班。2. 拿到Bug先定性代码、环境、依赖还是前端与后端的分工问题2.1 前端Bug还是后端Bug从接口视角判断很多团队在协作时最没效率的对话就是前端说“后端接口返回的字段不对”后端说“接口我curl了一下没问题”前端说“可页面上就是不对啊”后端说“那我再看看”。这种对话循环的前提是双方都在用“自己的视角”理解同一个Bug。而解决“前端Bug还是后端Bug”这种问题最有效的办法是直接绕开页面和UI先验证接口本身。当你在浏览器、小程序或App里发现一个表现异常时可以先打开开发者工具里的Network面板找到对应的请求然后复制其URL直接在终端里发一遍curl -i -X GET \ -H Content-Type: application/json \ http://127.0.0.1:8080/api/order/123如果返回的数据和预期一致那问题大概率出在前端渲染、参数组装或交互逻辑上如果返回数据本身就是错的那问题就向后端方向走。这种办法看起来很简单但在实际团队协作中它能让责任边界立刻清晰起来。2.2 快速定性清单我建议每个项目都维护一套简单的“Bug快速定性表”不需要多复杂但至少要能回答下面这几个问题排查视角核心问题常用工具前端交互页面是否真的把参数传给了接口浏览器DevTools、Network面板、Vue/React DevTools前端渲染数据到了页面之后渲染逻辑是否正确控制台、断点、组件状态检查接口层接口收到的请求是否符合预期curl、Postman、网关访问日志后端逻辑接口处理逻辑在什么条件下会出错后端日志、慢查询日志、断点环境差异是否只有某类环境、设备、版本才会触发环境变量对比、容器镜像对比、设备真机依赖/构建依赖版本或构建产物是否和源码一致npm ls、pipdeptree、构建记录这个表的价值在于还没开始修复时你就可以先确定“不要在哪里浪费时间”。2.3 定性至少要能跨过三堵墙第一堵墙是“开发环境 vs 测试环境”。一个Bug如果只在特定环境出现第一反应不应该是改代码而是对比两边的配置、数据库、依赖版本和部署方式。很多时候环境变量差了一个前缀整个逻辑都会绕路。第二堵墙是“浏览器/终端 vs 服务端”。移动端出现屏幕滑动异常、页面闪退这类问题不少出现在WebView兼容性或前端资源版本不一致上后端日志往往没有直接信号。需要先用真机复现再决定往哪个方向查。第三堵墙是“业务代码 vs 模型/算法逻辑”。AI时代的Bug更特殊因为模型输出本身带有不确定性很多时候不是异常而是“结果不对”。这时候你很难用普通Bug的报错栈来定位问题。3. 从“气人”到“可排查”先复现再谈修复3.1 没有复现路径的Bug只能“观察”有一个共识不能复现的Bug不建议直接改代码。因为你看不到根因改完大概率是撞运气。很多开发者一拿到Bug就急着去改逻辑结果改了几轮最后发现真正的问题是测试数据写错了。复现不是为了走流程而是要找到一条可重复走到错误点的路径。如果你完全不知道怎么复现建议先做三件事向Bug提出者要完整的操作步骤精确到点击哪个按钮、输入什么内容要测试数据包括账号、文件、截图、表单内容索要环境信息包括系统版本、App版本、浏览器版本、网络环境。很多“气人Bug”其实不是技术难度高而是提出者只丢给你一句话“你打开页面看看不对。”这不算有效的Bug描述后面第七章会专门讲怎么写Bug单。3.2 写一个可运行的最小复现脚本当问题涉及后端逻辑、工具类方法或算法时“最小复现脚本”是非常有效的武器。不要直接在庞大的工程里断点运行先试着把问题从业务代码里剥离出来写成一段可以本地独立跑的小代码。比如你怀疑某个列表处理函数对异常数据类型处理有问题可以把函数单独抽出来执行# reproduce_bug.py import time def process_items(items): result [] for i, item in enumerate(items): time.sleep(0.01) if i 3: # 这里故意构造一个跨类型加法用于观察异常 result.append(item 1) else: result.append(item) return result if __name__ __main__: data [1, 2, 3, not_a_number, 5] print(process_items(data))运行结果会直接暴露异常发生在第几个元素以及item的实际类型。不要小看这段代码真正的业务场景里“处理到第4条数据就崩”往往就是因为数据里混入了一个非预期值而不是算法本身写错了。3.3 最小复现的三条纪律最小复现有三条纪律数据最小化不要用整库数据只要能触发Bug的那几行。依赖最小化尽量不要引入框架和外部服务如果必须引入注明版本。步骤最小化从“打开系统”到“报错”步骤越少越好。当你把问题压缩到这个程度Bug通常已经暴露了你能够照见的边界条件。4. Bug的生命周期状态流转和负责人的变化4.1 生命周期状态“Bug的生命周期”不只是流程还是一种工程习惯。一个Bug如果长期停留在“打开”状态就不只是技术问题更是管理问题。通常一个Bug会经历这么几个状态状态意义负责人新建提出者提交了Bug描述提出者待确认开发确认是否能复现、是否接受为缺陷开发修复中开发正在定位和修改开发待验证开发修复完成等待测试或提出者回归测试/提出者回归通过验证通过在版本中关闭测试/提出者重新打开回归不通过或再次出现测试/提出者这张表看似平淡但它回答了一个关键问题每一个时刻Bug都应该有一个明确的负责人。4.2 谁该推进状态流转现实中经常出现一种情况开发改完了Bug直接在聊天里说“改好了”然后测试一直没空验证三天后问起来开发又说“我不知道啊我不是说了改好了吗”。这种沟通低效的根源就是状态没有同步。不管团队用的是Jira、禅道、GitHub Issues还是简单的在线表格都至少要有一个人负责跟踪状态。团队里如果出现“Bug观察员”这种角色往往说明真正的问题不是Bug太多而是Bug信息流没有自动化大家只能靠人肉观察。正确的方式是提出者负责说清楚“我要什么”开发负责把Bug从“待确认”推到“待验证”测试或提出者负责回归回归通过后才能关闭。每一环不交接状态就不迁移。5. 最容易把人气死的四类Bug与排查方向5.1 依赖与原生模块无法加载native binding这类问题在很多前端和后端项目里error: cannot find native binding这类报错很容易让人一头雾水。它常常出现在升级依赖、切换Node版本、重新安装包之后。表面信息是“找不到原生模块”但背后通常有三种可能依赖安装过程中的可选依赖没有被正确安装Node或Python版本和本机编译的原生模块不匹配构建缓存残留了旧架构的二进制文件。常规排查命令如下# 查看当前依赖树确认是否包含未被安装的可选依赖 npm ls # 清理缓存和 node_modules 后重新安装 npm cache verify rm -rf node_modules package-lock.json npm install如果是Python项目也可以用类似思路pip list | grep 相关依赖 pipdeptree | grep 相关依赖注意重新安装依赖是改动环境的行为最好先在测试环境或本地分支验证不要直接在生产服务器上执行。除了命令本身更重要的教训是依赖相关Bug第一时间要对比的不是源码而是依赖锁文件和构建环境。5.2 内存越界与栈缓冲区溢出这一类Bug常见于C/C、嵌入式系统或系统级组件中。它的特点非常强烈不是每次都会崩但崩的时候往往是整个进程退出没有优雅的报错信息。比如嵌入式开发里如果你配置了DMA通道但缓冲区地址对齐方式、传输长度、中断优先级设置不当就可能出现数据错乱或栈溢出。这不是“改一行代码就能复现”的问题它和内存布局密切相关。排查方法是先复现记录崩溃时的调用栈用工具检查缓冲区边界比如ASan、Valgrind检查是否存在数组越界、字符串没有结束符、拷贝长度超过目标缓冲区等常见问题如果是修复脚本不要直接在线上执行先确认脚本内容在测试环境跑通并备份原配置。看到网上流传类似“检测到基于堆栈的缓冲区溢出修复.bat”这种脚本时不要盲目运行。任何涉及系统设置、注册表、文件替换的操作都要先看脚本内容再做隔离验证。5.3 基础设施状态Bug以Cinder卷分离失败为例在OpenStack等云平台环境中有一种Bug让运维和研发都头疼资源状态和期望状态不一致。比如虚机已经删除但绑定的卷一直处于分离失败状态。这时候不是代码报错而是云平台的资源状态机卡住了。排查这类问题首先要看的是资源的实际状态openstack server show server_id openstack volume show volume_id然后重点确认卷当前是否还被某个虚机引用是否有正在运行的迁移或快照任务控制节点和存储节点的日志是否执行到某一步中断数据库里记录的状态和真实后端存储状态是否一致。这类Bug不能靠重启解决关键在于状态修复。它提醒我们基础设施越复杂越需要在状态管理层多做幂等处理否则任何一个中断都可能留下“僵尸状态”。5.4 模型推理中的非确定性Bug长对话重复、chunk_size异常最近很多读者提到两类现象一类是LLM对话一长就开始出现重复回答另一类是某些推理框架调整了chunk_size后推理速度或内存表现异常。先说一个基本判断LLM的长对话重复并不总是模型“笨”更多时候是上下文工程和采样策略的问题。当对话历史太长超过模型的有效上下文设计范围后模型可能会丢失对前文的注意力导致生成内容开始“兜圈子”。排查思路可以从这几条入手检查历史消息是否被截断检查temperature等采样参数是否过低导致输出陷入局部循环检查生成后的后处理逻辑是否做过重复连续性检测观察是否是某个特定长度之后才开始重复如果是调节上下文窗口或分段策略。对于chunk_size这类推理框架参数遇到异常时不要只看参数本身。可以先看日志确认异常发生阶段是prefill还是decode再对比不同参数下的显存占用和耗时。如果确认是版本相关的问题优先更新到稳定版本并在测试环境用相同参数复现。这类Bug的难点在于“非确定性”同一段输入每次输出可能不同。所以修复后尤其需要反复回归而不是跑通一次就算结束。如果想在前端自动复现和验证这类交互问题也可以借助Playwright这类自动化工具录制用户流程再把步骤固化成回归用例npx playwright test tests/bug-repro.spec.ts6. 排查方法论让Bug“交底”6.1 用系统化采集替代灵感排查Bug最怕的是“灵感式排障”。一会儿改个配置一会儿清个缓存一会儿重启一下服务运气好就解决了但并没有真正搞清原因。更稳定的办法是采集完整证据链。拿到一个Bug时先确认下面这些信息# 采集应用运行日志不遗漏标准输出和错误输出 python -u main.py 21 | tee run.log # 查看关键服务是否在监听 ss -lntp | grep 8080 # 查看进程和资源占用 ps aux | grep java这段命令的作用是把系统表现、进程状态、日志信息一次性留底。这类信息不需要每一条都看懂但它是后续分析的基础。6.2 二分法缩小范围如果一个问题涉及到几十个文件的变更不要从头到尾读代码。更高效的方式是“二分法”。用git bisect可以快速定位是哪个提交引入了回归git bisect start git bisect bad # 当前提交是坏的 git bisect good commit_id # 已知某个旧提交是好的 git bisect run pytest -m regression它会自动选择一个中间提交执行回归命令然后根据结果继续二分。最终会告诉你“第一次让测试失败的提交”是哪一次。这个命令能极大压缩排查时间但它依赖两个前提第一你有稳定的复现脚本第二测试用例能自动返回通过或失败。6.3 让“偶现”变成“必现”很多气人的Bug都是偶现的。偶现不代表没有规律只是触发条件没有被发现。处理偶现问题时可以先考虑下面几个变量并发量是不是同时请求多个接口就会出问题数据量数据超过多少行才出问题操作速度用户点得很快才会出问题慢一点就正常缓存时机第一次访问正常第二次访问异常后端状态服务刚启动时正常运行一段时间后异常。给这些变量加上开关逐个打开和关闭通常能找到一个组合让问题从“偶尔出现”变成“必现”。6.4 日志记录的正确姿势如果你怀疑是后端某个函数执行异常但日志又不够细可以在代码中临时加入更详细的上下文日志。注意生产环境加日志要谨慎尽量使用现有日志框架并控制级别不要打印敏感信息。import logging logging.basicConfig( filenameapp.log, levellogging.DEBUG, format%(asctime)s %(levelname)s %(name)s %(message)s ) logger logging.getLogger(__name__) def handle(item): logger.debug(enter handle, item%r, item) # ... 原有逻辑调试完成后记得移除或降低日志级别避免给生产环境带来额外IO压力。7. 写一份让人愿意马上处理的Bug单7.1 标题怎么写才有画面感有一种Bug描述是这样的“来bug了图一的横线你看一下。”这种描述的问题在于不告诉我是什么平台、什么操作、什么数据只说“图一有根横线”。看图的人可能要看半天才能确认“横线”到底指什么。好的Bug标题应该像一条索引让人不看正文也能知道问题范围差标题登录有问题好标题iOS 16.4系统下输入正确密码后点击登录按钮无反应控制台无请求发出标题里至少要包含三要素设备/环境、操作动作、观察到的异常结果。7.2 Bug单字段清单一份可以快速流转的Bug单建议包含这些字段字段说明示例标题一句话描述问题订单详情页在苹果手机上滑动时偶发闪退环境系统、浏览器、App版本、分支Chrome 117 / iOS 16.4 / Android 12前置条件操作前需要准备什么需要登录一个VIP账号复现步骤精确到每一步操作1. 打开订单列表 2. 点击第二个订单 3. 向下滑动预期结果应该看到什么页面正常展示并可以滚动实际结果实际看到了什么页面闪退回首页日志/截图辅助证据附控制台报错截图或日志文件填完这张表大多数人已经能自行复现问题根本不需要在群里来回追问。7.3 附件的正确贴法截图是有价值的但截图最好附上时间、位置和必要的文字说明。不要只发一张满屏红色告警的图也不要只发一行被压缩成马赛克的日志。如果日志太长不要直接粘贴进聊天框保存成文件或放在日志平台然后在Bug单里填入日志ID。如果涉及敏感信息先做脱敏处理。8. 团队Bug制度与回归防线8.1 状态机要有人促流转很多团队把Bug工具当成记录本只记录不流转这是最大的浪费。Bug工具应该是工作流引擎。提出者提交Bug之后开发需要在约定时间内把状态改成“修复中”或“待确认”。如果连“是否能复现”都无法判断应该在状态字段中写明原因而不是让Bug躺在“新建”里。团队里每个人都可以是“Bug观察员”但更推荐的做法是把状态流转交给工具和流程让人只处理真正需要人判断的事。8.2 回归不要轻易说“改好了”修复Bug之后最容易翻车的场景是开发只验证了“问题路径”没有验证“相关路径”。比如你修复了一个订单支付状态不更新的问题导致支付成功的订单也能被重复支付。如果你只测了“支付失败后不更新状态”没测“支付成功后订单状态正常”那就等于引入了新Bug。建议在修复完成后至少回归三类场景主路径测试验证原问题不再出现边界路径测试用和问题相邻的边界数据再跑一遍受影响模块测试检查涉及同一函数、同一表、同一组件附近的功能。8.3 修复要区分“绕过”还是“根修”有些Bug修复起来很简单比如给参数加个默认值或者前端改成空值兜底。但你要清楚这是“绕过”还是“根修”绕过只解决当前表现根修要解决产生这个表现的根因。比如前端调用接口时后端返回了null导致页面报错。如果你只是在前端写一个if (res.data null) return []这是绕过如果后端能正确返回空数组并且查明为什么会出现null这是根修。成熟的团队在排期时通常会把“绕过应急”和“根修排期”分开记录避免绕过长期占用生产环境。9. 用工程习惯替代“运气”9.1 日志是可观测性的第一入口面对Bug第一反应不该是“改代码”而是“看日志”。但日志不是越多越好。瞎打日志会造成两倍噪音。好的日志至少要包含时间戳请求ID或业务ID函数/模块名关键入参结果或异常信息。有了这些排查者才能在数千行日志中快速拼出一次业务调用的完整路径。否则你只能靠“碰运气”。9.2 错误信息要抄写要有错误码很多人在聊天里复述Bug时会把错误信息记成“它报了一个错好像是什么绑定失败然后就不能用了”。这种表达丢失了最有价值的信息。正确做法是完整抄写第一行错误信息、异常类型、以及关键的堆栈前几行。如果系统支持错误码把错误码一并写进Bug单。错误码比自然语言可靠得多因为它能精确对应到代码路径。9.3 用安全兜底给Bug留退路没有Bug的软件是不存在的。所以工程习惯的另一半是怎么在不完美的情况下减少损失。数据库操作之前必须备份和回滚配置修改之前必须记录旧值生产环境执行命令之前先评估权限和影响范围重要逻辑加上开关和熔断防止Bug被放大。这套习惯不能杜绝Bug但能让Bug从“事故”变成“事件”。只要还有回退空间气人程度就会大幅度下降。9.4 心态Bug不是人品题是信息题最后说回开头的那句“这Bug太气人了”。程序员基本上都见过这种文件夹或者朋友圈文案“神兽保佑代码无Bug”。这是调侃但它的隐藏含义是Bug是一个随机事件只能靠运气压制。但真正的工程世界里Bug不是烂人品也不是随机惩罚它只是从系统行为到预期行为之间的一段信息差。你现在不知道正确答案是因为信息还没收集够。当你把日志、数据、操作路径、环境差异都摆到桌面上Bug基本已经退无可退。下次再遇到让你头皮发麻的问题不要急着骂人也不要急着改代码。先写复现步骤再拉日志再收藏本文里的排查清单。把一个气人的Bug变成一个走流程就能解决的问题这才是工程师真正的解压方式。 
长河君 · 2026/9/8 5:43:28 · 阅读 1.2k Bug排查实战：从定性、复现到根修与回归的完整流程
你在深夜收到一条消息“这个需求怎么成这样了”或者“线上有个Bug你看一下”然后你打开日志发现一切都很正常你刷新页面问题消失了你顺手点了一遍接口发现数据又是对的。等你准备回复“我这边复现不了”的时候用户又甩过来一张截图上面只有一个被红圈圈住的位置而红圈下面还有一行更让人头大的话——“这Bug太气人了”。这句话几乎是所有开发者的共鸣。Bug本身并不会说话真正让人觉得气人的是它出现的前提、环境、时序都不在同一个上下文里你这边没有人家那边有代码半年没动今天突然报错开发环境一切正常测试环境一跑就崩。这种Bug最折磨人的地方不是修复的那几行代码而是排查过程中巨大的不确定性。这篇文章不打算只讲“态度要端正”这种虚话而是把“这Bug太气人了”这件事拆成一整套可落地的排障流程先定性、再复现、后定位、再修复、最后回归。我会结合常见的前端Bug、后端Bug、依赖问题、内存问题、基础设施状态问题以及这两年很容易出现的AI模型推理类问题给你一份可以直接抄到工作里的排查框架。读完你应该能搞清楚一个Bug从“气人”到“好查”中间到底差了什么。1. Bug真正的杀伤力不确定性的成本1.1 会报错的Bug并不可怕先纠正一个错觉报错越明确Bug越好修。如果前端按下按钮后明显请求失败后端的错误日志指向/api/order/123然后告诉你SQL里表不存在这种情况下通常不会有太多抱怨——问题清楚修复方案明确改完上线测试即可。真正让人崩溃的是那种“什么都不报错但结果就是不对”的问题。举一个很常见的场景用户在某个旧版本的App里登录后界面空白测试环境用同一个账号却正常后端日志显示请求已经响应状态码200前端控制台也没有红色报错唯一不对劲的是接口返回的内容和浏览器实际渲染的内容对不上。这种问题有一个共同特征每一个环节单独看都是正常的但组合在一起就出错。你花费大量时间不是在“修复”Bug而是在“寻找”Bug。可问题是Bug不会主动告诉你它藏在哪一层。1.2 让Bug气人的是“隐性前提”如果一个Bug需要满足特定版本、特定数据、特定操作顺序才会触发那么整个排查过程会迅速从“看日志”变成“猜谜”。开发环境复现不了因为数据不同测试环境又稳定复现因为数据里有脏数据生产环境偶尔出现因为你只测了三次而用户点了三十次。这就是“隐性前提”。它不一定是什么高深的技术问题很可能只是用户上传了一个文件名特别长的附件某个字段在极端条件下变成了null多线程场景下共享变量被并发修改一个全局单例在重启后没有清空缓存组件A先于组件B挂载而代码默认B先完成。所以这篇文章的第一个核心判断是处理Bug的能力本质上不是代码写得快而是压缩不确定性空间的速度。你能多快把一个“偶现、无报错、只有用户能复现”的问题变成一个“稳定复现、有日志、有明确断言”的问题你就能多快下班。2. 拿到Bug先定性代码、环境、依赖还是前端与后端的分工问题2.1 前端Bug还是后端Bug从接口视角判断很多团队在协作时最没效率的对话就是前端说“后端接口返回的字段不对”后端说“接口我curl了一下没问题”前端说“可页面上就是不对啊”后端说“那我再看看”。这种对话循环的前提是双方都在用“自己的视角”理解同一个Bug。而解决“前端Bug还是后端Bug”这种问题最有效的办法是直接绕开页面和UI先验证接口本身。当你在浏览器、小程序或App里发现一个表现异常时可以先打开开发者工具里的Network面板找到对应的请求然后复制其URL直接在终端里发一遍curl -i -X GET \ -H Content-Type: application/json \ http://127.0.0.1:8080/api/order/123如果返回的数据和预期一致那问题大概率出在前端渲染、参数组装或交互逻辑上如果返回数据本身就是错的那问题就向后端方向走。这种办法看起来很简单但在实际团队协作中它能让责任边界立刻清晰起来。2.2 快速定性清单我建议每个项目都维护一套简单的“Bug快速定性表”不需要多复杂但至少要能回答下面这几个问题排查视角核心问题常用工具前端交互页面是否真的把参数传给了接口浏览器DevTools、Network面板、Vue/React DevTools前端渲染数据到了页面之后渲染逻辑是否正确控制台、断点、组件状态检查接口层接口收到的请求是否符合预期curl、Postman、网关访问日志后端逻辑接口处理逻辑在什么条件下会出错后端日志、慢查询日志、断点环境差异是否只有某类环境、设备、版本才会触发环境变量对比、容器镜像对比、设备真机依赖/构建依赖版本或构建产物是否和源码一致npm ls、pipdeptree、构建记录这个表的价值在于还没开始修复时你就可以先确定“不要在哪里浪费时间”。2.3 定性至少要能跨过三堵墙第一堵墙是“开发环境 vs 测试环境”。一个Bug如果只在特定环境出现第一反应不应该是改代码而是对比两边的配置、数据库、依赖版本和部署方式。很多时候环境变量差了一个前缀整个逻辑都会绕路。第二堵墙是“浏览器/终端 vs 服务端”。移动端出现屏幕滑动异常、页面闪退这类问题不少出现在WebView兼容性或前端资源版本不一致上后端日志往往没有直接信号。需要先用真机复现再决定往哪个方向查。第三堵墙是“业务代码 vs 模型/算法逻辑”。AI时代的Bug更特殊因为模型输出本身带有不确定性很多时候不是异常而是“结果不对”。这时候你很难用普通Bug的报错栈来定位问题。3. 从“气人”到“可排查”先复现再谈修复3.1 没有复现路径的Bug只能“观察”有一个共识不能复现的Bug不建议直接改代码。因为你看不到根因改完大概率是撞运气。很多开发者一拿到Bug就急着去改逻辑结果改了几轮最后发现真正的问题是测试数据写错了。复现不是为了走流程而是要找到一条可重复走到错误点的路径。如果你完全不知道怎么复现建议先做三件事向Bug提出者要完整的操作步骤精确到点击哪个按钮、输入什么内容要测试数据包括账号、文件、截图、表单内容索要环境信息包括系统版本、App版本、浏览器版本、网络环境。很多“气人Bug”其实不是技术难度高而是提出者只丢给你一句话“你打开页面看看不对。”这不算有效的Bug描述后面第七章会专门讲怎么写Bug单。3.2 写一个可运行的最小复现脚本当问题涉及后端逻辑、工具类方法或算法时“最小复现脚本”是非常有效的武器。不要直接在庞大的工程里断点运行先试着把问题从业务代码里剥离出来写成一段可以本地独立跑的小代码。比如你怀疑某个列表处理函数对异常数据类型处理有问题可以把函数单独抽出来执行# reproduce_bug.py import time def process_items(items): result [] for i, item in enumerate(items): time.sleep(0.01) if i 3: # 这里故意构造一个跨类型加法用于观察异常 result.append(item 1) else: result.append(item) return result if __name__ __main__: data [1, 2, 3, not_a_number, 5] print(process_items(data))运行结果会直接暴露异常发生在第几个元素以及item的实际类型。不要小看这段代码真正的业务场景里“处理到第4条数据就崩”往往就是因为数据里混入了一个非预期值而不是算法本身写错了。3.3 最小复现的三条纪律最小复现有三条纪律数据最小化不要用整库数据只要能触发Bug的那几行。依赖最小化尽量不要引入框架和外部服务如果必须引入注明版本。步骤最小化从“打开系统”到“报错”步骤越少越好。当你把问题压缩到这个程度Bug通常已经暴露了你能够照见的边界条件。4. Bug的生命周期状态流转和负责人的变化4.1 生命周期状态“Bug的生命周期”不只是流程还是一种工程习惯。一个Bug如果长期停留在“打开”状态就不只是技术问题更是管理问题。通常一个Bug会经历这么几个状态状态意义负责人新建提出者提交了Bug描述提出者待确认开发确认是否能复现、是否接受为缺陷开发修复中开发正在定位和修改开发待验证开发修复完成等待测试或提出者回归测试/提出者回归通过验证通过在版本中关闭测试/提出者重新打开回归不通过或再次出现测试/提出者这张表看似平淡但它回答了一个关键问题每一个时刻Bug都应该有一个明确的负责人。4.2 谁该推进状态流转现实中经常出现一种情况开发改完了Bug直接在聊天里说“改好了”然后测试一直没空验证三天后问起来开发又说“我不知道啊我不是说了改好了吗”。这种沟通低效的根源就是状态没有同步。不管团队用的是Jira、禅道、GitHub Issues还是简单的在线表格都至少要有一个人负责跟踪状态。团队里如果出现“Bug观察员”这种角色往往说明真正的问题不是Bug太多而是Bug信息流没有自动化大家只能靠人肉观察。正确的方式是提出者负责说清楚“我要什么”开发负责把Bug从“待确认”推到“待验证”测试或提出者负责回归回归通过后才能关闭。每一环不交接状态就不迁移。5. 最容易把人气死的四类Bug与排查方向5.1 依赖与原生模块无法加载native binding这类问题在很多前端和后端项目里error: cannot find native binding这类报错很容易让人一头雾水。它常常出现在升级依赖、切换Node版本、重新安装包之后。表面信息是“找不到原生模块”但背后通常有三种可能依赖安装过程中的可选依赖没有被正确安装Node或Python版本和本机编译的原生模块不匹配构建缓存残留了旧架构的二进制文件。常规排查命令如下# 查看当前依赖树确认是否包含未被安装的可选依赖 npm ls # 清理缓存和 node_modules 后重新安装 npm cache verify rm -rf node_modules package-lock.json npm install如果是Python项目也可以用类似思路pip list | grep 相关依赖 pipdeptree | grep 相关依赖注意重新安装依赖是改动环境的行为最好先在测试环境或本地分支验证不要直接在生产服务器上执行。除了命令本身更重要的教训是依赖相关Bug第一时间要对比的不是源码而是依赖锁文件和构建环境。5.2 内存越界与栈缓冲区溢出这一类Bug常见于C/C、嵌入式系统或系统级组件中。它的特点非常强烈不是每次都会崩但崩的时候往往是整个进程退出没有优雅的报错信息。比如嵌入式开发里如果你配置了DMA通道但缓冲区地址对齐方式、传输长度、中断优先级设置不当就可能出现数据错乱或栈溢出。这不是“改一行代码就能复现”的问题它和内存布局密切相关。排查方法是先复现记录崩溃时的调用栈用工具检查缓冲区边界比如ASan、Valgrind检查是否存在数组越界、字符串没有结束符、拷贝长度超过目标缓冲区等常见问题如果是修复脚本不要直接在线上执行先确认脚本内容在测试环境跑通并备份原配置。看到网上流传类似“检测到基于堆栈的缓冲区溢出修复.bat”这种脚本时不要盲目运行。任何涉及系统设置、注册表、文件替换的操作都要先看脚本内容再做隔离验证。5.3 基础设施状态Bug以Cinder卷分离失败为例在OpenStack等云平台环境中有一种Bug让运维和研发都头疼资源状态和期望状态不一致。比如虚机已经删除但绑定的卷一直处于分离失败状态。这时候不是代码报错而是云平台的资源状态机卡住了。排查这类问题首先要看的是资源的实际状态openstack server show server_id openstack volume show volume_id然后重点确认卷当前是否还被某个虚机引用是否有正在运行的迁移或快照任务控制节点和存储节点的日志是否执行到某一步中断数据库里记录的状态和真实后端存储状态是否一致。这类Bug不能靠重启解决关键在于状态修复。它提醒我们基础设施越复杂越需要在状态管理层多做幂等处理否则任何一个中断都可能留下“僵尸状态”。5.4 模型推理中的非确定性Bug长对话重复、chunk_size异常最近很多读者提到两类现象一类是LLM对话一长就开始出现重复回答另一类是某些推理框架调整了chunk_size后推理速度或内存表现异常。先说一个基本判断LLM的长对话重复并不总是模型“笨”更多时候是上下文工程和采样策略的问题。当对话历史太长超过模型的有效上下文设计范围后模型可能会丢失对前文的注意力导致生成内容开始“兜圈子”。排查思路可以从这几条入手检查历史消息是否被截断检查temperature等采样参数是否过低导致输出陷入局部循环检查生成后的后处理逻辑是否做过重复连续性检测观察是否是某个特定长度之后才开始重复如果是调节上下文窗口或分段策略。对于chunk_size这类推理框架参数遇到异常时不要只看参数本身。可以先看日志确认异常发生阶段是prefill还是decode再对比不同参数下的显存占用和耗时。如果确认是版本相关的问题优先更新到稳定版本并在测试环境用相同参数复现。这类Bug的难点在于“非确定性”同一段输入每次输出可能不同。所以修复后尤其需要反复回归而不是跑通一次就算结束。如果想在前端自动复现和验证这类交互问题也可以借助Playwright这类自动化工具录制用户流程再把步骤固化成回归用例npx playwright test tests/bug-repro.spec.ts6. 排查方法论让Bug“交底”6.1 用系统化采集替代灵感排查Bug最怕的是“灵感式排障”。一会儿改个配置一会儿清个缓存一会儿重启一下服务运气好就解决了但并没有真正搞清原因。更稳定的办法是采集完整证据链。拿到一个Bug时先确认下面这些信息# 采集应用运行日志不遗漏标准输出和错误输出 python -u main.py 21 | tee run.log # 查看关键服务是否在监听 ss -lntp | grep 8080 # 查看进程和资源占用 ps aux | grep java这段命令的作用是把系统表现、进程状态、日志信息一次性留底。这类信息不需要每一条都看懂但它是后续分析的基础。6.2 二分法缩小范围如果一个问题涉及到几十个文件的变更不要从头到尾读代码。更高效的方式是“二分法”。用git bisect可以快速定位是哪个提交引入了回归git bisect start git bisect bad # 当前提交是坏的 git bisect good commit_id # 已知某个旧提交是好的 git bisect run pytest -m regression它会自动选择一个中间提交执行回归命令然后根据结果继续二分。最终会告诉你“第一次让测试失败的提交”是哪一次。这个命令能极大压缩排查时间但它依赖两个前提第一你有稳定的复现脚本第二测试用例能自动返回通过或失败。6.3 让“偶现”变成“必现”很多气人的Bug都是偶现的。偶现不代表没有规律只是触发条件没有被发现。处理偶现问题时可以先考虑下面几个变量并发量是不是同时请求多个接口就会出问题数据量数据超过多少行才出问题操作速度用户点得很快才会出问题慢一点就正常缓存时机第一次访问正常第二次访问异常后端状态服务刚启动时正常运行一段时间后异常。给这些变量加上开关逐个打开和关闭通常能找到一个组合让问题从“偶尔出现”变成“必现”。6.4 日志记录的正确姿势如果你怀疑是后端某个函数执行异常但日志又不够细可以在代码中临时加入更详细的上下文日志。注意生产环境加日志要谨慎尽量使用现有日志框架并控制级别不要打印敏感信息。import logging logging.basicConfig( filenameapp.log, levellogging.DEBUG, format%(asctime)s %(levelname)s %(name)s %(message)s ) logger logging.getLogger(__name__) def handle(item): logger.debug(enter handle, item%r, item) # ... 原有逻辑调试完成后记得移除或降低日志级别避免给生产环境带来额外IO压力。7. 写一份让人愿意马上处理的Bug单7.1 标题怎么写才有画面感有一种Bug描述是这样的“来bug了图一的横线你看一下。”这种描述的问题在于不告诉我是什么平台、什么操作、什么数据只说“图一有根横线”。看图的人可能要看半天才能确认“横线”到底指什么。好的Bug标题应该像一条索引让人不看正文也能知道问题范围差标题登录有问题好标题iOS 16.4系统下输入正确密码后点击登录按钮无反应控制台无请求发出标题里至少要包含三要素设备/环境、操作动作、观察到的异常结果。7.2 Bug单字段清单一份可以快速流转的Bug单建议包含这些字段字段说明示例标题一句话描述问题订单详情页在苹果手机上滑动时偶发闪退环境系统、浏览器、App版本、分支Chrome 117 / iOS 16.4 / Android 12前置条件操作前需要准备什么需要登录一个VIP账号复现步骤精确到每一步操作1. 打开订单列表 2. 点击第二个订单 3. 向下滑动预期结果应该看到什么页面正常展示并可以滚动实际结果实际看到了什么页面闪退回首页日志/截图辅助证据附控制台报错截图或日志文件填完这张表大多数人已经能自行复现问题根本不需要在群里来回追问。7.3 附件的正确贴法截图是有价值的但截图最好附上时间、位置和必要的文字说明。不要只发一张满屏红色告警的图也不要只发一行被压缩成马赛克的日志。如果日志太长不要直接粘贴进聊天框保存成文件或放在日志平台然后在Bug单里填入日志ID。如果涉及敏感信息先做脱敏处理。8. 团队Bug制度与回归防线8.1 状态机要有人促流转很多团队把Bug工具当成记录本只记录不流转这是最大的浪费。Bug工具应该是工作流引擎。提出者提交Bug之后开发需要在约定时间内把状态改成“修复中”或“待确认”。如果连“是否能复现”都无法判断应该在状态字段中写明原因而不是让Bug躺在“新建”里。团队里每个人都可以是“Bug观察员”但更推荐的做法是把状态流转交给工具和流程让人只处理真正需要人判断的事。8.2 回归不要轻易说“改好了”修复Bug之后最容易翻车的场景是开发只验证了“问题路径”没有验证“相关路径”。比如你修复了一个订单支付状态不更新的问题导致支付成功的订单也能被重复支付。如果你只测了“支付失败后不更新状态”没测“支付成功后订单状态正常”那就等于引入了新Bug。建议在修复完成后至少回归三类场景主路径测试验证原问题不再出现边界路径测试用和问题相邻的边界数据再跑一遍受影响模块测试检查涉及同一函数、同一表、同一组件附近的功能。8.3 修复要区分“绕过”还是“根修”有些Bug修复起来很简单比如给参数加个默认值或者前端改成空值兜底。但你要清楚这是“绕过”还是“根修”绕过只解决当前表现根修要解决产生这个表现的根因。比如前端调用接口时后端返回了null导致页面报错。如果你只是在前端写一个if (res.data null) return []这是绕过如果后端能正确返回空数组并且查明为什么会出现null这是根修。成熟的团队在排期时通常会把“绕过应急”和“根修排期”分开记录避免绕过长期占用生产环境。9. 用工程习惯替代“运气”9.1 日志是可观测性的第一入口面对Bug第一反应不该是“改代码”而是“看日志”。但日志不是越多越好。瞎打日志会造成两倍噪音。好的日志至少要包含时间戳请求ID或业务ID函数/模块名关键入参结果或异常信息。有了这些排查者才能在数千行日志中快速拼出一次业务调用的完整路径。否则你只能靠“碰运气”。9.2 错误信息要抄写要有错误码很多人在聊天里复述Bug时会把错误信息记成“它报了一个错好像是什么绑定失败然后就不能用了”。这种表达丢失了最有价值的信息。正确做法是完整抄写第一行错误信息、异常类型、以及关键的堆栈前几行。如果系统支持错误码把错误码一并写进Bug单。错误码比自然语言可靠得多因为它能精确对应到代码路径。9.3 用安全兜底给Bug留退路没有Bug的软件是不存在的。所以工程习惯的另一半是怎么在不完美的情况下减少损失。数据库操作之前必须备份和回滚配置修改之前必须记录旧值生产环境执行命令之前先评估权限和影响范围重要逻辑加上开关和熔断防止Bug被放大。这套习惯不能杜绝Bug但能让Bug从“事故”变成“事件”。只要还有回退空间气人程度就会大幅度下降。9.4 心态Bug不是人品题是信息题最后说回开头的那句“这Bug太气人了”。程序员基本上都见过这种文件夹或者朋友圈文案“神兽保佑代码无Bug”。这是调侃但它的隐藏含义是Bug是一个随机事件只能靠运气压制。但真正的工程世界里Bug不是烂人品也不是随机惩罚它只是从系统行为到预期行为之间的一段信息差。你现在不知道正确答案是因为信息还没收集够。当你把日志、数据、操作路径、环境差异都摆到桌面上Bug基本已经退无可退。下次再遇到让你头皮发麻的问题不要急着骂人也不要急着改代码。先写复现步骤再拉日志再收藏本文里的排查清单。把一个气人的Bug变成一个走流程就能解决的问题这才是工程师真正的解压方式。