Docker中Nx Monorepo下NestJS应用VS Code调试断点失效问题

目标 #

尝试使用Visual Studio Code调试Docker容器中Nrwl Nx Monorepo架构下的两个NestJS应用（auth-gateway和notifications-gateway），实现调试器成功附加并触发断点。

环境配置 #

• 应用：两个NestJS服务（auth-gateway、notifications-gateway）
• 开发环境：Node.js、Docker、Nrwl Nx、NestJS、TypeScript、带Node.js调试器的VS Code
• 核心工具：通过docker-compose.yml中的nx serve命令运行应用；在Docker外执行nx serve auth-gateway和nx serve notifications-gateway可成功连接调试器

问题现象 #

本地非Docker环境调试正常，但应用运行在Docker容器中时，VS Code断点无法被识别。调试器可无错误附加，但断点不触发，容器日志显示：

auth-gateway-1           | Debugger listening on ws://localhost:9229/4505cf30-66c7-40a8-8f6f-efed38504da6
auth-gateway-1           | For help, see: https://nodejs.org/en/docs/inspector

已尝试措施 #

• Docker配置：在docker-compose.yml中映射调试端口，确保各服务启动命令正确
• VS Code调试配置：配置launch.json以附加到正确端口，确保源映射处理正常
• TypeScript配置：调整tsconfig.json的module和moduleResolution等参数
• 命令调整：尝试直接使用node --inspect命令，后切换回在Docker外有效的nx serve命令
• 本地验证：确认非Docker环境调试正常，定位问题为Docker环境特有
• 错误处理：解决了moduleResolution配置不匹配导致的TypeScript编译错误

复现步骤 #

1. 克隆仓库：https://github.com/vdiaz1130/docker-debug
2. 执行pnpm install
3. 确保Docker已安装并运行
4. 执行docker compose up --watch
5. 在VS Code中打开调试器并尝试连接

需求 #

1. 如何调整Docker或VS Code配置，确保Docker中NestJS应用的断点能被识别？
2. 是否存在特定的Docker或VS Code设置会影响TypeScript应用调试？如有可行的解决方法？
3. 寻求Docker配置或VS Code设置中可能缺失/错误的点，以及Nrwl Nx命令与Docker配合调试的优化建议，是否需要更换编辑器？

解决方案 #

1. 核心配置调整（解决断点不触发问题） #

Docker Compose配置修正

• 调试端口绑定：容器内Node调试器默认监听localhost，外部VS Code无法访问，需修改启动命令让调试器监听0.0.0.0。同时确保端口映射正确：

  services:
    auth-gateway:
      ports:
        - "3333:3333"
        - "9229:9229"
      command: ["pnpm", "nx", "serve", "auth-gateway", "--inspect=0.0.0.0:9229"]
    notifications-gateway:
      ports:
        - "3334:3334"
        - "9230:9230"
      command: ["pnpm", "nx", "serve", "notifications-gateway", "--inspect=0.0.0.0:9230"]
  

• 源码路径对齐：挂载本地源码目录到容器内对应路径，保证容器内源码结构与本地一致：

  volumes:
    - ./:/app
  

VS Code Launch配置优化

在.vscode/launch.json中添加附加调试配置，明确localRoot（本地源码路径）和remoteRoot（容器内源码路径），确保源映射能正确关联：

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "attach",
      "name": "Attach to Auth Gateway (Docker)",
      "port": 9229,
      "localRoot": "${workspaceFolder}/apps/auth-gateway",
      "remoteRoot": "/app/apps/auth-gateway",
      "sourceMaps": true,
      "skipFiles": ["<node_internals>/**"]
    },
    {
      "type": "node",
      "request": "attach",
      "name": "Attach to Notifications Gateway (Docker)",
      "port": 9230,
      "localRoot": "${workspaceFolder}/apps/notifications-gateway",
      "remoteRoot": "/app/apps/notifications-gateway",
      "sourceMaps": true,
      "skipFiles": ["<node_internals>/**"]
    }
  ]
}

TypeScript源映射确认

确保应用的tsconfig.json开启源映射，且输出路径配置正确：

{
  "compilerOptions": {
    "sourceMap": true,
    "outDir": "../../dist/out-tsc",
    "rootDir": "."
  }
}

2. 影响TypeScript调试的关键设置及解决方法 #

• Docker端口监听限制：容器内调试器若仅监听localhost，外部无法连接，必须显式指定--inspect=0.0.0.0:<port>。
• 源映射路径不匹配：本地与容器内源码路径不一致会导致VS Code无法映射编译后的代码到本地源码，通过localRoot和remoteRoot参数对齐路径即可解决。
• Nx Serve默认行为：默认nx serve可能未开启调试或仅监听localhost，需手动添加调试参数。

3. 优化建议 #

• 为每个服务分配独立的调试端口，避免端口冲突（如auth用9229，notifications用9230）。
• 在docker-compose.yml中添加环境变量NODE_ENV=development，确保Nx以开发模式运行，生成完整的源映射：

  environment:
    - NODE_ENV=development
  

• 若使用pnpm，可挂载本地node_modules到容器内，避免重复安装依赖：

  volumes:
    - ./:/app
    - ./node_modules:/app/node_modules
  

• 无需更换编辑器，VS Code对Node.js+Docker的调试支持成熟，核心是路径和端口配置对齐。

内容的提问来源于stack exchange，提问作者vdiaz1130