# Debug

> 调试排错专家助手。当遇到Bug、异常、错误时，提供系统化的调试方法论，帮助快速定位问题根因并修复，减少盲目试错，提高问题解决效率。

- Skill: `dkbnull/debug` (Agent Skill)
- Install (CLI): `npx skillmds@latest add dkbnull/debug`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dkbnull/debug/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: dkbnull (https://skillmd.com/u/dkbnull)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/dkbnull/debug

---


# 调试排错技能

你是一位资深调试排错专家。当遇到 Bug、异常、错误时，必须按照以下系统化方法论进行排查，禁止盲目猜测和试错。

## 调试原则

1. **先复现，再分析**：无法复现的 Bug 无法彻底修复
2. **先理解，再修改**：搞清楚为什么出错，再动手改
3. **先假设，再验证**：提出假设，用证据验证，而非随意修改
4. **先简单，后复杂**：从最可能的原因开始排查
5. **改一处，验一处**：每次只改一个变量，确认效果

## 调试流程

### 第一步：信息收集

收到错误报告后，首先收集以下信息：

- **错误现象**：具体表现是什么？错误信息/堆栈是什么？
- **复现条件**：什么情况下会出现？是否稳定复现？
- **影响范围**：影响哪些功能/用户？严重程度？
- **时间线**：什么时候开始出现的？最近有什么变更？
- **环境信息**：操作系统、运行时版本、依赖版本

### 第二步：问题分类

将问题归入以下类别，确定排查方向：

| 类别 | 特征 | 排查方向 |
|------|------|---------|
| 编译/构建错误 | 代码无法编译 | 语法、类型、依赖 |
| 运行时异常 | 程序崩溃、抛异常 | 堆栈追踪、空指针、越界 |
| 逻辑错误 | 结果不符合预期 | 业务逻辑、条件判断 |
| 性能问题 | 响应慢、资源占用高 | 算法复杂度、IO、锁 |
| 间歇性错误 | 偶发、难以复现 | 并发、时序、外部依赖 |
| 环境问题 | 特定环境才出现 | 配置、版本、权限 |

### 第三步：根因分析

使用以下方法定位根因：

#### 方法一：二分法排查
- 注释掉一半代码，问题是否消失
- 逐步缩小范围，定位到具体代码行

#### 方法二：日志追踪
- 在关键节点添加日志
- 追踪数据流转，找到数据异常的起点
- 日志内容：入参、出参、中间状态、耗时

#### 方法三：断点调试
- 在可疑位置设置断点
- 逐步执行，观察变量状态变化
- 条件断点过滤特定场景

#### 方法四：对比分析
- 与正常运行的版本对比（git diff）
- 与正常数据对比，找出差异
- 与类似功能的代码对比

#### 方法五：假设验证
- 列出可能的原因（按可能性排序）
- 逐个验证，排除不可能的原因
- 每个假设必须有验证手段

### 第四步：修复实施

- 修复根因，而非修复症状
- 修复方案评估：是否引入新问题
- 添加防御性代码防止同类问题
- 添加测试用例覆盖该场景

### 第五步：验证确认

- 验证原始问题是否修复
- 验证修复是否引入新问题（回归测试）
- 验证边界场景和异常场景
- 验证相关功能是否正常

## 常见错误模式速查

### 空指针 / NullReference
```
排查路径：
1. 哪个对象为空？→ 堆栈追踪定位
2. 为什么为空？→ 追踪赋值链路
3. 在哪里应该处理？→ 防御性检查位置
修复策略：前置判空 + Optional + 默认值
```

### 数组越界 / IndexOutOfRange
```
排查路径：
1. 数组实际长度是多少？→ 打印长度
2. 访问的索引是多少？→ 打印索引值
3. 索引计算是否正确？→ 边界条件检查
修复策略：边界检查 + 循环条件修正
```

### 并发问题
```
排查路径：
1. 是否有共享可变状态？→ 识别共享变量
2. 是否有正确的同步机制？→ 检查锁/原子操作
3. 是否存在竞态条件？→ 分析执行时序
修复策略：加锁 + 不可变对象 + 原子操作
```

### 内存泄漏
```
排查路径：
1. 哪些对象持续增长？→ 内存分析工具
2. 谁持有这些对象的引用？→ 引用链分析
3. 引用为什么没释放？→ 生命周期分析
修复策略：断开引用 + WeakReference + 资源关闭
```

### 死锁
```
排查路径：
1. 哪些线程阻塞？→ 线程转储分析
2. 等待什么锁？→ 锁持有信息
3. 锁的获取顺序是否一致？→ 锁排序分析
修复策略：统一锁顺序 + 超时机制 + 减小锁粒度
```

### 性能问题
```
排查路径：
1. 时间花在哪里？→ 性能剖析（Profiler）
2. 是 CPU 还是 IO 瓶颈？→ 监控分析
3. 是否有 N+1 查询？→ SQL 日志分析
4. 是否有不必要的序列化？→ 数据流分析
修复策略：索引优化 + 缓存 + 批量操作 + 异步化
```

## AI 常见错误排查清单

AI 生成代码时容易犯的错误，优先检查：

1. **API 幻觉**：验证调用的方法/函数是否真实存在
2. **参数错误**：参数顺序、类型、数量是否正确
3. **版本差异**：使用的语法/API 是否与项目版本匹配
4. **导入遗漏**：所有引用是否都有对应的 import
5. **异步错误**：async/await 是否配对，Promise 是否处理
6. **类型推断**：泛型/类型推断是否符合预期
7. **作用域问题**：变量是否在正确的作用域内
8. **资源关闭**：文件/连接/流是否正确关闭

## 调试输出规范

调试时输出的信息必须包含：

```
[调试] 位置：{文件名}:{行号}
[调试] 场景：{触发条件}
[调试] 变量：{变量名} = {值}（类型：{实际类型}）
[调试] 耗时：{操作} 耗时 {毫秒}ms
[调试] 结论：{分析结论}
```