VS Code调试Docker容器内Node.js应用断点不命中问题

你的配置存在3个核心错误，直接导致连接失败、断点无法命中：

• launch.json 缺少容器内源码路径映射配置，VS Code无法将本地/当前工作区打开的源码文件和容器内实际运行的JS文件做路径匹配，即使调试器成功连接，也找不到对应源码位置，断点自然无法绑定。
• PM2 开启cluster_mode时，硬编码--inspect=0.0.0.0:9331参数只会让PM2主进程监听9331端口，真正执行业务逻辑的fork子进程（worker）会因为端口冲突无法启动调试服务，就算启动成功也会自动切换到其他端口，你的调试配置连接的是不运行业务代码的主进程，不可能命中业务断点。
• Docker仅映射单个9331端口，集群模式下多个worker会占用多个连续调试端口，单端口映射无法满足多实例调试需求。

第一步：调整PM2启动配置 #

集群模式下不要给所有实例硬编码同一个调试端口，让PM2自动为每个worker分配递增的调试端口即可。
如果使用ecosystem.config.js配置PM2，参考如下配置：

module.exports = {
  apps: [{
    name: "api",
    script: "./src/server.js",
    cwd: "/api",
    instances: 2, // 按实际需求配置集群实例数
    exec_mode: "cluster",
    // 仅绑定监听地址，不指定固定端口，PM2会从9229开始为每个实例分配递增端口
    node_args: "--inspect=0.0.0.0",
    merge_logs: true
  }]
}

如果用命令行直接启动，参数调整为：

pm2 start /api/src/server.js -i 2 --node-args="--inspect=0.0.0.0"

配置完成后重启PM2，进入容器执行ss -tulpn | grep node，可以看到每个worker进程分别监听9229、9230等连续端口。

第二步：调整Docker端口映射（仅本地远程调试场景需要） #

如果你是在宿主机打开源码、通过端口映射远程连接容器调试，需要把单端口9331的映射替换为连续端口段映射，覆盖你配置的集群实例数量，比如开2个实例就映射9229-9230端口：

# 启动容器时添加端口映射参数
-p 9229-9230:9229-9230

如果你已经通过VS Code的「Attach To Running Container」功能附加到容器，并且直接在容器内打开/api作为工作区，不需要配置端口映射，VS Code会自动处理容器内端口转发。

第三步：修正launch.json配置 #

补全路径映射配置，参考如下正确配置：

{
  "configurations": [
    {
      "name": "Attach to Node in Container",
      "port": 9229, // 要调试哪个worker就填对应端口，第一个实例默认是9229
      "request": "attach",
      "skipFiles": ["<node_internals>/**"],
      "type": "node",
      // 容器内打开工作区的场景，两个root都填${workspaceFolder}即可
      "localRoot": "${workspaceFolder}",
      "remoteRoot": "/api",
      // 本地远程调试场景下，localRoot填本地项目根目录绝对路径，remoteRoot固定填/api
      "restart": true,
      "timeout": 120000,
      "sourceMaps": true,
      "continueOnAttach": true
    }
  ]
}

注意路径映射层级必须完全匹配：你本地/工作区打开的项目根目录，要和容器内/api目录的结构完全对应——比如根目录下直接存在src/server.js文件，多一层或少一层目录都会导致断点变灰无法命中。

第四步：验证调试 #

1. 重启PM2所有进程，在容器内执行curl http://127.0.0.1:9229/json/version，如果返回带Node.js版本号的JSON，说明调试端口正常监听。
2. 回到VS Code调试面板，选择刚才修改的Attach配置启动调试。
3. 在业务代码行打红点断点，发起对应请求即可正常命中。

• 不建议在集群模式下使用--inspect-brk参数，该参数会让worker启动时卡在第一行等待调试连接，如果没有提前启动调试附加，服务会一直卡住无法对外提供服务。
• 如果集群模式下硬编码同一个调试端口，只有第一个worker能成功绑定调试端口，其余worker会抛出端口占用错误，导致服务启动异常。
• 如果断点始终显示为未绑定的灰色空心圆，优先检查路径映射是否正确，90%以上的断点不命中问题都是路径层级不匹配导致的。

内容的提问来源于stack exchange，提问作者d-_-b