就是七七维护过 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 或更早的兼容版本。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 调试前的准备：远程安装和环境检查
2.1 远程端安装指定版本
安装 debugpy 之前，先确认远程服务器的 Python 2.7 环境是否已经装了 pip。很多老服务器上 Python 2.7 的 pip 因为年代久远，会出现 SSL 证书报错或者索引源不可达的问题，这时候需要先修 pip 再装 debugpy。我遇到过一台 CentOS 6 的机器，pip 还是 8.x，访问新版 PyPI 索引时直接报 SSLError，最后是手动下载 debugpy 的 wheel 文件离线安装才通过的思路。如果你也遇到类似情况，直接去 PyPI 的 debugpy 页面下载对应 Python 2.7 和系统架构的 wheel，再用 pip install debugpy-1.8.0-py2.py3-none-any.whl 本地安装就行。
这里要注意一点，debugpy 1.8.0 发布时针对不同平台有多个 wheel。Linux x86_64 环境通常下载 debugpy-1.8.0-py2.py3-none-any.whl 这个通用包即可，但如果你是在 ARM 架构的服务器上跑，就需要找对应的 cp27 或 abi3 标签。最稳妥的方式还是先看 pip 能不能直接解析，不能解析再走离线方案。
2.2 本地 VS Code 需要准备什么
本地端要准备的其实很少。VS Code 里安装 Python 扩展，这是必须的，因为调试器类型的注册和调试会话的启动都由它负责。Python 扩展装好之后，它会自带 debugpy，所以本地不需要单独安装任何东西。如果你想用 Remote-SSH 的方式先连到远程机器查看代码，再在远程环境里启动调试，那就再装一个 Remote-SSH 扩展，这个是可选项，不装也不影响 debugpy 远程调试的基本功能。
我的建议是：如果远程服务器上的代码结构和本地工作区不完全一致，优先用 Remote-SSH 打开远程目录，这样你在 VS Code 里看到的文件路径和远程解释器实际解析的路径天然一致，断点命中率会高很多。本地工作区调试的方式也不是不行，但你必须额外处理好路径映射，稍后会具体讲。
3. 远程端代码改造与启动调试
3.1 代码内集成 debugpy
远程端的核心工作是让 debugpy 在目标进程里启动并进入监听状态。最简单的方式是在代码入口处加几行：
python复制import debugpy
debugpy.listen(("0.0.0.0", 5678))
print("等待调试器连接...")
debugpy.wait_for_client()
# 可选：到这里自动暂停
debugpy.breakpoint()
这段代码的逻辑很直白：listen 会让 debugpy 在指定端口上等待调试器接入，wait_for_client 会阻塞当前线程直到调试器完成连接，breakpoint 在连接成功后立刻触发一个断点。这样你从本地发起 attach 的瞬间，代码就停在断点处，可以马上看到当前堆栈和变量。
要注意的是 listen 的第一个参数我写成了 "0.0.0.0"，这意味着监听所有网卡接口。如果服务器有公网 IP，且防火墙没有限制，这就有安全风险。更稳的做法是监听内网地址，或者直接监听 "127.0.0.1"，然后通过 SSH 隧道转发端口到本地，这样只有本机才能通过隧道访问调试端口。
3.2 命令行模式启动
不是所有场景都适合改代码。比如你调试的是一个后台任务脚本，或者是一个用 Gunicorn 启动的 Django 服务，代码入口文件往往不是自己写的。这时候可以用命令行模式启动 debugpy：
bash复制python -m debugpy --listen 0.0.0.0:5678 --wait-for-client manage.py runserver 0.0.0.0:8000 --noreload
这条命令的意思是用 debugpy 模块来启动后续的脚本，并在 5678 端口上等待调试器。--wait-for-client 会在运行脚本之前就暂停，直到本地调试器连上，这能避免错过启动早期逻辑的断点。对 Gunicorn 这类带了多进程模型的服务器，命令行模式会有些复杂，因为 debugpy 默认只监听主进程，真正处理请求的 worker 是 fork 出来的子进程，不会继承监听端口。这种情况下要么改用单 worker 模式，要么把 debugpy.listen 写在 worker 初始化代码里，例如写进 Django 的 wsgi.py：
python复制import debugpy
debugpy.listen(("0.0.0.0", 5678))
debugpy.wait_for_client()
wsgi.py 在每次 worker 启动时都会执行一次，所以每个子进程都会有自己的调试端口。不过实际调试时只要连上其中一个进程就够了，哪个进程接收了请求就断在哪个进程里。
3.3 端口检查、防火墙与 SSH 隧道
启动 debugpy 之后，先确认端口是否真的在监听。
bash复制ss -lntp | grep 5678
如果能列出 LISTEN 状态的进程，说明 debugpy 启动成功。如果看不到，多半是代码执行顺序的问题，比如 debugpy.listen 被放在了某个条件判断之后，或者进程直接崩了。接着要看防火墙。Linux 上常见的 iptables 和后起的 firewalld 都可能挡住外部连接，最简单的方式是先临时放行 5678 端口测试连通性，调试完再关掉。如果你不想动防火墙，用 SSH 隧道几乎是零成本的安全方案：
bash复制ssh -L 5678:127.0.0.1:5678 user@remote_server
这条命令把远程服务器的 5678 端口转发到本机的 5678 端口，然后你在本地配置 host 时填 127.0.0.1 就行。这样做的好处是调试协议不会明文暴露在网络里，而且不需要任何防火墙改动。
4. 本地 launch.json 配置与路径映射
4.1 attach 模式调试配置
本地 VS Code 侧要做的核心事情就是新建一个调试配置。打开 .vscode/launch.json，新建一个 attach 类型的配置：
json复制{
"version": "0.2.0",
"configurations": [
{
"name": "Python 远程调试",
"type": "debugpy",
"request": "attach",
"connect": {
"host": "127.0.0.1",
"port": 5678
},
"pathMappings": [
{
"localRoot": "${workspaceFolder}",
"remoteRoot": "/home/user/myproject"
}
]
}
]
}
这里最容易忽略的是 type 字段。老版本的 VS Code Python 扩展里，调试器类型是 "python"，新版本改成了 "debugpy"。如果你用的是新版扩展，却复制了网上的旧配置，启动时会直接报“无法识别调试适配器类型”。所以配置之前先确认扩展版本，再决定 type 写什么。
request 固定为 "attach"，因为 debugpy 在远程端是主动监听的一方，本地是连接方。connect 里的 host 和 port 要对应远程的监听地址。如果你用 SSH 隧道连的是 127.0.0.1:5678，这里就填 127.0.0.1；如果调试端口安全地暴露在内网，这里就填内网 IP。
4.2 pathMappings 路径映射的细节
pathMappings 是远程调试里最容易出问题的地方。它的作用是把远程解释器看到的源码文件路径，映射到你本地工作区的路径。调试器在远程进程里命中某个文件时，会拿到一个类似 /home/user/myproject/module.py 的绝对路径，然后根据这个映射关系，在本地找到对应的 C:/Users/me/workspace/module.py 来显示源码和设置断点。
基础映射规则就是一条：
json复制{
"localRoot": "本地源码根目录",
"remoteRoot": "远程源码根目录"
}
如果映射不对，最常见的现象是断点能连上，但一断下来 VS Code 提示“找不到源文件”，或者断点设了却不生效。因为断点本身就是通过源文件路径绑定的，远程代码在哪个路径，VS Code 就得用映射关系找到同一个文件才能下断点。我建议在配置好之后，先在远程代码路径上打个日志断点，确认能命中，再做正式调试。
如果远程和本地的网页目录结构完全一致，通常一个顶层映射就够了。但如果 Python 2.7 项目用了复杂的包路径，比如把某个模块放在 /data/app/libs 下，而本地对应路径是 <workspace>/libs，就需要额外加一条映射。多映射的规则是按顺序匹配，遇到命中即停。
5. 实操记录：一次完整的远程 debug 流程
5.1 从远程启动到本地连接
下面我用一个实际例子完整走一遍流程。假设远程服务器 IP 是 192.168.1.100，项目路径是 /opt/app/myproject，我要调试的是一个定时任务脚本 task.py，脚本逻辑很简单：读取一批订单数据，做金额计算，最后写回数据库，但最近总有几个订单算错金额。
第一步，远程端在项目目录下执行命令启动脚本并等待调试器：
bash复制cd /opt/app/myproject
python -m debugpy --listen 127.0.0.1:5678 --wait-for-client task.py
这里我故意把监听地址设成 127.0.0.1，然后在本机开一个 SSH 隧道：
bash复制ssh -L 5678:127.0.0.1:5678 user@192.168.1.100
第二步，在本地 VS Code 打开项目目录，确保 launch.json 里的 remoteRoot 是 /opt/app/myproject，localRoot 是本地的工作区路径。然后按下 F5，选择“Python 远程调试”这个配置。
第三步，连接成功后，VS Code 底部状态栏会显示调试模式，调用堆栈面板会停留在脚本的第一行可执行代码，此时脚本是暂停的。你可以在 task.py 里需要检查的金额计算处点上行号设置断点，然后按 F5 继续运行。脚本走到断点处就会停下，左侧变量面板里能看到 order_id、amount、tax_rate 这些变量的实时值。
5.2 调试面板能做什么
在调试会话里，我个人最常用的几个功能按使用频率排序：变量查看、监视表达式、调用堆栈、调试控制台。变量查看可以展开对象的所有属性，Python 2.7 里的 dict 和 list 都能逐层展开。监视表达式可以输入 amount * tax_rate 这种临时表达式，实时计算结果。调试控制台则可以执行任意 Python 表达式，比如我可以在断点处手动调用某个函数，看看返回值是否符合预期。
但有个细节要提醒：Python 2.7 的 print 在调试控制台里有时会输出乱码，尤其是打印包含中文的字符串。这是因为 Python 2.7 的默认字符串编码和调试器控制台的编码处理方式不一致。遇到这种情况，用 repr() 包裹变量再打印，通常能看到可读的转义表示。还有就是在调试控制台里执行语句修改变量时，Python 2.7 会对 global 和局部作用域的处理方式不太一样，如果修改了全局变量发现不生效，可以在命名空间前显式声明 global。
6. 常见问题与排查技巧实录
6.1 连接被拒绝或连接超时
这是最多人遇到的问题。调试器连不上远程端，本质上就三类原因：端口没监听、网络不通、防火墙拦截。先按顺序排查。第一步，在远程服务器上执行 ss -lntp | grep 5678，确认 debugpy 进程是否在监听；第二步，在本地机器执行 telnet 远程IP 5678，看端口是否可连通；第三步，检查防火墙。如果确认监听正常且网络可通，但依然连不上，那就把 launch.json 里的 host 改成 127.0.0.1，并确认 SSH 隧道已经建立。
实际排错中我还发现过一个容易忽略的点：服务器上如果有多个 Python 版本，必须确保运行脚本的 Python 和安装 debugpy 的 Python 是同一个。我用 /usr/bin/python 跑脚本，却用 pip install 装到了 /usr/local/bin/python 环境下，结果脚本启动后根本没有 debugpy 模块，直接报 ImportError: No module named debugpy。
6.2 断点不命中
断点连上了，但运行到那行就是不暂停。这个问题八成出在 pathMappings 配置上。调试器是按源码文件的绝对路径来关联断点的，如果远程序执行时的文件路径和 remoteRoot 不匹配，断点就会被静默忽略。排查方式很简单：在 VS Code 的调试会话里打开“调用堆栈”面板，看当前暂停时的文件路径显示，和你在本地打开的同一个文件路径是否一致。如果不一致，就调整 pathMappings，把远程真实路径映射到本地。
另一种情况是源码版本不一致。远程服务器上跑的还是旧版代码，本地工作区已经改得面目全非，此时行号对不上，断点自然会乱掉。这种情况我只能建议在调试前把本地代码同步到和远程一致的版本，否则调试到的状态不是你想要的。
6.3 Python 2.7 独有的编码与模块坑
Python 2.7 的字符串处理是历史包袱，调试时也躲不开。最典型的是在调试控制台执行某些表达式时，如果表达式中包含非 ASCII 字符，解释器可能直接抛 UnicodeDecodeError。解决办法是从外部传入的字符串统一用 decode('utf-8') 处理，调试时也尽量在表达式里使用 unicode() 或 str.encode('utf-8') 做显式转换。
另外，Python 2.7 里没有 queue 模块的别名，标准库里有 Queue，在调试控制台里 import 时要特别注意大小写。这个对调试本身没有影响，但在你试图在控制台里验证某个队列相关逻辑时，会莫名踩坑。养成习惯，调试控制台里用 import Queue as queue 这样兼容旧版本的写法。
6.4 多进程服务调试命中不了
Flask 开发服务器带 use_reloader=True 时，会启动一个 reloader 进程再 fork 出主进程，debugpy 监听可能落在 reloader 上，真正处理请求的主进程反而没有监听。Gunicorn 更明显，默认多 worker 模式下，只有主进程监听调试端口，worker 进程接收请求后我们想断点的地方根本不在监听进程里。解决思路是用 --noreload 和 --workers 1 把服务变成单进程，或者按前面说的，把 debugpy.listen 写在每个 worker 的启动位置。前者适合快速调试，后者适合需要保持多进程行为的场景。
7. 我的经验与建议
经过这一轮折腾，我最大的体会是：Python 2.7 的项目虽然老，但调试体验不该跟着一起老。debugpy 远程调试这套方案我实际用了快半年，中间救过我好几次。一次是一个请求在某种极端数据组合下触发了内存泄漏的线索，如果没有断点变量查看和调试控制台的配合，我根本不可能在几分钟内锁定是哪段循环逻辑里生成了超量对象。
给你几个我的习惯性建议。第一，远程端永远用 --wait-for-client 或 wait_for_client()，它保证代码从一开始就在调试器控制之下，避免丢失启动阶段的状态。第二，调试端口不要裸奔在公网上，能用 SSH 隧道就一定用，不方便用隧道就在防火墙里严格限定来源 IP。第三，断点宁少勿多，Python 2.7 的调试速度毕竟不如 Python 3，如果断点打在循环体里，而且远程数据量又大，每断一次停几秒是很常见的，这会消磨耐心。
最后一件事，如果你调试完忘记关掉远程进程里的 debugpy，它会一直占着端口。我在生产服务器上就出现过一次，第二天同事报告服务端口被占用，查了半天才发现是我前一天留下的调试进程。所以调试完记得杀掉进程，或者在代码里用 debugpy.wait_for_client() 配合超时逻辑，比如设置 300 秒没连接就自动跳过，避免长期挂起影响业务。