Python 2.7老项目远程调试：VS Code + debugpy 断点调试实战

维护过 Python 2.7 项目的人，多少都有过这种体验：代码在一个你摸不到屏幕的服务器上跑，为了定位一个数据异常，你只能在关键位置插上 print，然后看日志、猜逻辑、再插 print。运气好，三轮迭代能锁住问题；运气不好，一个诡异的分支要耗掉整个下午。我自己的经历更折腾：一个跑了快十年的 Django 1.11 服务，代码量三万多行，迁移到 Python 3 的成本高到被业务侧直接否定，但线上功能又必须持续维护。后来我被逼着把本地到远程的调试链路完整打通，才发现原来 Python 2.7 的项目也能用 VS Code 的 debugpy 做远程断点调试，体验和调本地 Python 3 代码几乎一致。

这篇文章把我实际配置和踩坑的过程完整记录下来，核心方案是：在远程服务器上用 debugpy 监听调试端口，本地 VS Code 通过 attach 方式连接，配合 pathMappings 把远程源码路径映射到本地工作区。文章会覆盖版本选型、环境安装、代码改造、launch.json 配置、常见问题排查，适合正在维护 Python 2.7 老项目、又希望摆脱 print 调试的开发者参考。整个配置过程大概十分钟能完成，但里面有几个版本和路径上的坑，不提前说清楚，很容易卡住。

1. 为什么用 debugpy 远程调试老旧的 Python 2.7

1.1 从 pdb 到 debugpy：远程调试的现实需求

Python 2.7 项目最常见的调试方式，基本就是 print 加日志。这种方式在简单场景下够用，但一旦遇到复杂的数据处理逻辑，或某个只在特定输入下才出现的状态异常，print 的效率就太低了。你得反复修改代码、重启服务、翻日志，而且打印出来的信息永远是“某个时刻的全局快照”，很难还原调用链上的中间状态。pdb 虽然能在本地打断点，但它是交互式的，Python 2.7 时代想在远程服务器上做真正意义的断点调试，要么用 pdb 的远程扩展，要么就得靠 IDE 的远程调试协议。

debugpy 是微软在 VS Code Python 扩展里默认集成的调试器，也是早期 ptvsd 的继任者。它的调试协议经过完全重写，可以理解为“让你在本地 VS Code 里直接操作远程进程里的解释器状态”。相比 pdb，你能看到每个栈帧的局部变量、表达式求值、监视表达式，甚至在断点处动态修改变量值，这些能力是 print 调试完全不具备的。对我这种还在维护 Python 2.7 老代码的开发者来说，最大的价值就是：不需要把代码迁到 Python 3，也不需要换 PyCharm，就能获得一套现代调试体验。

1.2 版本选择的坑：Python 2.7 只能用 debugpy 1.8.0

这里有一个非常关键的坑，必须先说清楚。debugpy 在 1.8.0 版本之后，官方就完全抛弃了 Python 2.7 支持，从 1.8.1 开始最低要求 Python 3.7。所以你在远程服务器上执行 pip install debugpy 时，如果 pip 自动解析出最新版，大概率会得到一个根本无法在 Python 2.7 环境下导入的包，报错信息通常是语法错误或者找不到某个标准库模块。

正确做法是强制指定版本安装：

bash复制pip install debugpy==1.8.0

如果服务器上有多个 Python 版本，尽量用显式的解释器路径来安装：

bash复制/python2.7/bin/python -m pip install debugpy==1.8.0

装完之后可以用一行命令验证当前解释器能否正常导入：

bash复制python -c "import debugpy; print(debugpy.__version__)"

能输出 1.8.0 就说明环境没问题。顺带提一句，VS Code 的 Python 扩展本身也内置了 debugpy，但那个版本是给本地调试用的。远程调试时，真正在服务器端干活的是你装到 Python 2.7 环境里的 debugpy，两者版本不需要强制一致，但远程端必须是 1.8.0 或更早的兼容版本。

2. 调试前的准备：远程安装和环境检查

2.1 远程端安装指定版本

安装 debugpy 之前，先确认远程服务器的 Python 2.7