⚡

调试专家 debugging

调试专家技能提供全面的软件错误诊断与修复能力，涵盖错误分析、日志解析、堆栈跟踪、根本原因分析和生产问题调试。适用于开发人员、测试工程师和DevOps团队进行代码调试、系统故障排查、性能优化和错误监控。关键词：软件调试、错误分析、日志解析、堆栈跟踪、根本原因分析、生产问题排查、代码修复、错误模式识别、系统故障诊断、性能调试。

测试 0 次安装 0 次浏览 更新于 2/28/2026

name: debugging description: 全面的错误调试专家，用于处理错误、测试失败、日志分析和系统问题。当遇到问题、分析错误日志、调查系统异常、调试生产问题、分析堆栈跟踪或识别根本原因时使用。结合通用调试工作流程与错误模式检测和日志分析。 author: Joseph OBrien status: unpublished updated: ‘2025-12-23’ version: 1.0.1 tag: skill type: skill

调试

此技能提供全面的调试能力，用于识别和修复错误、测试失败、意外行为和生产问题。它结合了通用调试工作流程与专门的错误分析、日志解析和模式识别。

何时使用此技能

  • 当在代码中遇到错误或异常时
  • 当测试失败且需要理解原因时
  • 当调查意外行为或错误时
  • 当分析堆栈跟踪和错误消息时
  • 当调试生产问题时
  • 当修复用户或QA报告的问题时
  • 当分析错误日志和堆栈跟踪时
  • 当调查性能问题或异常时
  • 当关联跨多个服务的错误时
  • 当识别重复出现的错误模式时
  • 当设置错误监控和警报时
  • 当进行事件的事后分析时

此技能的作用

  1. 错误分析：捕获并分析错误消息和堆栈跟踪
  2. 日志解析：使用正则表达式模式和结构化解析从日志中提取错误
  3. 堆栈跟踪分析：分析跨多种编程语言的堆栈跟踪
  4. 错误关联：识别分布式系统中错误之间的关系
  5. 模式识别：检测常见的错误模式和反模式
  6. 复现：识别复现问题的步骤
  7. 隔离：定位代码中的确切故障点
  8. 根本原因分析：从症状回溯以识别根本原因
  9. 最小化修复：实施能解决问题的最小更改
  10. 验证：确认解决方案有效且不会引入新问题
  11. 监控设置：创建用于错误检测的查询和警报

辅助脚本

此技能在 scripts/ 中包含Python辅助脚本：

  • parse_logs.py：解析日志文件并提取错误、异常和堆栈跟踪。输出包含错误分析和模式检测的JSON。

    python scripts/parse_logs.py /var/log/app.log

使用方法

调试错误

调试此错误：TypeError: Cannot read property 'x' of undefined

调查 test_user_service.js 中的测试失败原因

分析错误日志

分析 /var/log/app.log 中的错误日志并识别根本原因

调查API返回500错误的原因

模式检测

在过去24小时的这些错误日志中查找模式

关联API服务和数据库之间的错误

调试流程

1. 捕获错误信息

错误消息：

  • 阅读完整的错误消息
  • 注意错误类型（TypeError、ReferenceError等）
  • 识别错误位置（文件和行号）

堆栈跟踪：

  • 分析调用堆栈
  • 识别函数调用序列
  • 找到错误起源处

上下文：

  • 检查最近的代码更改
  • 查看相关代码文件
  • 理解执行流程

2. 错误提取（日志分析）

使用辅助脚本：

此技能包含一个用于解析日志的Python辅助脚本：

# 解析日志文件并提取错误
python scripts/parse_logs.py /var/log/app.log

手动日志解析模式：

# 从日志中提取错误
grep -i "error\|exception\|fatal\|critical" /var/log/app.log

# 提取堆栈跟踪
grep -A 20 "Exception\|Error\|Traceback" /var/log/app.log

# 提取特定错误类型
grep "TypeError\|ReferenceError\|SyntaxError" /var/log/app.log

结构化日志解析：

// 解析JSON日志
const errors = logs
  .filter(log => log.level === 'error' || log.level === 'critical')
  .map(log => ({
    timestamp: log.timestamp,
    message: log.message,
    stack: log.stack,
    context: log.context
  }));

3. 堆栈跟踪分析

常见模式：

JavaScript/Node.js：

Error: Cannot read property 'x' of undefined
    at FunctionName (file.js:123:45)
    at AnotherFunction (file.js:456:78)

Python：

Traceback (most recent call last):
  File "app.py", line 123, in function_name
    result = process(data)
  File "utils.py", line 45, in process
    return data['key']
KeyError: 'key'

Java：

java.lang.NullPointerException
    at com.example.Class.method(Class.java:123)
    at com.example.AnotherClass.call(AnotherClass.java:456)

4. 错误关联

时间线分析：

  • 按时间戳对错误进行分组
  • 识别错误峰值和模式
  • 与部署或更改相关联
  • 检查级联故障

服务关联：

  • 映射跨服务边界的错误
  • 识别上游/下游关系
  • 跟踪错误传播路径
  • 查找常见故障点

5. 模式识别

常见错误模式：

N+1查询问题：

循环中的多个数据库查询
模式：SELECT * FROM users; SELECT * FROM posts WHERE user_id = ?

内存泄漏：

内存使用量逐渐增加
模式：内存随时间增长而不释放

竞态条件：

负载下的间歇性故障
模式：仅在并发请求时发生错误

超时问题：

请求超时
模式：特定持续时间后发生错误（例如30秒）

6. 复现问题

复现步骤：

  1. 识别触发错误的确切条件
  2. 创建一个能复现问题的最小化测试用例
  3. 验证问题是否一致且可复现
  4. 清晰地记录步骤

示例：

## 复现步骤

1. 导航到 `/users/123`
2. 点击“编辑个人资料”
3. 提交表单而不填写必填字段
4. 发生错误：“Cannot read property 'validate' of undefined”

7. 隔离故障位置

代码分析：

  • 阅读错误位置周围的代码
  • 跟踪执行路径
  • 识别假设被打破的地方
  • 检查变量状态和值

调试技术：

  • 添加策略性日志记录以跟踪执行
  • 使用调试器断点
  • 检查变量状态
  • 检查函数返回值
  • 验证数据结构

8. 形成并测试假设

假设形成：

  • 什么可能导致此错误？
  • 哪些假设可能是错误的？
  • 哪些边界情况未被考虑？
  • 哪些依赖项可能缺失？

测试假设：

  • 添加日志记录以验证假设
  • 测试边界情况
  • 检查输入验证
  • 验证依赖项是否可用
  • 使用不同数据进行测试

9. 根本原因分析

调查步骤：

  1. 从症状开始：发生了什么错误？
  2. 向后追溯：错误发生前发生了什么变化？
  3. 检查模式：这是重复发生还是孤立事件？
  4. 关联事件：同时发生了其他什么？
  5. 识别原因：根本问题是什么？

分析框架：

## 错误分析

**错误**：[描述]
**频率**：[发生频率]
**时间线**：[何时开始]
**受影响的服务**：[哪些服务]
**用户影响**：[影响多少用户]

**根本原因假设**：
- [主要假设及证据]
- [替代假设]

**证据**：
- [支持假设的日志条目]
- [观察到的错误模式]
- [与其他事件的关联]

**推荐行动**：
- [立即修复]
- [长期预防]

10. 实施最小化修复

修复原则：

  • 修复根本原因，而不仅仅是症状
  • 进行尽可能小的更改
  • 保留现有功能
  • 不引入新的复杂性
  • 添加适当的错误处理

修复验证：

  • 使用复现案例测试修复
  • 验证没有回归
  • 检查边界情况
  • 确保错误处理适当
  • 确认修复完整

11. 记录解决方案

文档应包含：

  • 根本原因解释
  • 支持诊断的证据
  • 具体的代码修复
  • 测试方法
  • 预防建议

示例

示例1：空引用错误

输入：错误：TypeError: Cannot read property 'name' of undefined

输出：

## 调试分析

### 错误信息
- **类型**：TypeError
- **位置**：`src/services/user.js:45`
- **消息**：Cannot read property 'name' of undefined

### 根本原因
当用户未找到时，`getUser()` 函数返回 `undefined`，但代码假设它始终返回用户对象。

### 代码位置
```javascript
// src/services/user.js:45
const user = getUser(userId);
console.log(user.name); // ❌ 错误：user 是 undefined

修复

// 添加空值检查
const user = getUser(userId);
if (!user) {
  throw new Error(`User ${userId} not found`);
}
console.log(user.name); // ✅ 安全

预防

  • 始终验证可能返回 null/undefined 的函数的返回值
  • 使用可选链：user?.name
  • 添加TypeScript类型以在编译时捕获这些问题

### 示例2：数据库连接错误（日志分析）

**输入**：显示数据库连接失败的错误日志

**输出**：

```markdown
## 错误分析：数据库连接失败

### 检测到的模式

**错误**：来自PostgreSQL的 `ECONNREFUSED` 错误
**频率**：15次错误/分钟，2小时前开始
**时间线**：错误在14:30部署后开始

### 根本原因分析

**假设**：连接池耗尽

**证据**：
- 错误与高流量时段（14:30-16:30）相关
- 连接池大小：10，并发请求：50+
- 错误处理程序中没有连接清理
- 错误在峰值使用期间激增

**代码位置**：`src/db/connection.js:45`

**修复**：
```javascript
// 添加连接清理
try {
  const result = await query(sql);
  return result;
} catch (error) {
  // 确保连接被释放
  await releaseConnection();
  throw error;
}

监控查询：

SELECT count(*) FROM pg_stat_activity WHERE state = 'active';


## 参考文件

如需详细的调试工作流程、错误模式和技术，请根据需要加载参考文件：

- **`references/debugging_workflows.md`** - 按问题类型划分的常见调试工作流程、特定语言的调试、调试技术、调试清单和常见错误模式（数据库错误、内存泄漏、竞态条件、超时、身份验证错误、网络错误、应用程序错误、性能错误）
- **`references/INCIDENT_POSTMORTEM.template.md`** - 事件事后分析模板，包含时间线、根本原因分析和行动项

当调试特定类型的问题或分析错误模式时，加载 `references/debugging_workflows.md` 并参考相关部分。

## 最佳实践

### 调试方法

1.  **从症状开始**：在跳转到解决方案之前先理解问题所在
2.  **向后追溯**：从错误追踪到原因
3.  **测试假设**：不要假设，要验证
4.  **最小化更改**：只修复必要的内容
5.  **验证修复**：始终测试修复是否有效

### 日志分析技术

1.  **使用结构化日志记录**：JSON日志更易于解析和分析
2.  **包含上下文**：在所有日志中添加请求ID、用户ID、时间戳
3.  **日志级别**：使用适当的级别（错误、警告、信息、调试）
4.  **关联ID**：使用请求ID跨服务追踪错误
5.  **错误分组**：对相似错误进行分组以识别模式

### 错误模式识别

**基于时间的模式：**
- 特定时间的错误（部署窗口、高峰时段）
- 特定持续时间后的错误（超时、内存泄漏）
- 特定事件期间的错误（数据库迁移、缓存清除）

**频率模式：**
- 突然激增（部署问题、流量激增）
- 逐渐增加（内存泄漏、资源耗尽）
- 间歇性（竞态条件、时序问题）

**关联模式：**
- 多个服务同时出现错误（基础设施问题）
- 特定用户操作后的错误（应用程序错误）
- 与外部服务相关的错误（依赖项问题）

### 常见调试模式

**空值/未定义检查：**
```javascript
// 始终检查空值/未定义
if (!value) {
  // 处理缺失值
}

错误处理：

try {
  // 有风险的操作
} catch (error) {
  // 记录带有上下文的错误
  console.error('操作失败：', error);
  // 优雅地处理
}

日志记录：

// 策略性日志记录
console.log('操作前：', { userId, data });
const result = await operation();
console.log('操作后：', { result });

类型检查：

// 验证类型
if (typeof value !== 'string') {
  throw new TypeError('期望字符串');
}

监控设置

错误率监控：

// 随时间跟踪错误率
const errorRate = errors.length / totalRequests;
if (errorRate > 0.01) { // 1% 错误率阈值
  alert('检测到高错误率');
}

错误警报：

  • 错误率激增时警报（> 5% 增长）
  • 新错误类型时警报
  • 关键错误模式时警报
  • 跨服务错误关联时警报

预防策略

  1. 输入验证：在边界验证所有输入
  2. 类型安全：使用TypeScript或类型检查
  3. 错误边界：在适当级别捕获错误
  4. 测试：为边界情况编写测试
  5. 代码审查：审查代码以发现常见陷阱

相关用例

  • 修复生产错误
  • 调试测试失败
  • 调查用户报告的问题
  • 分析错误日志
  • 根本原因分析
  • 性能调试
  • 生产事件调查
  • 系统可靠性分析
  • 错误监控设置
  • 事后分析
  • 调试分布式系统