debugger

调试器

一位高级调试专家，可帮助系统地诊断和解决代码问题。

此技能的触发条件

在以下情况下触发：

• 报告错误或 Bug
• 提到“调试这个”或“帮忙调试”
• 描述意外行为
• 询问为什么某些功能无法正常工作

调试流程

阶段 1：了解问题

1. 重现问题

   • 重现问题的具体步骤是什么？
   • 预期行为是什么？
   • 实际行为是什么？
   • 出现了哪些错误消息？

2. 收集上下文

   # Check recent changes
   git log --oneline -10
   
   # Check error logs
   tail -f logs/error.log
   
   # Check environment
   env | grep -i debug
   

阶段 2：隔离问题

1. 定位错误来源

   • 分析堆栈跟踪
   • 查找错误代码
   • 关联日志

2. 缩小范围

   • 二分查找（注释掉一半代码）
   • 精简复现案例
   • 确定受影响的组件

阶段 3：分析根本原因

常见错误类别

类别	症状	调查步骤
Null/Undefined	“无法读取 undefined 的 X”	追踪变量的来源
类型错误	“X 不是一个函数”	检查实际类型与预期类型
异步问题	竞态条件、时序问题	检查 Promise 处理、async/await
状态问题	数据过时、状态错误	追踪状态变更
网络	超时、连接被拒绝	检查端点、CORS、身份验证
环境	本地运行正常，生产环境异常	比较环境变量和版本
内存	泄漏、内存不足（OOM）	分析内存使用情况
并发	死锁、竞态条件	检查锁和共享状态

阶段 4：提出假设

针对每个可能的原因：

1. 提出假设
2. 创建测试以验证假设
3. 运行测试
4. 确认或否定假设

阶段 5：修复并验证

1. 实施修复
2. 必要时添加日志
3. 测试修复
4. 添加回归测试

调试命令

通用调试

# Find recently modified files
find . -type f -mtime -1 -name "*.js" -o -name "*.ts" -o -name "*.py"

# Grep for error patterns
grep -r "ERROR\|FATAL\|Exception" logs/

# Search for suspicious patterns
grep -r "TODO\|FIXME\|XXX" src/

# Check for console.log left in code
grep -r "console\.log\|debugger" src/

特定语言调试

JavaScript/TypeScript：

# Run with debug output
NODE_DEBUG=* node app.js

# Check syntax
node -c file.js

# Run tests in debug mode
npm test -- --inspect-brk

Python：

# Run with pdb
python -m pdb script.py

# Check syntax
python -m py_compile script.py

# Verbose mode
python -v script.py

Go：

# Race detection
go run -race main.go

# Debug build
go build -gcflags="-N -l"

# Profile
go test -cpuprofile=cpu.prof

常见调试模式

模式 1：分而治之

# When you don't know where the bug is:
def process():
    step1()
    step2()
    step3()
    step4()

# Comment out half:
def process():
    step1()
    # step2()
    # step3()
    # step4()

# If bug disappears, uncomment half of commented:
def process():
    step1()
    step2()
    # step3()
    # step4()

# Continue until you isolate the bug

模式 2：添加日志

// Before (mysterious failure):
async function getUser(id: string) {
  const user = await db.find(id);
  return transform(user);
}

// After (with logging):
async function getUser(id: string) {
  console.log('[DEBUG] getUser called with id:', id);
  const user = await db.find(id);
  console.log('[DEBUG] db.find returned:', user);
  const result = transform(user);
  console.log('[DEBUG] transform returned:', result);
  return result;
}

模式 3：最小化复现

// Complex code with bug:
function processBatch(items, options) {
  // 100 lines of complex logic
}

// Create minimal reproduction:
function processBatch(items, options) {
  console.log('Items:', items.length);
  console.log('Options:', options);
  // Test with minimal data
  return processBatch([items[0]], options);
}

错误消息分析

常见错误消息

错误	可能原因	解决方案
Cannot read property 'X' of undefined	在 null/undefined 上访问属性	添加 null 检查，使用可选链
X is not a function	类型错误、名称遮蔽	检查 typeof，验证导入
Unexpected token	语法错误	检查错误行之前的代码，验证语法
Module not found	导入路径错误	检查相对路径，确认文件存在
EADDRINUSE	端口已被占用	终止现有进程，使用其他端口
Connection refused	服务未运行	启动服务，检查端口
Timeout	请求耗时过长	增加超时时间，检查网络

调试检查清单

• 我可以稳定地重现问题
• 我已找到确切的错误位置
• 我了解根本原因
• 我已提出修复方案
• 修复不会破坏现有功能
• 我已添加测试以防止问题回归

脚本

生成调试报告：

python3 scripts/debug_report.py --name <error-message> --output debug-report.md

参考资料

• references/checklist.md - 调试检查清单
• references/patterns.md - 常见调试模式
• references/errors.md - 错误消息参考