远程调试连不上90%是端口未对齐：远程服务未暴露、VSCode未转发、防火墙/SSH隧道拦截，且remoteRoot与localRoot路径映射必须严格一致，Node.js需绑定0.0.0.0，Python需debugpy.listen(("0.0.0.0", port))，Xdebug需设client_host为本地真实IP。
远程调试连不上，90% 是端口没对齐——不是本地没监听，而是远程服务没暴露、VSCode 没转发、防火墙/SSH 隧道又拦了一道。
remoteRoot 和 localRoot 映射错一个字符，断点就永远不命中
VSCode 断点依赖源码路径严格一对一匹配。容器里报 /app/server.js，你却在 launch.json 里写 "remoteRoot": "/app" 对应 "localRoot": "${workspaceFolder}"，看着合理，但只要本地路径实际是 /Users/me/project，而容器挂载的是 /app，中间差个 src 子目录，断点就失效。
- 进容器执行
pwd和ls -l /app，确认代码真实根路径 -
launch.json中必须显式写死"remoteRoot": "/app"，别信sourceFileMap自动推导 - Node.js 调试时，
pathMappings比remoteRoot/localRoot更可靠，尤其在 monorepo 或符号链接场景下 - Python + debugpy 用
"pathMappings"，格式为{"${workspaceFolder}": "/app"}，注意键是本地路径、值是远程路径
Node.js 的 --inspect 必须绑定 0.0.0.0，不是 127.0.0.1
写 node --inspect=9229 server.js 看似没错，但默认绑定 127.0.0.1:9229，只允许本机回环访问。VSCode 在本地通过 SSH 隧道或直接连接时，实际是从宿主机 IP（比如 192.168.1.100）发起请求，根本连不到 127.0.0.1。
- 正确启动命令：
node --inspect=0.0.0.0:9229 server.js - 验证是否生效：进服务器执行
netstat -tuln | grep :9229，输出中必须含0.0.0.0:9229 - Docker 容器内启动，还要加
-p 9229:9229（或 devcontainer.json 中"forwardPorts": [9229]） - 云服务器记得开安全组——端口放行对象是你的本地公网 IP，不是
0.0.0.0/0
Python debugpy.listen() 绑定地址和 launch.json 的 connect.host 必须一致
debugpy 默认监听 127.0.0.1，和 Node.js 一样，这会导致 VSCode 连接超时。很多人改了 Python 代码却忘了同步改 launch.json，或者反过来。
- Python 启动代码必须写成：
debugpy.listen(("0.0.0.0", 5678)) -
launch.json中对应配置：{ "name": "Attach to Remote", "type": "python", "request": "attach", "connect": { "host": "localhost", "port": 5678 }, "pathMappings": [ { "localRoot": "${workspaceFolder}", "remoteRoot": "/home/user/myproject" } ] } -
"host": "localhost"是指“从 VSCode 所在机器看的 localhost”，即 SSH 隧道终点或容器端口转发后的本地地址，不是远程服务器上的localhost - 如果用 SSH 隧道（
ssh -L 5678:localhost:5678 user@server），host就填localhost；如果直连远程 IP，则填该 IP
PHP Xdebug client_host 写成本地公网 IP，不是 127.0.0.1
PHP 调试走的是反向连接：Xdebug 主动连回本地 VSCode。所以 xdebug.client_host 必须设为你运行 VSCode 的那台机器的真实 IP（比如家庭宽带出口 IP 或公司内网 IP），设成 127.0.0.1 只在本地开发有效，远程必失败。
- 查本地 IP：Mac/Linux 执行
ipconfig getifaddr en0，Windows 执行ipconfig | findstr IPv4 - php.ini 中必须写：
xdebug.client_host=192.168.1.100（换成你的真实局域网 IP） - 若本地是 NAT 环境（如公司防火墙后），需配 SSH 端口转发：
ssh -R 9003:localhost:9003 user@server，再把xdebug.client_host改成127.0.0.1，xdebug.client_port保持9003 - VSCode 的
php.debug.port设置必须和xdebug.client_port一致，且 PHP Debug 插件要启用
端口转发不是“配了就通”，它是一条链路：远程服务监听 → 容器/Docker 网络暴露 → SSH 隧道或 VSCode Ports 转发 → 本地防火墙放行 → VSCode 调试器连接地址与端口完全匹配。漏掉任意一环，断点都只是灰色空心圆。
