VS Code 配置 launch.json 调试远程服务进程

远程服务已经在 Linux 主机上运行时，最稳妥的做法不是把调试器装在本机后反复猜端口，而是在 VS Code 的 Remote-SSH 工作区里保存一份 .vscode/launch.json，用 request: attach 连接已经开启检查端口的进程。这样菜单入口、端口、远程路径和断点行为都能随项目配置复用。

VS Code 官方地址：https://code.visualstudio.com/docs/debugtest/debugging-configuration

一、先把调试入口放到远程工作区

在 VS Code 按 Ctrl+Shift+P（macOS 为 ⌘⇧P），执行 Remote-SSH: Connect to Host...，选择目标主机。连接完成后，从 File → Open Folder... 打开远程项目目录。观察窗口左下角的远程连接标识，以及资源管理器中项目文件是否来自远端。

随后点击左侧 Run and Debug，选择 create a launch.json file。如果已经存在配置，点击配置下拉框旁的齿轮，直接打开工作区的 .vscode/launch.json。这里的关键是不要在本机用户设置里另建一份同名配置，否则换到远程窗口时容易看见错误的项目路径。

看到项目根目录下出现 .vscode/launch.json，并且配置下拉框能列出新条目，就可以进入下一步。它说明文件位置正确，但还不代表远程进程已经开放调试端口。

二、把 launch.json 改成 attach 配置

以远程主机上的 Node.js 服务为例，先让服务以检查模式启动。下面的命令只是启动方式示例，端口由团队约定；不要把调试端口直接暴露到公网。

# 在远程主机的项目目录启动检查模式，供 VS Code attach
node --inspect=127.0.0.1:9229 server.js

# 只在远程主机上确认监听状态，不把结果当成 VS Code 已连接
ss -lntp | grep 9229

回到 .vscode/launch.json，把生成的模板改成下面的配置。JSON 必须保持有效，所以不在代码块里塞注释；每个字段的作用放在代码后解释。

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "attach",
      "name": "Attach Remote Node Service",
      "address": "127.0.0.1",
      "port": 9229,
      "localRoot": "${workspaceFolder}",
      "remoteRoot": "/srv/example-service"
    }
  ]
}

如果 Remote-SSH 窗口和服务进程在同一台远程主机，127.0.0.1:9229 通常指向远程主机本身；如果服务在另一台机器或容器里，不能照抄这个地址，需要改成可达的调试端点，并同步处理 SSH 隧道、容器端口或网络策略。

三、启动 attach 并确认断点真的连上

保存文件后，按 F5，或点击 Run and Debug → Attach Remote Node Service。VS Code 会按照配置连接已经运行的进程。随后在服务入口或请求处理函数左侧灰色边栏点击一次，设置红色断点，再访问对应接口。

可见状态应当同时满足三项：调试工具栏出现继续、单步和停止按钮；编辑器在断点行暂停；Debug Console 可以读取当前作用域变量。只看到配置被选中而没有暂停，通常只能说明文件被解析，不能证明路径映射和远程进程连接成功。

# 在远程主机上确认服务仍由预期用户运行
ps -ef | grep '[n]ode.*server.js'

# 确认调试端口仍在监听；连接状态由 VS Code 面板另行确认
ss -lntp | grep 9229

四、连接失败时按端口、路径、启动方式排查

1. 报 connection refused：先看远程服务是否真的使用 --inspect 启动，端口是否写成了另一个值；服务重启后端口也可能改变。
2. 能连接但断点变灰：优先核对 remoteRoot。它应与远程进程加载脚本的绝对路径对应，而不是本机复制出来的目录。
3. 断点停住但变量不对：确认当前选中的配置、Node.js 进程和源码版本属于同一次部署，避免旧进程仍占用 9229。
4. 远程窗口找不到配置：从资源管理器确认 .vscode/launch.json 位于当前打开的工作区根目录；多根工作区还要确认配置属于正确的文件夹。

当服务在容器中运行时，remoteRoot 应指向容器内路径，不能只填宿主机路径；当 SSH 隧道负责转发端口时，address 和 port 应填写 VS Code 所在调试环境实际能够访问的端点。调试完成后点击停止，并关闭不再需要的 inspect 端口。

五、最后用一张清单验收

这套配置的价值在于把“连哪台机器、连哪个端口、源码怎样对应”写成可审查文件。远程服务换部署目录时只改 remoteRoot，服务换端口时同步修改启动参数和 launch.json，再通过一次断点命中确认，而不是凭界面是否打开来判断完成。

相关问题

launch 和 attach 应该选哪个？

launch 让调试器负责启动应用；attach 连接已经运行且开放调试端口的进程。远程服务由 systemd、容器或部署脚本管理时，通常更适合 attach。

为什么端口通了，断点仍然不命中？

端口只证明调试端点可达，断点还依赖源码路径映射、进程加载的脚本版本和当前配置。先查 remoteRoot，再确认服务进程没有指向旧发布目录。

调试端口可以一直监听公网吗？

不建议。优先监听远程回环地址并通过 Remote-SSH 或受控隧道访问，完成调试后关闭端口；不要把调试协议直接当成普通业务端口暴露。