VSCode调试Node.js失败主因是端口配置不一致或网络不通：launch.json的port必须与--inspect参数严格匹配（如9229），且服务需监听0.0.0.0而非127.0.0.1；调试前须用telnet或netstat验证端口监听状态及网络连通性。
VSCode 本身不“配置端口连接服务”，它只负责启动或附加调试器——端口是否被监听、由谁监听、监听在哪个 IP 上，完全取决于你的服务代码和运行时参数。配错 launch.json 的 port 字段不会让服务跑起来，但会让调试器连不上。
Node.js 的 --inspect 端口必须与 launch.json 的 port 严格一致
Node.js 调试依赖 Chrome DevTools Protocol（CDP），启动时需显式加 --inspect 参数；VSCode 的 launch.json 中 port 字段就是告诉调试器去连哪个 CDP 端口。
- 服务启动命令必须含
--inspect=0.0.0.0:9229（推荐绑定0.0.0.0，否则远程/容器内可能连不上） -
launch.json配置中"port": 9229必须和上面数字完全相同，不能是9228或92291 - 若用
nodemon，别把program指向nodemon二进制文件，应改用runtimeExecutable+runtimeArgs，并确保每次重启都带--inspect-brk - Windows 上如果端口被占用，错误提示是
EADDRINUSE，不是 VSCode 报错，而是 Node 启动失败——此时需先netstat -ano | findstr :9229杀掉旧进程
PHP Xdebug 的 xdebug.client_port 和 launch.json 的 port 要双向对齐
Xdebug 是客户端模式：PHP 进程主动连接 VSCode 监听的调试端口。所以两端端口号必须一致，且 PHP 进程得能路由到 VSCode 所在机器。
- 修改
php.ini，设xdebug.client_port=9004，同时确认xdebug.mode=debug和xdebug.start_with_request=yes -
launch.json中对应配置的"port": 9004必须匹配，否则 VSCode 根本不会收到连接请求 - 如果 PHP 运行在 Docker 容器里，宿主机的
9004端口要映射出来，且容器内 DNS 能解析宿主机 IP（常用host.docker.internal替代localhost） - Apache/Nginx 重启后，用
php --ini和php -m | grep xdebug验证配置已加载，别只改了文件却没生效
远程调试时，address 字段决定调试器往哪发连接请求
本地调试默认 "address": "localhost" 就够用；一旦涉及 Remote-SSH、Docker 或 WSL，这个字段就变成关键开关。
- Remote-SSH 场景下，
"address": "localhost"实际指向的是远程服务器的127.0.0.1，所以你的 Node 服务必须也在远程启动并监听0.0.0.0:9229 - Docker 容器内调试 Node，
"address"应设为宿主机 IP（如"172.17.0.1"）或"host.docker.internal"，不能写"localhost"（那会指向容器自己） - WSL2 中调试 Windows 主机上的服务，
"address"得填"localhost"（因为 WSL2 的 localhost 已自动映射到 Windows） - 所有场景下，
"localRoot"和"remoteRoot"的路径映射必须准确，否则断点打不进源码——尤其注意/home/user/app和C:\Users\user\app这类路径差异
最常被忽略的一点：端口只是通道，真正卡住调试的往往不是数字对不对，而是网络通不通、路径映不映、权限给没给。比如 Xdebug 连不上，先抓包看 PHP 进程有没有发 SYN；Node attach 失败，先 telnet 一下 localhost 9229 确认端口真在监听——别一上来就重装插件。
