Chaos and Order

💡 왼쪽 원문을 읽으면서 오른쪽에 따라 써보세요. Tab 키로 힌트를 받을 수 있습니다.

本文是调试实战系列 5 篇中的第 1 篇。

分语言调试指南 ← 当前文章

分框架调试实战

分 IDE 调试完全整理

语言×框架故障案例集

远程调试实战指南

为什么调试策略要按语言区分

调试的本质是一样的（复现 → 观察 → 假设 → 验证），但每种语言的运行时、内存模型和工具链都不同，所以切入方式也不同。

Python：动态类型 + 以解释器为中心。运行时几乎什么都能看到，但类型相关的 bug 会一直藏到运行时才暴露。
JavaScript/TypeScript：事件循环与异步调用栈。在 Promise 链里，错误的来源很容易消失。
Go：goroutine、channel 与精简的运行时。并发 bug（竞态条件、死锁）是主要难关。
Java：基于 JVM，剖析生态成熟。内存泄漏与 GC 调优是主要课题。

下面只压缩整理了在实务中可以直接使用的做法。

分语言调试工具对比

项目	Python	JavaScript/TS	Go	Java
基础调试器	pdb / breakpoint()	Chrome DevTools / --inspect	Delve (dlv)	JDWP (jdb) / IDE 内置
剖析器	cProfile, py-spy	--cpu-prof, Chrome Perf	pprof	JFR, async-profiler
内存分析	memory-profiler, objgraph	--heapsnapshot, Chrome Memory	pprof heap	VisualVM, Eclipse MAT
异步追踪	asyncio debug mode	Async Stack Traces (DevTools)	goroutine dump, GODEBUG	Thread dump, Virtual Threads
静态分析	mypy, pylint	tsc --strict, ESLint	go vet, staticcheck	SpotBugs, Error Prone

分语言的常见 bug 模式与诊断法

语言	常见 bug 模式	诊断方法	预防策略
Python	TypeError/AttributeError（动态类型）、N+1 查询	用 breakpoint() 确认类型、django-debug-toolbar	类型提示 + mypy strict、select_related
JS/TS	Unhandled Promise rejection、内存泄漏（闭包）	async stack trace、比较 heap snapshot	eslint-plugin-promise、活用 WeakRef
Go	竞态条件、goroutine 泄漏、channel 死锁	-race 标志、pprof goroutine、stack dump	go vet、基于 context 的取消、errgroup
Java	NPE、OOM（内存泄漏）、线程死锁	exception breakpoint、分析 heap dump、jstack	活用 Optional、try-with-resources、Virtual Threads

1) Python 调试

运行方法

# 基本运行
python app.py

# 用 pdb 立即以调试模式运行
python -m pdb app.py

# 在 pytest 中进入失败点（在首次失败处停下并打开 pdb）
pytest -x --pdb

# 启用 asyncio 调试模式
PYTHONASYNCIODEBUG=1 python app.py

断点

def calculate_total(items):
    subtotal = sum(i.price for i in items)
    breakpoint()  # Python 3.7+ 内置
    return subtotal

条件断点

def process_order(order):
    # 只在特定条件下进入调试器 — 在大量循环中很有用
    if order.user_id == "U-9999":
        breakpoint()

    # 或者在 pdb 中设置条件（在 pdb 提示符下）
    # (Pdb) b process_order, order.status == "FAILED"

    result = validate(order)
    return result

实务技巧：

循环内的断点必须限定为条件断点。在上万次的循环里无条件命中，工作就停摆了。
数据体积大的对象只确认 len() 或核心字段。一次 print(huge_dict) 就可能让终端卡死。
用 PYTHONBREAKPOINT=0 可以让生产环境忽略 breakpoint。

内存泄漏探测

import tracemalloc

# 开始内存追踪
tracemalloc.start()

# --- 执行可疑区间 ---
process_large_dataset()
# --- 结束 ---

# 生成当前内存分配的快照
snapshot = tracemalloc.take_snapshot()

# 输出内存占用最多的前 10 个位置
top_stats = snapshot.statistics('lineno')
for stat in top_stats[:10]:
    print(stat)

# 用 objgraph 探测循环引用
import objgraph

# 创建数量最多的前 20 种对象类型
objgraph.show_most_common_types(limit=20)

# 可视化特定类型的引用图
objgraph.show_backrefs(
    objgraph.by_type('MyLeakingClass')[:3],
    filename='refs.png'
)

性能剖析

CPU

# 用 cProfile 按函数粒度测量 CPU 时间
python -m cProfile -o out.prof app.py
python -m pstats out.prof

# 对生产环境友好的采样（py-spy — 不中断进程）
py-spy top --pid <PID>
py-spy record -o profile.svg --pid <PID>

# 用 line_profiler 测量函数内部每一行的耗时
pip install line-profiler
kernprof -l -v slow_function.py

内存

pip install memory-profiler
python -m memory_profiler app.py

# 用装饰器方式只测量特定函数
# 在函数上方加 @profile 装饰器，即可按行输出内存使用量

2) JavaScript/TypeScript (Node.js) 调试

运行方法

# 开放调试端口（默认 9229）
node --inspect src/index.js

# 在第一行停下 — 对调试初始化过程很有用
node --inspect-brk src/index.js

# TypeScript（前提是 source map 已启用）
node --inspect-brk dist/index.js

# 用 ts-node 直接调试（开发环境）
node --inspect-brk -r ts-node/register src/index.ts

断点

async function syncUser(id: string) {
  const user = await repo.findById(id)
  debugger // 连接 DevTools/IDE 时中断
  return user
}

条件断点 (Chrome DevTools)

// 在 Chrome DevTools 中右键点击断点 → 选择 "Edit breakpoint"
// 条件示例：
//   user.role === "admin"
//   items.length > 100
//   error.code === "TIMEOUT"

// 在代码中按条件使用 debugger
function handleRequest(req: Request) {
  // 只在带有特定请求头时进入调试器
  if (req.headers['x-debug'] === 'true') {
    debugger
  }
  // ...
}

异步调试技巧

// 反面示例：在 Promise 链中无法追踪错误来源
fetchUser(id)
  .then((user) => fetchOrders(user.id))
  .then((orders) => process(orders))
  .catch((err) => console.log(err)) // 无从得知在哪里失败

// 正面示例：用 async/await 保住调用栈
async function syncUserOrders(id: string) {
  try {
    const user = await fetchUser(id) // 失败时会停在这一行
    const orders = await fetchOrders(user.id) // 停在这里则原因明确
    return await process(orders)
  } catch (err) {
    // 堆栈跟踪中会留下出错的那一行
    console.error('syncUserOrders failed:', err)
    throw err
  }
}

// 检测事件循环阻塞
// 用 --prof 标志生成 V8 剖析数据
// node --prof dist/index.js
// node --prof-process isolate-*.log > processed.txt

// 或者用 Clinic.js Doctor 自动诊断
// npx clinic doctor -- node dist/index.js

内存泄漏探测

// Heap snapshot 三快照法
// 1) 初始状态 snapshot
// 2) 反复执行可疑操作
// 3) 操作之后 snapshot
// 在 DevTools Memory 标签页用 Comparison 视图确认增长的对象

// 在代码中强制 GC 后确认内存
// node --expose-gc dist/index.js
if (global.gc) {
  global.gc()
}
console.log(process.memoryUsage())
// { rss, heapTotal, heapUsed, external, arrayBuffers }

性能剖析

# 生成 CPU profile 文件
node --cpu-prof dist/index.js

# Heap snapshot（用 SIGUSR2 信号触发）
node --heapsnapshot-signal=SIGUSR2 dist/index.js
kill -USR2 <PID>

# 用 Clinic.js 做综合诊断
npx clinic doctor -- node dist/index.js
npx clinic flame -- node dist/index.js
npx clinic bubbleprof -- node dist/index.js

在 Chrome DevTools 中：

Performance 标签页：确认 CPU 瓶颈与事件循环延迟
Memory 标签页：通过比较 Heap snapshot 追踪泄漏
Sources 标签页：启用 Async Stack Traces 查看异步调用栈

3) Go 调试

运行方法

go run ./cmd/api

Delve 调试器：

# 以调试模式运行
dlv debug ./cmd/api

# 调试测试
dlv test ./...

# 附加到正在运行的进程
dlv attach <PID>

# 远程调试（headless 模式）
dlv debug ./cmd/api --headless --listen=:2345 --api-version=2

断点

(dlv) break main.main
(dlv) break service/user.go:42
(dlv) continue
(dlv) print userID

条件断点

# 只在特定条件下中断
(dlv) break service/order.go:55
(dlv) condition 1 order.Status == "FAILED"

# 结合 hit count — 只在第 100 次调用时停下
(dlv) condition 1 hitcount % 100 == 0

# 确认 goroutine
(dlv) goroutines          # 全部 goroutine 列表
(dlv) goroutine 15        # 切换到特定 goroutine
(dlv) bt                  # 当前 goroutine 的堆栈跟踪

异步（goroutine）调试技巧

# race detector — 并发 bug 的第一道关口
go test -race ./...
go run -race ./cmd/api

// goroutine 泄漏探测：监控 runtime.NumGoroutine()
import "runtime"

func debugGoroutines() {
    // 周期性确认 goroutine 数量
    ticker := time.NewTicker(5 * time.Second)
    for range ticker.C {
        log.Printf("Active goroutines: %d", runtime.NumGoroutine())
    }
}

// 死锁诊断：用 SIGQUIT 导出全部 goroutine 栈
// 用 kill -QUIT <PID> 或 Ctrl+\ 触发
// 用 GOTRACEBACK=all 环境变量包含所有 goroutine

// 用基于 context 的超时预防死锁
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()

select {
case result := <-ch:
    return result, nil
case <-ctx.Done():
    return nil, fmt.Errorf("operation timed out: %w", ctx.Err())
}

性能剖析 (pprof)

import _ "net/http/pprof"
import "net/http"

go func() {
  _ = http.ListenAndServe(":6060", nil)
}()

# CPU 剖析 30 秒
go tool pprof http://localhost:6060/debug/pprof/profile?seconds=30

# Heap 内存分析
go tool pprof http://localhost:6060/debug/pprof/heap

# goroutine dump — 确认泄漏的必备手段
go tool pprof http://localhost:6060/debug/pprof/goroutine

# 用 Web UI 可视化
go tool pprof -http=:8080 http://localhost:6060/debug/pprof/profile?seconds=30

4) Java 调试

运行方法

./gradlew bootRun
# 或者
java -jar app.jar

远程调试端口：

# JDK 9+ 的远程调试设置
java -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005 -jar app.jar

# 在 Docker 容器中暴露调试端口
# docker run -p 5005:5005 -e JAVA_TOOL_OPTIONS="-agentlib:jdwp=..." app

断点

// 在 IntelliJ 中设置条件断点
// 右键点击断点 → 输入 Condition：
//   orderId.equals("ORD-12345")
//   items.size() > 100
//   user != null && user.getRole().equals("ADMIN")

// Logpoint（不中断，只输出日志）
// Evaluate and log: "Order processed: " + orderId + ", total=" + total

积极使用异常断点（NullPointerException、IllegalStateException 等）
用条件断点在大流量中只捕捉特定场景
用 logpoint 在不中断服务的情况下观察数值

内存泄漏探测

# 生成 Heap dump
jcmd <PID> GC.heap_dump /tmp/heapdump.hprof

# 发生 OOM 时自动生成 heap dump
java -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/tmp/ -jar app.jar

# 用 Eclipse MAT (Memory Analyzer Tool) 分析
# Leak Suspects Report → Dominator Tree → 按 Retained Size 排序

// 用 WeakReference 预防缓存泄漏
import java.lang.ref.WeakReference;
import java.util.WeakHashMap;

// 反面示例：不断往 static Map 里添加 → 内存泄漏
static Map<String, Object> cache = new HashMap<>();

// 正面示例：使用 WeakHashMap → GC 会在需要时回收
static Map<String, Object> cache = new WeakHashMap<>();

性能剖析

JFR (Java Flight Recorder)

# 在生产环境剖析 120 秒（开销低于 1%）
jcmd <PID> JFR.start name=onprod settings=profile duration=120s filename=app.jfr
jcmd <PID> JFR.stop name=onprod

# 用 JDK Mission Control (JMC) 分析 .jfr 文件
# Hot Methods → Call Tree → 确认排名靠前的热点函数

async-profiler

# CPU 剖析（30 秒，输出 flamegraph SVG）
./profiler.sh -d 30 -f cpu.svg <PID>

# 内存分配剖析
./profiler.sh -e alloc -d 30 -f alloc.svg <PID>

# Lock contention 剖析
./profiler.sh -e lock -d 30 -f lock.svg <PID>

# wall-clock 剖析（包含 I/O 等待）
./profiler.sh -e wall -d 30 -f wall.svg <PID>

通用调试流程（与语言无关）

固定复现条件：捕获输入、版本与环境变量。无法复现就无法调试。
把观测点降到最少：不要滥用断点。只放在边界位置。
一次只验证一个假设：一次只改一处。同时改两处就抓不住原因了。
剖析的优先顺序：按 CPU → I/O → 内存的顺序收窄可疑范围。
事后文档化：记录原因、探测信号与复发预防。这是不让同一个 bug 出现第二次的必要动作。

团队运营检查清单

在 PR 模板中加入「复现方法」字段
在故障报告中附上 flamegraph 或 JFR
调试会话设定时间上限（例如 30 分钟），超时后更换切入方式
共享本地与预发布环境的调试配置模板

综合排障检查清单

复现与环境确认

问题在本地能复现吗？
复现条件（输入值、环境变量、版本）是否准确记录了？
是否确认过与近期部署或变更的关联性？
在其他环境（预发布、生产）是否同样发生？

观测与分析

是否确认过错误日志与堆栈跟踪？
相关指标（CPU、内存、响应时间）是否有异常？
断点是否放在了边界位置（输入、输出、外部调用）？
是否用条件断点收窄了范围？

性能剖析

是否采集了 CPU 剖析数据？(py-spy / --cpu-prof / pprof / JFR)
是否确认过内存剖析数据（heap dump 或 snapshot）？
是否确认过 I/O 瓶颈（网络、磁盘、数据库）？
是否在 flamegraph 中识别出了排名靠前的热点函数？

解决与后续

是否识别出了根本原因（root cause）？
是否为修复内容编写了回归测试？
是否把原因、探测信号与复发预防写成了文档？
是否新增或改进了监控与告警规则？
是否向团队共享了 postmortem？

按症状快速诊断表

这是一张在现场看到症状后，能立刻找到该先怀疑哪种语言与工具的表。

症状	Python	JavaScript/TS	Go	Java
响应变慢（CPU 密集）	`py-spy top`, cProfile	`--cpu-prof`, Clinic flame	`pprof profile`	JFR, async-profiler
内存单调增长	tracemalloc, objgraph	比较 Heap Snapshot	`pprof heap`	`jcmd GC.heap_dump`, MAT
间歇性挂起（hang）	`PYTHONASYNCIODEBUG=1`	Async Stack Traces	goroutine dump (`SIGQUIT`)	`jstack`, Thread dump
并发 bug	threading.enumerate()	unhandledRejection 处理器	`go test -race`	Deadlock detection (IntelliJ)
类型/Null 错误	mypy strict + breakpoint()	tsc --strict	go vet, staticcheck	SpotBugs, Exception BP
N+1 查询	django-debug-toolbar	Prisma query logging	sqlx logging	Hibernate SQL + p6spy

调试环境搭建的一行命令

这是在新项目中快速搭好调试环境的命令合集。

# Python — 一次性安装调试与剖析工具
pip install debugpy py-spy line-profiler memory-profiler objgraph ipdb

# Node.js — 安装诊断工具
npm install -D @clinic/doctor why-did-you-render

# Go — Delve 调试器 + 静态分析工具
go install github.com/go-delve/delve/cmd/dlv@latest && go install honnef.co/go/tools/cmd/staticcheck@latest

# Java — 下载 async-profiler（Linux x64）
curl -L https://github.com/async-profiler/async-profiler/releases/latest/download/async-profiler-3.0-linux-x64.tar.gz | tar xz

收尾

好的调试者不是「知道很多工具的人」，而是能快速收窄问题的人。每种语言的工具不同，但核心是一样的：

先造出可观察的状态，再基于证据一步一步收窄。

只要理解各语言运行时的特性，并能熟练使用该生态中经过验证的工具，大部分 bug 都能在 30 分钟内找到原因。学习工具所花的时间，会以调试中省下的时间成倍回报你。

下一篇会讲分框架调试实战。整理了当语言之上叠加框架后，执行流程会怎样改变，以及断点该打在哪里。