name: debugging-systematic description: 应用系统性根本原因分析和调试方法来诊断和修复bug、测试失败和意外行为。在遇到生产问题、调查测试失败、诊断性能问题、通过调用栈追踪错误源、分析日志和堆栈跟踪、复现不一致的bug、调试竞态条件、调查内存泄漏或应用科学方法解决问题之前提出修复方案时使用。
系统性调试 - 根本原因分析框架
何时使用此技能
- 遇到bug或意外应用行为时
- 调查测试失败和脆弱测试时
- 诊断生产问题和中断时
- 通过复杂调用栈追踪错误源时
- 分析日志、堆栈跟踪和错误消息时
- 复现间歇性或难以复现的bug时
- 调试竞态条件和时序问题时
- 调查内存泄漏或性能退化时
- 提出修复方案前进行根本原因分析时
- 调试服务间集成问题时
- 调查数据损坏或不一致时
- 应用科学方法进行系统性解决问题时
何时使用此技能
- 遇到bug、测试失败、意外行为或生产问题时 - 在提出修复方案之前。
- 处理相关任务或功能时
- 需要此专业知识的开发过程中
使用时机：遇到bug、测试失败、意外行为或生产问题时 - 在提出修复方案之前。
核心哲学
永远不要猜测修复方案。 先理解根本原因。
❌ 错误："让我们在这里加个超时试试"
✅ 正确："超时发生是因为X。这是证据：[证据]"
四阶段框架
阶段1：根本原因调查
目标：准确理解发生了什么及原因
1. 可靠复现问题
- 最小复现案例
- 一致的复现步骤
- 记录环境/条件
2. 收集证据
- 错误消息（完整堆栈跟踪）
- 日志（带时间戳和上下文）
- 失败点状态
- 触发问题的输入数据
3. 形成假设
- 基于证据，而非猜测
- 具体且可测试
- 包括失败机制
示例：
Bug：用户认证间歇性失败
调查：
1. 复现：约每第10次登录尝试失败
2. 证据：
- 错误："无效令牌签名"
- 日志显示令牌创建于14:32:15，验证于14:32:17
- 服务器日志显示认证服务器和API服务器间时间漂移
3. 假设：时钟偏差导致令牌验证失败
- 认证服务器：14:32:15
- API服务器：14:32:10（落后5秒）
- 令牌由于nbf（不早于）声明而"尚未有效"
阶段2：模式分析
目标：理解这是孤立问题还是系统性问题
1. 检查类似问题
- 其他位置有相同错误吗？
- 相关代码中有相同模式吗？
- 错误日志中重复出现吗？
2. 确定范围
- 单个函数还是整个子系统？
- 单个用户还是所有用户？
- 单个环境还是所有环境？
3. 查找共同因素
- 时间（时间点、持续时间）？
- 数据特征？
- 执行路径？
阶段3：假设测试
目标：通过实验证明理解
1. 设计证明/反驳假设的测试
2. 如需，添加检测
3. 系统运行实验
4. 记录结果
示例测试：
// 假设：时钟偏差导致令牌失败
// 测试1：人工设置服务器时钟同步
// 结果：100次尝试无失败 ✓
// 测试2：将令牌nbf容忍度增加到10秒
// 结果：100次尝试无失败 ✓
// 测试3：记录失败发生时的精确时间差
// 结果：所有失败显示4-6秒时钟差异 ✓
// 结论：假设确认
阶段4：实施
目标：修复根本原因，而非症状
1. 处理根本原因
- 修复底层问题
- 不仅仅是表面症状
2. 添加安全措施
- 验证
- 错误处理
- 监控
3. 验证修复
- 复现器不再触发问题
- 处理相关边缘案例
- 未引入新问题
调试技巧
1. 二分查找调试
针对"在正常工作状态和现在之间某处坏了"：
# Git二分查找示例
git bisect start
git bisect bad HEAD # 当前损坏状态
git bisect good v1.2.0 # 最后已知工作状态
# Git将检出提交进行测试
# 测试每个：git bisect good / git bisect bad
# 自动找到破坏提交
2. 差异调试
比较工作与损坏环境：
工作环境：
- Node 18.16.0
- 依赖A v2.1.0
- 功能标志X：关闭
损坏环境：
- Node 18.17.0 ← 可疑
- 依赖A v2.1.0
- 功能标志X：关闭
测试：更改Node版本 → Bug消失 → 根本原因找到
3. 检测
添加战略日志：
// 信息不足
function processUser(user) {
const result = complexOperation(user);
return result; // 有时失败，为什么？
}
// 丰富检测
function processUser(user) {
logger.debug('processUser开始', {
userId: user.id,
userState: user.state,
timestamp: Date.now()
});
const result = complexOperation(user);
logger.debug('processUser完成', {
userId: user.id,
resultStatus: result.status,
duration: Date.now() - start
});
return result;
}
4. 橡皮鸭调试
大声解释问题：
"当用户点击登录时，我们：
1. 哈希他们的密码 ← 等等，我们用的是相同的盐吗？
2. 与数据库比较
3. ... 哦。我们上周改了盐算法。"
5. 时间旅行调试
使用调试器向后步进：
现代调试器（rr、WinDbg、Chrome DevTools）可以：
- 记录执行
- 重放向后
- 找到状态变为无效的确切时刻
常见根本原因
1. 竞态条件
// 症状：间歇性失败，在调试器中工作
// 根本原因：异步操作以错误顺序完成
// 错误
let userData = null;
fetchUser().then(data => userData = data); // 异步
sendEmail(userData.email); // 在fetch完成前运行！ ❌
// 修复
const userData = await fetchUser();
sendEmail(userData.email); // ✓
2. 共享可变状态
// 症状：测试单独通过，一起失败
// 根本原因：测试共享状态
// 错误 - 共享状态
const cache = {}; // 全局
test('test1', () => { cache.foo = 'bar'; });
test('test2', () => { expect(cache.foo).toBeUndefined(); }); // 失败！ ❌
// 修复 - 隔离状态
test('test1', () => {
const cache = {};
cache.foo = 'bar';
});
test('test2', () => {
const cache = {};
expect(cache.foo).toBeUndefined();
}); // ✓
3. 错误假设
// 症状：某些输入时崩溃
// 根本原因：假设数据总是存在
// 错误 - 假设邮箱存在
function sendWelcome(user) {
sendEmail(user.email); // 如果邮箱为null则崩溃 ❌
}
// 修复 - 验证假设
function sendWelcome(user) {
if (!user?.email) {
logger.warn('无法发送欢迎邮件', { userId: user.id });
return;
}
sendEmail(user.email); // ✓
}
4. 差一错误
// 症状：数组索引错误，缺失最后一项
// 根本原因：循环边界错误
// 错误
for (let i = 0; i < array.length - 1; i++) { // 遗漏最后一个元素 ❌
process(array[i]);
}
// 修复
for (let i = 0; i < array.length; i++) { // ✓
process(array[i]);
}
// 或更好：array.forEach(process);
5. 时区问题
// 症状：对某些用户日期计算错误
// 根本原因：未处理时区
// 错误
const deadline = new Date('2024-01-01'); // 哪个时区的午夜？ ❌
// 修复
const deadline = new Date('2024-01-01T00:00:00Z'); // 显式UTC
// 或使用库：dayjs.utc('2024-01-01')
调试检查清单
□ 你能可靠复现问题吗？
□ 你有完整的错误消息和堆栈跟踪吗？
□ 你知道触发问题的确切输入吗？
□ 你检查了最近的变化（git log）吗？
□ 你用日志验证了你的假设吗？
□ 你隔离了失败组件吗？
□ 你理解它为什么失败（不仅仅是哪里失败）吗？
□ 你测试了修复针对复现器吗？
□ 你添加了测试以防止回归吗？
□ 你检查了其他地方的类似问题吗？
何时求助
求助时机：
- 系统性调查2+小时后卡住时
- 问题涉及不熟悉子系统时
- 复现器不一致时
但首先准备：
## 问题描述
[什么坏了]
## 复现步骤
1. [精确步骤]
2. [预期与实际]
## 调查至今
- [我尝试了什么]
- [我排除了什么]
- [当前假设]
## 证据
- [日志、错误、截图]
- [最小代码复现器]
## 环境
- 操作系统、版本、配置
避免的反模式
❌ 散弹枪调试
"让我试试改这个...和这个...和这个..."
→ 你不知道什么真正修复了它
❌ printf调试过载
无计划地到处加打印语句
→ 噪音掩盖信号
❌ 假设不是你的代码
"肯定是框架bug"
→ 95%的时间，是你的代码
❌ 修复症状，而非根本原因
Bug：大文件时崩溃
错误修复：加try/catch隐藏错误 ❌
正确修复：实现流处理以处理大文件 ✓
高级技巧
核心转储分析
# 进程崩溃时
gdb program core
(gdb) bt # 回溯
(gdb) info locals # 局部变量
(gdb) frame 3 # 检查帧
网络调试
# 捕获流量
tcpdump -i any -w capture.pcap
# 用Wireshark分析
wireshark capture.pcap
# 或使用Charles Proxy、mitmproxy
性能分析
// Node.js
node --prof app.js
node --prof-process isolate-*.log
// Chrome DevTools
// 性能标签 → 记录 → 分析火焰图
资源
记住：调试是一项技能。你的方法越系统，你找到根本原因越快，修复中引入的bug越少。