vscode调试node.js端口配错导致90%断点失效，因调试器仅按launch.json的port连接，而node进程端口由--inspect参数决定，二者必须严格对齐；attach模式需request:"attach"、port与启动命令一致、protocol:"inspector"，并确保address、sourcemap路径匹配。
VSCode 调试 Node.js 时端口配错，90% 的断点不生效、连接失败、灰点问题都源于此——不是代码写错了，是调试器根本没连上进程。
为什么端口必须手动对齐，不能靠 VSCode 自动推断
VSCode 的 Node 调试器不会主动扫描端口，它只按 launch.json 里写的 port 去连。而 Node 进程是否暴露调试端口、暴露在哪个地址和端口，完全取决于你启动时加的参数（比如 --inspect=0.0.0.0:9229）或脚本配置。两者不一致，就会报 Cannot connect to the target 或断点全灰。
-
port字段只在request: "attach"模式下生效；request: "launch"模式下 VSCode 自己拉起进程并控制端口，但容易和npm run start:debug冲突 - 默认端口是
9229，但如果你改了--inspect=127.0.0.1:3001，launch.json就必须同步改成"port": 3001 - 地址绑定影响连通性：用
--inspect=127.0.0.1:9229时，VSCode 在 WSL 或远程容器里可能连不上；换成--inspect=0.0.0.0:9229更稳妥（注意仅限本地开发）
attach 模式下 port 配置的实操要点
这是当前最稳定、兼容 NestJS / TypeScript / nodemon 的方式。关键不是“VSCode 启动 Node”，而是“VSCode 附加到已运行的 Node 进程”。
-
launch.json中必须包含："request": "attach"、"port": 9229（与启动命令一致）、"protocol": "inspector" - 删掉所有
runtimeExecutable、runtimeArgs、program字段——它们属于launch场景，混用会导致调试器行为不可控 - 加上
"restart": true，这样 nodemon 或 NestJS 重启后，VSCode 会自动重连新进程，不用手动点三角形 - 终端先执行
npm run debug（确保输出Debugger listening on ws://127.0.0.1:9229/），再点 VSCode 的「开始调试」
常见端口错误现象与快速验证法
别猜，直接看终端输出和网络状态。
- 没看到
Debugger listening on ws://...？说明 Node 进程根本没启用--inspect——检查package.json的脚本，比如"debug": "node --inspect-brk dist/main.js" - 看到
address already in use？两个进程在抢同一个端口。关掉所有node进程，或换端口（如--inspect=9230+"port": 9230） - 断点能打但不触发？确认
sourceMap开启且outFiles匹配编译路径，否则 VSCode 找不到 JS 和 TS 行号的映射关系 - Windows 上用 WSL2？
--inspect=0.0.0.0:9229+"port": 9229是刚需，127.0.0.1会因网络隔离连不上
端口本身很简单，难的是让「VSCode 认的端口」、「Node 实际监听的端口」、「网络可达的地址」三者严格对齐。漏掉任意一环，调试就停在连接阶段——这不是配置技巧问题，是通信链路没打通。
