debugging-techniques

调试技巧

目的

为 Python、Go、Rust 和 Node.js 提供适用于本地、远程、容器和生产环境的系统化调试工作流。涵盖交互式调试器、使用临时容器调试容器，以及使用关联 ID 和分布式追踪的生产环境安全调试技术。

何时使用此技能

遇到以下情况时使用此技能：

• 在 Python、Go、Rust 或 Node.js 代码中设置断点
• 调试正在运行的容器或 Kubernetes Pod
• 设置远程调试连接
• 安全地调试生产问题
• 检查 goroutine、线程或异步任务
• 分析核心转储或堆栈跟踪
• 为特定场景选择合适的调试工具

按语言分类的快速参考

Python 调试

内置工具：pdb

# Python 3.7+
def buggy_function(x, y):
    breakpoint()  # Stops execution here
    return x / y

# Older Python
import pdb
pdb.set_trace()

必备 pdb 命令：

• list (l) - 显示当前行附近的代码
• next (n) - 执行当前行，跳过函数调用
• step (s) - 执行当前行，进入函数
• continue (c) - 继续执行，直到遇到下一个断点
• print var (p) - 打印变量值
• where (w) - 显示堆栈跟踪
• quit (q) - 退出调试器

增强工具：

• ipdb - 增强版 pdb，支持 Tab 补全和语法高亮（pip install ipdb）
• pudb - 终端图形界面调试器（pip install pudb）
• debugpy - VS Code 集成（包含在 Python 扩展中）

调试测试：

pytest --pdb  # Drop into debugger on test failure

有关 Python 调试模式的详细信息，请参阅 references/python-debugging.md。

Go 调试

Delve - Go 官方调试器

安装：

go install github.com/go-delve/delve/cmd/dlv@latest

基本用法：

dlv debug main.go              # Debug main package
dlv test github.com/me/pkg     # Debug test suite
dlv attach <pid>               # Attach to running process
dlv debug -- --config prod.yaml  # Pass arguments

必备命令：

• break main.main (b) - 在函数处设置断点
• break file.go:10 (b) - 在指定行设置断点
• continue (c) - 继续执行
• next (n) - 单步跳过
• step (s) - 单步进入
• print x (p) - 打印变量
• goroutine (gr) - 显示当前 goroutine
• goroutines (grs) - 列出所有 goroutine
• goroutines -t - 显示 goroutine 堆栈跟踪
• stack (bt) - 显示堆栈跟踪

Goroutine 调试：

(dlv) goroutines                 # List all goroutines
(dlv) goroutines -t              # Show stacktraces
(dlv) goroutines -with user      # Filter user goroutines
(dlv) goroutine 5                # Switch to goroutine 5

有关 Go 调试模式的详细信息，请参阅 references/go-debugging.md。

Rust 调试

LLDB - Rust 默认调试器

编译：

cargo build  # Debug build includes symbols by default

用法：

rust-lldb target/debug/myapp   # LLDB wrapper for Rust
rust-gdb target/debug/myapp    # GDB wrapper (alternative)

必备 LLDB 命令：

• breakpoint set -f main.rs -l 10 - 在指定行设置断点
• breakpoint set -n main - 在函数处设置断点
• run (r) - 启动程序
• continue (c) - 继续执行
• next (n) - 单步跳过
• step (s) - 单步进入
• print variable (p) - 打印变量
• frame variable (fr v) - 显示局部变量
• backtrace (bt) - 显示堆栈跟踪
• thread list - 列出所有线程

VS Code 集成：

• 安装 CodeLLDB 扩展（vadimcn.vscode-lldb）
• 为 Rust 项目配置 launch.json

有关 Rust 调试模式的详细信息，请参阅 references/rust-debugging.md。

Node.js 调试

内置工具：node --inspect

基本用法：

node --inspect-brk app.js       # Start and pause immediately
node --inspect app.js           # Start and run
node --inspect=0.0.0.0:9229 app.js  # Specify host/port

Chrome DevTools：

1. 打开 chrome://inspect
2. 点击“Open dedicated DevTools for Node”
3. 设置断点并检查变量

VS Code 集成： 配置 launch.json：

{
  "type": "node",
  "request": "launch",
  "name": "Launch Program",
  "program": "${workspaceFolder}/app.js"
}

Docker 调试：

EXPOSE 9229
CMD ["node", "--inspect=0.0.0.0:9229", "app.js"]

有关 Node.js 调试模式的详细信息，请参阅 references/nodejs-debugging.md。

容器和 Kubernetes 调试

使用 kubectl debug 和临时容器

适用情况：

• 容器已崩溃（无法使用 kubectl exec）
• 使用 distroless/精简镜像（没有 Shell 或工具）
• 需要调试工具，但不想重新构建镜像
• 调试网络问题

基本用法：

# Add ephemeral debugging container
kubectl debug -it <pod-name> --image=nicolaka/netshoot

# Share process namespace (see other container processes)
kubectl debug -it <pod-name> --image=busybox --share-processes

# Target specific container
kubectl debug -it <pod-name> --image=busybox --target=app

推荐的调试镜像：

• nicolaka/netshoot（约 380MB）- 网络调试（curl、dig、tcpdump、netstat）
• busybox（约 1MB）- 精简 Shell 和实用工具
• alpine（约 5MB）- 轻量级，带包管理器
• ubuntu（约 70MB）- 完整环境

Node 调试：

kubectl debug node/<node-name> -it --image=ubuntu

Docker 容器调试：

docker exec -it <container-id> sh

# If no shell available
docker run -it --pid=container:<container-id> \
           --net=container:<container-id> \
           busybox sh

有关容器调试模式的详细信息，请参阅 references/container-debugging.md。

生产环境调试

生产环境调试原则

黄金法则：

1. 尽量减少性能影响 - 评估开销，限制范围
2. 不执行阻塞操作 - 使用非侵入式技术
3. 注意安全 - 避免记录机密信息和个人身份信息
4. 可回滚 - 能够快速回滚（功能标志、Git）
5. 可观测 - 结构化日志、关联 ID、追踪

安全的生产环境技术

1. 结构化日志

import logging
import json

logger = logging.getLogger(__name__)
logger.info(json.dumps({
    "event": "user_login_failed",
    "user_id": user_id,
    "error": str(e),
    "correlation_id": request_id
}))

2. 关联 ID（请求追踪）

func handleRequest(w http.ResponseWriter, r *http.Request) {
    correlationID := r.Header.Get("X-Correlation-ID")
    if correlationID == "" {
        correlationID = generateUUID()
    }
    ctx := context.WithValue(r.Context(), "correlationID", correlationID)
    log.Printf("[%s] Processing request", correlationID)
}

3. 分布式追踪（OpenTelemetry）

from opentelemetry import trace

tracer = trace.get_tracer(__name__)

def process_order(order_id):
    with tracer.start_as_current_span("process_order") as span:
        span.set_attribute("order.id", order_id)
        span.add_event("Order validated")

4. 错误追踪平台

• Sentry - 带上下文的异常追踪
• New Relic - 集成错误追踪的 APM
• Datadog - 日志、指标、追踪
• Rollbar - 错误监控

生产环境调试工作流：

1. 检测 - 错误追踪告警、日志激增、指标异常
2. 定位 - 查找关联 ID、搜索日志、查看分布式追踪
3. 复现 - 尝试使用生产数据（已脱敏）在预发布环境中复现
4. 修复 - 创建功能标志，先部署到金丝雀环境
5. 验证 - 检查错误率、查看日志、监控追踪

有关生产环境调试模式的详细信息，请参阅 references/production-debugging.md。

决策框架

不同语言适用哪些调试器？

语言	主要工具	安装方式	最适用于
Python	pdb	内置	简单脚本、服务端环境
	ipdb	pip install ipdb	增强型用户体验、IPython 用户
	debugpy	VS Code 扩展	IDE 集成、远程调试
Go	delve	go install github.com/go-delve/delve/cmd/dlv@latest	所有 Go 调试、goroutine
Rust	rust-lldb	系统软件包	Mac、Linux、MSVC Windows
	rust-gdb	系统软件包	Linux、偏好使用 GDB 的场景
Node.js	node --inspect	内置	所有 Node.js 调试、Chrome DevTools

不同场景适用哪些技术？

场景	推荐技术	工具
本地开发	交互式调试器	pdb、delve、lldb、node --inspect
测试中的 Bug	针对测试的调试	pytest --pdb、dlv test、cargo test
远程服务	SSH 隧道 + 远程附加	VS Code Remote、debugpy
容器（本地）	docker exec -it	sh/bash + 调试器
Kubernetes Pod	临时容器	kubectl debug --image=nicolaka/netshoot
Distroless 镜像	临时容器（必需）	使用 busybox/alpine 的 kubectl debug
生产环境问题	日志分析 + 错误追踪	结构化日志、Sentry、关联 ID
Goroutine 死锁	Goroutine 检查	delve goroutines -t
崩溃进程	Core 转储分析	gdb core、lldb -c core
分布式故障	分布式追踪	OpenTelemetry、Jaeger、关联 ID
竞态条件	竞态检测器 + 调试器	go run -race、cargo test

生产环境调试安全检查清单

在生产环境调试之前：

• 这会影响性能吗？（评估开销）
• 这会阻塞用户吗？（使用非侵入式技术）
• 这可能会暴露机密信息吗？（避免转储变量）
• 有回滚计划吗？（Git 分支、功能标志）
• 我们先尝试过查看日志吗？（侵入性较低）
• 我们有相关联的 ID 吗？（追踪请求）
• 已启用错误追踪吗？（Sentry、New Relic）
• 能在预发布环境复现吗？（更安全的环境）

常见调试工作流

工作流 1：本地开发 Bug

1. 在代码中插入断点（因语言而异）
2. 启动调试器（dlv debug、rust-lldb、node --inspect-brk）
3. 执行到断点（run、continue）
4. 检查变量（print、frame variable）
5. 逐步执行代码（next、step、finish）
6. 找出问题并修复

工作流 2：测试失败调试

Python：

pytest --pdb  # Drops into pdb on failure

Go：

dlv test github.com/user/project/pkg
(dlv) break TestMyFunction
(dlv) continue

Rust：

cargo test --no-run
rust-lldb target/debug/deps/myapp-<hash>
(lldb) breakpoint set -n test_name
(lldb) run test_name

工作流 3：Kubernetes Pod 调试

场景：使用 distroless 镜像的 Pod 出现网络问题

# Step 1: Check pod status
kubectl get pod my-app-pod -o wide

# Step 2: Check logs first
kubectl logs my-app-pod

# Step 3: Add ephemeral container if logs insufficient
kubectl debug -it my-app-pod --image=nicolaka/netshoot

# Step 4: Inside debug container, investigate
curl localhost:8080
netstat -tuln
nslookup api.example.com

工作流 4：生产环境错误排查

场景：API 返回 500 错误

# Step 1: Check error tracking (Sentry)
# - Find error details, stack trace
# - Copy correlation ID from error report

# Step 2: Search logs for correlation ID
# In log aggregation tool (ELK, Splunk):
# correlation_id:"abc-123-def"

# Step 3: View distributed trace
# In tracing tool (Jaeger, Datadog):
# Search by correlation ID, review span timeline

# Step 4: Reproduce in staging
# Use production data (sanitized) if needed
# Add additional logging if needed

# Step 5: Fix and deploy
# Create feature flag for gradual rollout
# Deploy to canary environment first
# Monitor error rates closely

更多资源

按语言深入了解：

• references/python-debugging.md - pdb、ipdb、pudb、debugpy 详细指南
• references/go-debugging.md - Delve CLI、goroutine 调试、条件断点
• references/rust-debugging.md - LLDB 与 GDB、所有权调试、宏调试
• references/nodejs-debugging.md - node --inspect、Chrome DevTools、Docker 调试

按环境了解相关模式：

• references/container-debugging.md - kubectl debug、临时容器、节点调试
• references/production-debugging.md - 结构化日志、关联 ID、OpenTelemetry、错误跟踪

决策支持：

• references/decision-trees.md - 扩展的调试决策框架

动手示例：

• examples/ - 各语言的分步调试会话

相关技能

身份验证模式请参阅 auth-security 技能。 性能分析（可作为调试的补充）请参阅 performance-engineering 技能。 Kubernetes 操作（包括 kubectl debug）请参阅 kubernetes-operations 技能。 测试调试策略请参阅 testing-strategies 技能。 可观测性设置（日志记录、跟踪）请参阅 observability 技能。