debug

name	debug
description	Systematic debugging methods, log analysis, and performance diagnostics. Use when debugging issues, analyzing errors, or troubleshooting incidents.
allowed-tools	Read, Write, Edit, Bash, Grep, Glob
parent	quality

调试技能

本技能提供系统化的调试方法和技巧。

触发条件

• 调试代码问题
• 分析错误日志
• 调查性能问题
• 排查生产事故
• 修复 Bug

调试原则

黄金法则

1. 复现问题 - 先能稳定复现，再开始调试
2. 最小化 - 找到最小可复现用例
3. 二分法 - 缩小问题范围
4. 假设验证 - 提出假设，验证假设
5. 记录过程 - 记录尝试过的方法

调试流程

问题描述 → 复现问题 → 缩小范围 → 定位原因 → 修复验证 → 记录总结

问题描述模板

记录时包含以下要素:

要素	内容
问题描述	简要描述问题现象
预期 vs 实际	期望行为与实际行为的差异
复现步骤	可稳定复现的最小步骤
环境信息	OS、语言版本、依赖版本
错误信息	完整的错误堆栈或日志
已尝试方案	每个方案及其结果

日志调试

有效的日志输出

// ❌ 无用的日志
console.log("here");
console.log(data);

// ✅ 有信息量的日志
console.log("[UserService.createUser] 开始创建用户:", {
  email: user.email,
  timestamp: new Date().toISOString(),
});

console.log("[UserService.createUser] 数据库插入成功:", {
  userId: result.id,
  duration: Date.now() - startTime,
});

console.error("[UserService.createUser] 创建失败:", {
  error: error.message,
  stack: error.stack,
  input: { email: user.email },
});

# ❌ 无用的日志
print("here")
print(data)

# ✅ 有信息量的日志
import logging
logger = logging.getLogger(__name__)

logger.info(f"[create_user] 开始创建用户: email={email}")
logger.info(f"[create_user] 创建成功: user_id={user.id}, duration={duration}ms")
logger.error(f"[create_user] 创建失败: error={str(e)}", exc_info=True)

日志级别使用

级别	用途	示例
DEBUG	详细调试信息	函数参数、中间状态
INFO	正常操作信息	用户登录、订单创建
WARN	警告但可继续	配置缺失使用默认值
ERROR	错误但可恢复	API 调用失败重试
FATAL	致命错误需退出	数据库连接失败

断点调试

VS Code 调试配置 (.vscode/launch.json)

场景	type	关键配置
Node.js	node	program, preLaunchTask, outFiles
Python	python	program: "${file}", integratedTerminal
Jest 测试	node	program: jest, args: ["--runInBand"]

条件断点

在循环中设置条件表达式 (如 item.id === 'target-id')，仅在满足条件时暂停。

网络与数据库调试

详见 network-debug.md

• 网络调试: Axios 拦截器日志、cURL 调试技巧
• 数据库调试: Prisma/SQLAlchemy 查询日志、慢查询分析 (EXPLAIN ANALYZE)

性能调试

详见 performance-debug.md

• 时间测量: performance.now() / console.time / Python timeit 装饰器
• 内存分析: Node.js process.memoryUsage() / Python tracemalloc

前端调试与常见问题

详见 frontend-debug.md

• Console 高级方法: group / table / assert / trace / count
• React DevTools: displayName / useDebugValue
• 常见 JS 陷阱: 忘记 await、闭包捕获、this 丢失

调试清单

## 调试前

- [ ] 能稳定复现问题吗？
- [ ] 最小复现用例是什么？
- [ ] 最近改动了什么？

## 调试中

- [ ] 查看错误日志和堆栈
- [ ] 添加必要的日志输出
- [ ] 使用断点逐步执行
- [ ] 检查输入数据是否正确
- [ ] 检查环境变量和配置

## 调试后

- [ ] 修复是否解决了根本原因？
- [ ] 是否需要添加测试？
- [ ] 是否需要更新文档？
- [ ] 是否有类似问题需要检查？

最佳实践

1. 先复现后调试 - 不能复现就无法确认修复
2. 二分法定位 - 缩小问题范围
3. 记录尝试 - 避免重复无效尝试
4. 查看最近改动 - git diff, git log
5. 橡皮鸭调试 - 向他人解释问题
6. 休息一下 - 换个思路
7. 搜索错误信息 - 可能他人遇到过
8. 检查假设 - 你认为正确的可能是错的
9. 简化问题 - 去除无关因素
10. 写测试固化 - 防止问题复现

记住: 调试的第一步是复现——稳定复现问题后，解决方案通常就在眼前。