systematic-debugging

系统化调试

有条理地调试，不要随意修改代码。

流程

1. 复现

首先，可靠地复现问题：

• 获取触发问题的准确步骤
• 记录预期行为与实际行为
• 确认问题会稳定出现（而非偶发）
• 记录环境信息（操作系统、Node 版本、浏览器等）

如果无法复现，就无法修复。请索取更多信息。

2. 隔离

缩小问题所在的范围：

对代码库进行二分查找：

• 注释掉一半系统代码 → 问题是否仍然存在？
• 如果是，问题就在剩下的一半 → 重复操作
• 如果否，问题就在被注释掉的一半 → 重复操作

Git 二分查找：

git bisect start
git bisect bad          # current commit is broken
git bisect good <sha>   # this commit was working
# Git checks out the midpoint — test it
git bisect good         # or git bisect bad
# Repeat until it finds the first bad commit
git bisect reset        # when done

按层隔离：

• 问题出在前端还是后端？（检查网络面板）
• 问题出在数据库吗？（直接查询）
• 问题出在 API 吗？（使用 curl 请求端点）
• 问题出在组件吗？（单独渲染该组件）

3. 提出假设

提出具体且可验证的假设：

• “问题是由 X 导致的，因为 Y”
• 不要说“数据有问题”
• 好的例子：“userId 为 null，因为这个路由没有执行身份验证中间件”

4. 验证假设

编写尽可能小的测试，以验证或证伪假设：

• 在疑似位置添加 console.log 或断点
• 检查疑似变量的值
• 如果假设不成立，根据新信息回到第 3 步
• 如果假设成立，就找到问题了

5. 修复并验证

• 应用最小化修复
• 验证原先的复现步骤不再触发问题
• 检查是否引入回归问题——修复是否破坏了其他功能？
• 编写一个能够捕获此问题的测试

调试工具

场景	工具
“之前还能正常工作”	git bisect
“我不知道这段代码在哪里运行”	在可疑函数的入口和出口添加日志
“数据看起来不对”	检查每个转换步骤中的数据
“只在生产环境中失败”	比较环境变量、检查日志，并尝试在本地使用生产数据复现
“问题偶尔出现”	检查竞态条件、时序问题或未初始化的状态
“错误消息毫无用处”	在代码库中搜索抛出该错误的位置

常见问题模式

• 差一错误：数组索引、分页、日期范围
• Null/undefined：缺少可选链、状态未初始化
• 竞态条件：异步操作的完成顺序与预期不符
• 过时闭包：React useEffect/useCallback 捕获了旧值
• 类型强制转换：== 与 ===，字符串与数字的比较
• 缺少 await：忘记在异步函数上使用 await
• 环境不一致：由于环境变量或版本不同，代码在本地可运行，但在 CI/生产环境中失败

规则

• 绝不猜测——始终用证据验证
• 修复根本原因，而不是表面症状
• 如果 15 分钟没有进展，就停下来重新隔离问题
• 记录尝试过的方法，避免重复无效的做法