vscode调试docker compose多容器node微服务，核心卡点是服务间网络不可达、调试端口未暴露、pid 1非node进程；devcontainer.json的service名须严格匹配docker-compose.yml中services键名（区分大小写），跨容器通信必须用服务名而非localhost，launch.json中port需与宿主机映射端口一致，pathmappings必须精确一对一映射。
VSCode 调试 Docker Compose 编排的 Node.js 微服务链路，真正卡住你的不是 launch.json 写错，而是服务间网络不可达、调试端口没暴露、或 PID 1 不是 Node 进程——这三处一错，断点永远不命中，日志里也看不出明显报错。
devcontainer.json 里 service 名必须和 docker-compose.yml services 下一级键完全一致
VSCode 不解析 container_name 或 aliases，只认 services 下的原始键名，且严格区分大小写。
- 如果
docker-compose.yml写的是services: api:，devcontainer.json就必须写"service": "api"；写成"service": "API"或"service": "backend"都会 fallback 到本地构建，根本不会连上 compose 容器 - compose 文件若不在项目根目录（比如放在
./infra/docker-compose.yml），必须显式声明："dockerComposeFile": "./infra/docker-compose.yml"，否则 VSCode 默认只扫根目录 - 用了
profiles？Dev Containers 默认不加载。要么把目标服务配置“展开”进主文件，要么改用docker-compose --profile dev up手动启，再 Attach
Node 进程必须监听 0.0.0.0:9229，且 PID 1 必须是它自己
常见错误是启动命令 fork 后父进程退出，或者 shell 层没用 exec，导致 PID 1 是 /bin/sh 而不是 node，VSCode 会判定容器“未就绪”而放弃连接。
- Dockerfile 中避免
CMD ["npm", "run", "dev"]—— 某些 npm 版本会 fork 子进程后让父进程 exit - 改成
CMD ["sh", "-c", "exec npm run debug"]，并在package.json里加脚本："debug": "node --inspect=0.0.0.0:9229 server.js" - 验证方式：进容器执行
ps -o pid,comm -A | head -5，第一行 PID 应该对应node，不是sh - 确认监听地址：运行
netstat -tuln | grep 9229，输出必须含0.0.0.0:9229，不是127.0.0.1:9229
跨服务调用时 localhost 不指向其他容器，必须用服务名
VSCode 的 Dev Container 和你的 api、auth、db 容器同属一个 Docker 网络，但 localhost 在每个容器内都只指向自己——这是最常被忽略的网络陷阱。
- 在
api容器里调auth服务，URL 必须写http://auth:3001/xxx，不能写http://localhost:3001/xxx - 调试器 attach 时，
launch.json里的"address": "localhost"是对的——它指宿主机 localhost，但"port": 9229必须和docker-compose.yml中- "9229:9229"映射的宿主机端口一致 - 多个 Node 服务要分别调试，就得各自暴露不同端口（如 9229、9230），并分别配置
forwardPorts和launch.json条目
pathMappings 错一个字符，断点就失效
VSCode 断点依赖源码路径一对一映射。容器里报错显示 /app/src/server.js:12，你就得告诉 VSCode：“这个 /app 对应我本地的 ${workspaceFolder}”，差一个斜杠都不行。
- Dev Containers 模式下，默认挂载路径是
/workspace，但如果你在docker-compose.yml里写了volumes: - .:/app，那remoteRoot就得是/app，不是/workspace -
launch.json中不要依赖自动推导，手动写死："pathMappings": [{ "localRoot": "${workspaceFolder}/src", "remoteRoot": "/app/src" }] - 检查映射是否生效：在断点处触发后，打开 VSCode 的 Debug Console，输入
debugger;并单步，看当前文件路径是否匹配
微服务链路调试最难的不是配通一个服务，而是确保每个服务的网络可达性、调试端口真实暴露、以及路径映射完全对齐——这三个地方全对了，剩下的只是加断点的事。
