张芷铭的个人博客

debugpy

debugpy 是遵循 Debug Adapter Protocol (DAP) 标准的 Python 调试器，支持跨 IDE、远程调试、多进程等场景。

核心特性

  • DAP 协议：统一 IDE 与调试器通信规范，兼容 VS Code、PyCharm 等
  • 远程调试：通过 socket 连接服务器/容器中的 Python 应用
  • 多进程支持：原生支持 multiprocessing 调试
  • Jupyter 集成：可调试 Notebook 代码

安装

1

pip install debugpy

基础用法

命令行调试

1

python -m debugpy --listen 5678 --wait-for-client script.py

VS Code 配置

本地调试（.vscode/launch.json）：

1
2
3
4
5
6
7

{
    "name": "Python: 本地调试",
    "type": "python",
    "request": "launch",
    "program": "${file}",
    "justMyCode": true
}

远程调试：

1
2
3
4
5
6
7
8
9

{
    "name": "Python: 远程调试",
    "type": "python",
    "request": "attach",
    "connect": {"host": "服务器IP", "port": 5678},
    "pathMappings": [
        {"localRoot": "${workspaceFolder}", "remoteRoot": "/app"}
    ]
}

远程调试流程

1
2
3
4

# 服务端启动
python -m debugpy --listen 0.0.0.0:5678 --wait-for-client app.py

# 客户端通过 VS Code attach 连接

Jupyter Notebook 调试

1
2
3

import debugpy
debugpy.listen(5678)
# VS Code attach 后即可调试

启动方式对比

方式说明推荐
debugpy --listen ...直接调用可执行入口Linux/macOS
python -m debugpy --listen ...模块方式启动100% 兼容

python -m debugpy 严格使用当前 Python 解释器，避免多版本混乱。

调试技巧

技巧用途
条件断点仅在条件满足时触发
日志断点不修改代码输出日志
变量监视实时追踪变量变化
SSH 隧道ssh -L 5678:localhost:5678 user@server 安全连接

常见问题

问题原因解决
远程连接失败端口/防火墙检查 iptables，确认监听 0.0.0.0
断点灰色路径映射错误检查 pathMappings 配置
调试卡死死锁/资源占用关闭 justMyCode 定位问题

参考

Comments