VSCode如何配置远程调试连接端口_VSCode后端调试实战指南【进阶】-VSCode-PHP中文网

远程调试连不上90%是端口未对齐：远程服务未暴露、vscode未转发、防火墙/ssh隧道拦截，且remoteroot与localroot路径映射必须严格一致，node.js需绑定0.0.0.0，python需debugpy.listen(("0.0.0.0", port))，xdebug需设client_host为本地真实ip。

vscode如何配置远程调试连接端口_vscode后端调试实战指南【进阶】

远程调试连不上，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。

VSCode

避免常见的 VSCode 错误——设置冲突、调试器配置和扩展冲突。

下载

正确启动命令： 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 插件要启用