vscode 连不上远程 node 调试端口主因是远程进程未启用 --inspect=0.0.0.0:9229、ssh 隧道未正确配置或 localroot/remoteroot 路径不匹配；需确保端口开放、隧道转发、路径映射一致且 docker 容器绑定 0.0.0.0。
VSCode 连不上远程 Node 进程的 debug 端口怎么办
多数时候不是配置错了，而是远程 Node 进程没开调试模式，或端口被防火墙/SSH 隧道阻断。VSCode 的 attach 模式依赖进程已启动并监听 --inspect 或 --inspect-brk 端口，且该端口必须可被本地 VSCode 访问。
常见错误现象：Could not connect to debug target at http://localhost:9229: Promise was rejected with the following reason: connect ECONNREFUSED 127.0.0.1:9229 —— 这说明 VSCode 尝试连本地 9229，但实际目标在远程机器上。
- 确保远程 Node 启动时加了
--inspect=0.0.0.0:9229（不是默认的127.0.0.1:9229），否则只监听回环地址，SSH 隧道无法穿透 - 用 SSH 建立端口转发：
ssh -L 9229:localhost:9229 user@remote-host；注意这里localhost指远程主机上的 localhost（即 Node 正在监听的地址） - 检查远程防火墙是否放行 9229（如
ufw allow 9229），Docker 容器需额外暴露端口并绑定到0.0.0.0 - VSCode 的
launch.json中port填本地映射端口（如9229），address必须是localhost（不是远程 IP）——因为隧道已把远程 9229 绑定到你本机的 9229
attach 模式下断点失效或“未加载源码”
VSCode 找不到匹配的源码位置，本质是路径映射失败。远程运行的文件路径（如 /app/src/index.js）和本地工作区路径（如 ~/project/src/index.js）不一致，调试器无法对齐。
关键参数是 localRoot 和 remoteRoot，必须显式声明：
-
localRoot：你 VSCode 当前打开的文件夹路径（建议用${workspaceFolder}） -
remoteRoot：Node 进程中__filename或require.main.filename显示的实际绝对路径 - 两者必须一一对应，不能有末尾斜杠差异（
/app/src≠/app/src/） - 如果用 Docker，
remoteRoot是容器内路径，localRoot是你本地挂载的对应目录
示例 launch.json 片段：
使用一条命令部署ProbeChain Rydberg测试网代理节点。自动注册为Agent(NodeType=1)，免gas，支持macOS/Linux/Windows。触发词：/r
{
"type": "node",
"request": "attach",
"name": "Attach to Remote",
"port": 9229,
"address": "localhost",
"localRoot": "${workspaceFolder}",
"remoteRoot": "/app",
"sourceMaps": true,
"outFiles": ["${workspaceFolder}/dist/**/*.js"]
}
重启远程 Node 后 VSCode 断点自动失效
VSCode 的 attach 是一次性连接，进程退出后调试会话就终止，不会自动重连。所谓“重连”，其实是手动触发或靠脚本维持。
- VSCode 本身不支持自动重连
attach，但可配合nodemon+ 自定义脚本实现近似效果 - 远程启动命令建议改用：
nodemon --inspect=0.0.0.0:9229 --signal SIGUSR2 index.js（避免用--watch触发全量重启导致调试中断） - 在本地配一个任务（
tasks.json），用ssh发送SIGUSR2信号重启远程进程，再手动点击 VSCode 的 “重新连接” 按钮（快捷键Ctrl+Shift+P→Debug: Reconnect） - 更稳的方式：改用
request: launch+preLaunchTask启动远程进程（需配合ssh命令封装），但调试体验略滞后于原生 attach
Docker 容器里 Node 调试连不上 --inspect 端口
根本原因是容器网络隔离 + 默认 --inspect 绑定 127.0.0.1，导致即使端口映射了也连不上。
- 启动容器必须加：
-p 9229:9229，且 Node 启动参数为--inspect=0.0.0.0:9229（不是--inspect-brk=0.0.0.0:9229，后者会卡住等待调试器连接，而 Docker 可能超时） - 如果用
docker-compose，确保ports和environment同时配置，例如：
services:
app:
image: node:18
ports: ["3000:3000", "9229:9229"]
command: node --inspect=0.0.0.0:9229 index.js
volumes: ["./src:/app/src"]
最后检查容器内是否真在监听：docker exec -it <container> netstat -tuln | grep 9229</container>；若无输出，说明 Node 根本没成功启用调试。
真正容易被忽略的是 remoteRoot 和 localRoot 的路径一致性 —— 很多人调通端口后仍断点无效，翻日志才发现 VSCode 把 /app/utils.js 当成了 /Users/me/project/utils.js，但实际映射应是 /Users/me/project/src → /app/src。差一层目录，断点就永远灰着。
