VSCode远程调试服务器程序必须满足三个硬条件：远程进程已启动调试器并监听端口、本地launch.json配置与远程路径/端口/API版本严格匹配、网络层双向可达；Remote-SSH连接成功不等于调试就绪，需单独启动调试器、正确配置launch.json的attach模式、确保端口开放与映射准确。
VSCode 远程调试服务器程序，不是“连上就行”，而是必须满足三个硬条件：远程进程已启动调试器并监听端口、本地 launch.json 配置与远程路径/端口/API 版本严格匹配、网络层（SSH 端口或调试端口）双向可达。缺一不可，否则断点不命中、变量为空、连接被拒绝全是必然结果。
Remote-SSH 连接成功 ≠ 调试就绪
Remote-SSH 插件只负责建立文件系统级的远程编辑通道，它不启动任何调试服务，也不转发调试端口。你看到左下角显示 SSH: your-server，仅代表 VSCode 正在读写远程磁盘——此时若直接按 F5，会报错 Failed to launch: could not find program 或 connection refused。
- 必须单独在远程服务器上运行调试器（如
dlv exec ./myapp --headless --api-version=2 --addr=:2345、debugpy --port 5678 myscript.py） - 确保调试器监听地址是
0.0.0.0:2345（而非127.0.0.1:2345），否则本地无法访问 - 检查远程防火墙：
sudo ufw status或sudo firewall-cmd --list-ports，确认调试端口（如 2345、5678）已放行
launch.json 中 attach 模式的关键字段不能凭感觉填
Go 用 dlv、Python 用 debugpy、Node.js 用 --inspect，各自对 launch.json 字段要求不同。填错一个字段，VSCode 就会静默失败，不报错也不停断点。
-
mode必须为attach（不是launch），因为目标进程已在远程运行 -
port和host是远程服务器的监听地址，不是本地的；例如"host": "192.168.31.232"，不是"host": "localhost" -
remotePath（Go）或pathMappings（Python/Node）必须精确映射远程代码路径到本地工作区路径，比如远程是/home/user/project/main.go，本地打开的是~/code/project，就得写"remotePath": "/home/user/project"或"pathMappings": [ ["/home/user/project", "${workspaceFolder}"] ] - Go 的
apiVersion必须与远程dlv version输出一致（常见为2），版本不匹配会导致连接后立即断开
调试器端口被占用或未暴露是高频故障点
很多人在服务器上执行 dlv --headless --addr=:2345 后仍连不上，第一反应是配置错了——其实大概率是端口冲突或 SSH 隧道未启用。
- 先确认端口是否被占：
lsof -i :2345或netstat -tuln | grep :2345 - 如果用 Remote-SSH 连接，但调试器监听的是公网 IP，而服务器在 NAT 后，建议改用 SSH 端口转发：在本地终端运行
ssh -L 2345:localhost:2345 user@server-ip，然后launch.json中设"host": "localhost"、"port": 2345 - 容器场景下，
-p 2345:2345必须显式声明，且容器内调试器要监听0.0.0.0:2345，不能只绑127.0.0.1 - 某些云服务器（如阿里云、腾讯云）安全组默认屏蔽非 22/80/443 端口，需手动放行调试端口
最常被忽略的一点：远程调试器进程必须持续运行。一旦你在服务器上 Ctrl+C 终止了 dlv 或 debugpy，VSCode 不会自动重连，断点立刻失效，且控制台无明显提示——你得自己去看远程终端是否还活着。
