调试的艺术 开卷

这本不断更新的书籍将教你如何：

1. 快速调试常见问题
2. 让复杂问题也能被调试

脚注：改编自 Perl 的口号：“简单的事情应该容易，困难的事情应该可行”。

这是一本正在编写中的方法论与可直接复制粘贴的解决方案集锦，旨在帮助你成功调试简单及复杂的软件问题。部分章节已相当完整，另一些则将在后续阶段完成，还有一些尚未开始撰写。

除了调试方法论之外，本书的另一个重点是分享我所发现的最佳工具，以高效且尽可能“少掉头发”的方式完成调试工作。

引言

自 1995 年以来，我一直从事软件开发工作，其中很大一部分都涉及调试。多年来，我总结出多种高效的定位问题根源的方法——这是解决问题之前最为困难的环节。一旦弄清问题所在，通常其解决便指日可待。

时不时地，与我一同调试棘手问题的人会建议我将自己的方法分享给更多人。我过去总是认为这些方法难以普适化，但最近似乎这颗种子已经发芽。因此，在接下来的章节中，我将尝试分享一些见解，以减轻这一有时极为艰难的过程。

在空白状态下撰写调试相关内容颇具挑战性，而且由于我并未系统地记录用例，构建此书需要一定时间。因此，请您理解，这些页面在未来很长一段时间内都将是“进行中”的状态（WIP）。不过，希望其中的一些思路能够尽早传达给您，并在您的工作或个人项目中帮助您更轻松地完成调试任务。

目录

1. 快速调试方法论

2. 编译型程序的调试 - gdb、ldd、nm、LD_LIBRARY_PATH、LD_PRELOAD 等

3. Python 调试 - py-spy、路径管理、自动打印等

4. PyTorch 调试 - CPU 和 GPU 内存、性能、模型、张量等

5. 用于调试的 Unix 工具 - bash、strace、make、提示符、nohup 等

6. 机器学习项目的调试（外部）

贡献

如果您发现了 bug、错别字，或者希望提出改进建议，请随时提交 Issue 或 PR。

许可证

本网站的内容依据 署名-相同方式共享 4.0 国际 协议发布。

我的仓库概览

✔ 机器学习： ML 工程在线书 | ML 方法 | 移植

✔ 指南： 调试的艺术

✔ 应用： ipyexperiments

✔ 工具与速查表： bash | conda | git | Jupyter Notebook | make | Python | TensorBoard | Unix

The Art of Debugging 快速上手指南

the-art-of-debugging 并非一个需要安装的单一金牌软件包，而是一本开源的调试方法论书籍和实用代码片段集合。它旨在帮助开发者快速解决常规问题，并使复杂问题的调试成为可能。本指南将指导你如何获取并使用这份宝贵的资源。

环境准备

由于该项目主要包含文档、脚本片段和针对特定工具（如 gdb, py-spy, strace 等）的使用指南，因此没有严格的单一系统要求。但为了充分利用书中的内容，建议你的开发环境具备以下基础：

• 操作系统: Linux (推荐 Ubuntu/Debian 或 CentOS) 或 macOS。大部分命令行工具示例基于 Unix-like 系统。
• 版本控制: 已安装 git。
• 基础依赖 (根据你关注的章节选择性安装):
  • 通用编译型语言调试: gdb, binutils (包含 nm, ldd)。
  • Python 调试: Python 3.x, pip。
  • PyTorch 调试: PyTorch 环境。
  • 系统追踪: strace, make, bash。

国内加速建议: 克隆仓库时若遇到速度慢的问题，可使用国内镜像源（如 Gitee 镜像，若有）或配置 Git 代理。

# 示例：使用国内常见的加速方式（需确保网络可达）
git clone https://ghproxy.com/https://github.com/stas00/the-art-of-debugging.git
# 或者直接克隆（如果网络状况良好）
git clone https://github.com/stas00/the-art-of-debugging.git

安装步骤

该项目无需传统的“安装”过程，只需将仓库克隆到本地即可随时查阅。

1. 克隆仓库: 打开终端，执行以下命令将项目下载到本地：

   git clone https://github.com/stas00/the-art-of-debugging.git
   

2. 进入目录:

   cd the-art-of-debugging
   

3. (可选) 安装特定工具依赖: 根据你想实践的章节，安装相应的工具。例如，若要尝试 Python 调试章节：

   pip install py-spy
   

   若要尝试 Linux 系统调试：

   # Ubuntu/Debian
   sudo apt-get update
   sudo apt-get install gdb strace binutils
   
   # CentOS/RHEL
   sudo yum install gdb strace binutils
   

基本使用

本书的核心在于“按需查阅”和“复制粘贴（copy-n-paste）”实用的调试配方。

1. 浏览目录结构

在本地目录中，你可以看到按技术栈分类的文件夹：

• methodology/: 快速调试的方法论。
• compiled-programs/: C/C++ 等编译型程序调试（gdb, ldd 等）。
• python/: Python 脚本调试技巧。
• pytorch/: 深度学习模型、显存、性能调试。
• unix/: Unix 通用工具（bash, strace, make 等）。

2. 实战示例：使用 py-spy 分析 Python 性能

假设你正在阅读 python/ 章节，发现了一个关于性能分析的片段。

场景: 你的 Python 脚本 train.py 运行缓慢，你想查看哪行代码最耗时。

操作步骤:

1. 确保已安装 py-spy (见安装步骤)。
2. 直接复用书中推荐的命令模式：

   py-spy top -- python train.py
   

   或者对已运行的进程进行采样（假设 PID 为 12345）：

   py-spy dump --pid 12345
   

3. 实战示例：使用 strace 追踪系统调用

假设你在 unix/ 章节遇到一个程序启动失败但报错不明的问题。

场景: 程序 ./my_app 启动即退，无明确错误输出。

操作步骤:

1. 复用书中关于 strace 的用法：

   strace -f -o debug.log ./my_app
   

2. 查看生成的 debug.log 文件，定位最后发生的系统调用（通常是导致错误的 open, access 或 execve 等）。

4. 在线阅读

如果你不想克隆仓库，可以直接访问 GitHub 仓库页面浏览目录和具体内容：

• 主仓库: https://github.com/stas00/the-art-of-debugging
• 机器学习专项调试: https://github.com/stas00/ml-engineering/tree/master/debug

通过这种方式，你可以随时搜索关键词（如 "segmentation fault", "CUDA OOM", "slow training"），找到对应的解决方案并直接应用到你的项目中。