bug-detective

Bug Detective

一套系统的调试工作流，用于调查和解决代码错误、异常和故障。提供结构化的调试方法和常见错误模式识别。

核心理念

调试是一个科学的问题解决过程，需要：

1. 了解问题 - 清晰地定义症状和预期行为
2. 收集证据 - 收集错误消息、日志和堆栈跟踪
3. 提出假设 - 根据证据推断可能的原因
4. 验证假设 - 通过实验确认或排除原因
5. 解决问题 - 应用修复并进行验证

调试工作流

步骤 1：了解问题

开始调试前，请明确以下信息：

需要收集的信息：

• 完整的错误消息内容
• 错误的确切位置（文件名和行号）
• 重现步骤（如何触发错误）
• 预期行为与实际行为
• 环境信息（操作系统、版本、依赖项）

问题模板：

1. What is the exact error message?
2. Which file and line does the error occur at?
3. How can this issue be reproduced? Provide detailed steps.
4. What was the expected result? What actually happened?
5. What recent changes might have introduced this issue?

步骤 2：分析错误类型

根据错误类型选择调试策略：

错误类型	特征	调试方法
语法错误	代码无法解析	检查语法、括号匹配和引号
导入错误	ModuleNotFoundError	检查模块安装情况和路径配置
类型错误	TypeError	检查数据类型和类型转换
属性错误	AttributeError	检查对象属性是否存在
键错误	KeyError	检查字典键是否存在
索引错误	IndexError	检查列表/数组的索引范围
空引用	NoneType/NullPointerException	检查变量是否为 None
网络错误	ConnectionError/Timeout	检查网络连接、URL 和超时设置
权限错误	PermissionError	检查文件权限和用户权限
资源错误	FileNotFoundError	检查文件路径是否存在

步骤 3：定位问题来源

使用以下方法定位问题：

1. 二分查找法

• 注释掉一半代码，检查问题是否仍然存在
• 逐步缩小范围，直到找到有问题的代码

2. 日志跟踪

• 在关键位置添加 print/logging 语句
• 跟踪变量值的变化
• 确认代码执行路径

3. 断点调试

• 使用调试器的断点功能
• 单步执行代码
• 检查变量状态

4. 堆栈跟踪分析

• 从错误消息的堆栈跟踪中找出调用链
• 确定错误的直接原因
• 追溯根本原因

步骤 4：提出并验证假设

假设框架：

Hypothesis: [problem description] causes [error phenomenon]

Verification steps:
1. [verification method 1]
2. [verification method 2]

Expected results:
- If hypothesis is correct: [expected phenomenon]
- If hypothesis is wrong: [expected phenomenon]

步骤 5：应用修复

修复后，请验证：

1. 原始错误已解决
2. 没有引入新错误
3. 相关功能仍能正常工作
4. 已添加测试以防止回归

Python 常见错误模式

1. 缩进错误

2. 可变默认参数

3. 循环中的闭包问题

4. 迭代时修改列表

5. 使用 is 比较字符串

6. 忘记调用 super().__init__()

JavaScript/TypeScript 常见错误模式

1. this 绑定问题

2. 异步错误处理

3. 对象引用比较

Bash/Zsh 常见错误模式

1. 空格问题

# ❌ No spaces allowed in assignment
name = "John"  # Error: tries to run 'name' command

# ✅ Correct assignment
name="John"

# ❌ Missing spaces in conditional test
if[$name -eq 1]; then  # Error

# ✅ Correct
if [ $name -eq 1 ]; then

2. 引号问题

# ❌ Variables not expanded inside single quotes
echo 'The value is $var'  # Output: The value is $var

# ✅ Use double quotes
echo "The value is $var"  # Output: The value is actual_value

# ❌ Using backticks for command substitution (confusing)
result=`command`

# ✅ Use $()
result=$(command)

3. 未加引号的变量

# ❌ Unquoted variable, empty value causes errors
rm -rf $dir/*  # If dir is empty, deletes all files in current directory

# ✅ Always quote variables
[ -n "$dir" ] && rm -rf "$dir"/*

# Or use set -u to prevent undefined variables
set -u  # or set -o nounset

4. 循环中的变量作用域

# ❌ Pipe creates subshell, outer variable unchanged
cat file.txt | while read line; do
    count=$((count + 1))  # Outer count won't change
done
echo "Total: $count"  # Outputs 0

# ✅ Use process substitution or redirection
while read line; do
    count=$((count + 1))
done < file.txt
echo "Total: $count"  # Correct output

5. 数组操作

# ❌ Incorrect array access
arr=(1 2 3)
echo $arr[1]  # Outputs 1[1]

# ✅ Correct array access
echo ${arr[1]}  # Outputs 2
echo ${arr[@]}  # Outputs all elements
echo ${#arr[@]} # Outputs array length

6. 字符串比较

# ✅ Use `=` inside POSIX `[` tests and `==` inside Bash `[[ ]]` tests
if [ "$name" = "John" ]; then
if [[ "$name" == "John" ]]; then

# ❌ Using -eq for numeric comparison instead of =
if [ $age = 18 ]; then  # Wrong

# ✅ Use arithmetic operators for numeric comparison
if [ $age -eq 18 ]; then
if (( age == 18 )); then

7. 命令失败后仍继续执行

# ❌ Execution continues after command failure
cd /nonexistent
rm file.txt  # Deletes file.txt in current directory

# ✅ Use set -e to exit on error
set -e  # or set -o errexit
cd /nonexistent  # Script exits here
rm file.txt

# Or check if command succeeded
cd /nonexistent || exit 1

常用调试命令

Python pdb 调试器

python -m pdb script.py
pytest -x -vv tests/test_target.py

Node.js 检查器

node --inspect-brk app.js
node --trace-warnings app.js

Git 二分查找

git bisect start
git bisect bad
git bisect good <known-good-commit>

Bash 调试

# Run script in debug mode
bash -x script.sh  # Print each command
bash -v script.sh  # Print command source
bash -n script.sh  # Syntax check, no execution

# Enable debugging within a script
set -x  # Enable command tracing
set -v  # Enable verbose mode
set -e  # Exit on error
set -u  # Error on undefined variables
set -o pipefail  # Fail if any command in pipe fails

预防性调试

1. 使用类型检查

2. 输入验证

3. 防御性编程

4. 日志记录

调试检查清单

开始前

• 获取完整的错误消息
• 记录错误的堆栈跟踪
• 确认复现步骤
• 了解预期行为

调试期间

• 检查近期的代码更改
• 使用二分法定位问题
• 添加日志以跟踪变量
• 验证假设

解决后

• 确认原始错误已修复
• 测试相关功能
• 添加测试以防止回归
• 记录问题和解决方案

更多资源

参考文件

如需了解详细的调试技术和模式：

• references/python-errors.md - Python 错误详情
• references/javascript-errors.md - JavaScript/TypeScript 错误详情
• references/shell-errors.md - Bash/Zsh 脚本错误详情
• references/debugging-tools.md - 调试工具使用指南
• references/common-patterns.md - 常见错误模式

示例文件

可运行的调试示例：

• examples/debugging-workflow.py - 完整的调试工作流示例
• examples/error-handling-patterns.py - 错误处理模式
• examples/debugging-workflow.sh - Shell 脚本调试示例