python远程调试核心是本地调试器连接远程python进程，主流方案为debugpy（替代已弃用的ptvsd），支持直接监听、代码嵌入、ssh端口转发及docker容器调试，并需配置路径映射与端口开放。
Python 远程调试的核心是让本地调试器（如 VS Code、pycharm 或 pdb）连接到运行在远程机器（服务器、容器、虚拟机等）上的 Python 进程，从而实现断点、单步、变量查看等本地调试体验。
使用 ptvsd（已弃用，但仍有遗留项目在用）
ptvsd 是微软早期为 visual studio 和 VS Code 提供的 Python 调试协议实现，2020 年后已被 debugpy 取代。若维护旧项目，需注意：
- 安装：
pip install ptvsd - 代码中插入启动监听（注意端口开放和 host 绑定）：
import ptvsd; ptvsd.enable_attach(address=('0.0.0.0', 3000)); ptvsd.wait_for_attach() - VS Code 的
launch.json配置 type 为python，request为attach，指定port和host - 不推荐新项目使用，因缺乏维护且存在安全风险（如未设认证、绑定 0.0.0.0）
主流方案：用 debugpy 启动远程监听
debugpy 是 ptvsd 的继任者，轻量、活跃维护、兼容所有主流编辑器，也是 VS Code 默认调试后端。
- 远程机器安装：
pip install debugpy - 启动方式有两种：
• 直接运行脚本并监听：python -m debugpy --listen 0.0.0.0:5678 --wait-for-client your_script.py
• 或在代码中嵌入（适合已有服务）：import debugpy; debugpy.listen(('0.0.0.0', 5678)); debugpy.wait_for_client() - 确保防火墙放行对应端口（如 5678），生产环境建议仅绑定内网 IP 或加 SSH 端口转发
- 本地 VS Code 添加配置（
.vscode/launch.json）：
{ “name”: “Python: Remote Attach”, “type”: “python“, “request”: “attach”, “connect”: { “host”: “your-remote-ip”, “port”: 5678 }, “pathMappings”: [ { “localRoot”: “${workspaceFolder}”, “remoteRoot”: “/path/on/remote” } ] }
通过 SSH 端口转发 安全调试
不直接暴露调试端口到公网，而是利用 SSH 加密隧道把远程调试端口映射到本地，兼顾安全与便利。
立即学习“Python免费学习笔记（深入）”；
- 在本地终端执行：
ssh -L 5678:127.0.0.1:5678 user@remote-host
表示将远程机器的 5678 端口（需 debugpy 正在监听 127.0.0.1:5678）转发到本地 5678 - 远程端 debugpy 改为监听
('127.0.0.1', 5678)（更安全） - 本地 launch.json 中
host改为"localhost"，其余不变 - 适合调试云服务器、Docker 容器（需容器启动时加
-p 5678:5678或用docker exec注入）
调试 Docker 容器中的 Python 应用
容器默认隔离网络，需显式暴露调试端口并确保 debugpy 可被访问。
- Dockerfile 中安装 debugpy：
RUN pip install debugpy - 启动命令改为：
CMD [“python”, “-m”, “debugpy”, “–listen”, “0.0.0.0:5678”, “–wait-for-client”, “app.py”] - 运行容器时加参数：
docker run -p 5678:5678 your-image - 若用 docker-compose，需在
ports和environment中配置，并注意network_mode是否影响连接 - 路径映射（pathMappings）要对齐容器内路径（如
/app）与本地项目路径