在日常的后端研发中，我们常常会被“本地跑不通、线上报错”的尴尬局面逼到崩溃边缘。别慌！只要掌握了在 Debian 上的 Python 远程调试技巧， 就能像打开了新世界的大门——不再盲目打印日志，也不必频繁重启服务，一行代码、一条命令就能把问题抓个正着。

一、为什么要在 Debian 上做远程调试？

Debian 是很多服务器的首选系统，它的稳定性和包管理让人爱不释手。但正主要原因是“稳”，很多新手往往只会在本地跑通代码，然后直接把源码拷贝到服务器上运行。后来啊是：，挺好。

• 依赖版本不匹配导致异常。
• 生产环境的配置与本地差异大。
• 难以复现线上偶发的性能瓶颈。

此时 如果能够直接把本机的 IDE 与服务器上的 Python 进程“牵手”， 你猜怎么着？ 实时查看变量、堆栈甚至修改现场状态，那种快感简直让人欲罢不能。

二、 工具大比拼——挑选适合自己的调试方式

三、 准备工作：让你的 Debian “开门迎客”

1. 确认系统环境

# 更新软件源
sudo apt update && sudo apt upgrade -y
# 安装 python3-pip
sudo apt install -y python3-pip

换句话说... 如果你在服务器上已经用了虚拟环境，记得先激活它，这样后面的依赖才会装到正确的位置。

2. 安装调试器库

# 推荐使用 debugpy， 它兼容 VSCode 与 PyCharm
pip install --user debugpy
# 若想保守一点，也可以装 pdb++ 提升交互体验
pip install --user pdbpp

⚡ 小贴士：如果你使用的是根用户或者系统全局环境，请去掉 --user 参数，否则可能出现权限冲突，最后强调一点。。

3. 配置 SSH 无密码登录

为了让本地 IDE 能够顺畅“娱乐”， 建议使用密钥对登录而不是每次都输入密码：，我跪了。

# 本地生成密钥
ssh-keygen -t ed25519 -C ""
# 将公钥复制到 Debian 服务器
ssh-copy-id user@debian-host

⚠️ 注意：生产环境务必限制 root 登录，并通过防火墙仅开放必要端口。

四、一步步玩转 debugpy + VSCode Remote‑SSH

A. 在本地 VSCode 中安装必备插件

• Python: 提供语言服务和调试适配器。
• Remote‑SSH: 把本机编辑器映射到远端机器。
• *可选*：Pylance** 或 **Jedi**：提升智能提示速度。

B. 建立 Remote‑SSH 会话

1. 打开 VSCode → 按下 F1, 输入 “Remote‑SSH: Connect to Host”。输入类似 User@debian-host.
2. 连接成功后你会看到左下角出现 “SSH: debian-host”。此时所有文件操作都发生在服务器上。
3. 在左侧资源管理器里打开项目根目录，以确保路径一致性。

C. 配置 launch.json 为远程附加模式

图啥呢？ .vscode/launch.json 示例：

{
    "version": "0.2.0",
    "configurations": ,
            // 防止意外退出时自动关闭连接
            "justMyCode": false,
            "redirectOutput": true
        }
    ]
}

💡 小技巧：如果你的项目结构比较深， 可以多写几条 pathMappings，让 IDE 正确定位源码行号。

D. 在目标脚本里插入启动监听代码

加油！ 假设你要调试的入口文件是 /home/user/project/app.py, 在合适位置加入：

# ==== Debugger Hook ====
import debugpy
# 让 debugger 在指定端口等待客户端连接
debugpy.listen)
# 如果希望程序暂停到断点再继续，可加下面这行：
# debugpy.wait_for_client
# =========================
print
# 以下为业务代码…
if __name__ == "__main__":
    main

有啥用呢？ ⚙️ 此段代码可以放在主函数前或任何你想马上捕获现场的地方。记得上线前把它注释或通过环境变量控制，以免泄露调试入口。

E. 启动脚本并附加调试器

1. SSh 登录后在终端施行：

五、 如果你只想用最原始的方式——PDB+SSH 隧道

实际上... PDB 是 Python 自带的交互式调试器，它无需额外依赖，只要能 ssh 到目标机器，就能开启一次“裸奔”式排错。这种方法特别适合：

• No GUI 环境。

A. 把 PDB 注入目标脚本

import pdb; pdb.set_trace