devcontainer.json 的 service 字段必须严格匹配 docker-compose.yml 中 services 下第一级键名且区分大小写，否则会 fallback 到本地构建；node 进程须作为 pid 1 前台运行并监听 0.0.0.0:9229；sourcefilemap 路径映射必须精确一致，热重载与调试器机制独立。
devcontainer.json 的 service 字段必须严格匹配 docker-compose.yml 的 services 键名
VSCode 不解析 container_name、aliases 或 extends，只认 docker-compose.yml 中 services 下第一级键名，且区分大小写。比如你的 compose 文件写的是：
services:
api:
build: .
ports: ["3000:3000", "9229:9229"]
那 devcontainer.json 就必须写 "service": "api"；写成 "service": "API" 或 "service": "backend" 都会 fallback 到本地构建，而不是复用已启动的容器。
常见错误现象：VSCode 显示 “Building image…” 却迟迟不 attach，或调试器连不上——其实它根本没连到你 docker-compose up 起来的那个容器。
- 检查路径：若
docker-compose.yml在子目录（如./infra/docker-compose.yml），devcontainer.json必须显式声明"dockerComposeFile": "./infra/docker-compose.yml" - 多服务依赖时，
service只能填一个主服务名；数据库、Redis 等辅助服务靠depends_on保证启动顺序，无需也不应写进service - 使用 profiles 时 Dev Containers 默认不加载；得把目标服务配置“展开”到主 compose 文件里，或改用
docker-compose --profile dev up启动后再 Attach
Node 进程必须作为 PID 1 前台运行并监听 0.0.0.0:9229
VSCode 判断容器是否“就绪”，依据是 PID 1 是否持续运行且暴露调试端口。常见陷阱是启动命令 fork 后父进程退出，或未用 exec 导致 PID 1 停留在 shell 层。
错误写法：CMD ["npm", "run", "dev"] —— 某些 npm 版本会 fork 子进程后让父进程 exit，VSCode 看不到真正的 Node 进程。
正确写法（推荐）：CMD ["sh", "-c", "exec npm run dev -- --inspect=0.0.0.0:9229"]
- 务必带
=0.0.0.0:9229，漏掉0.0.0.0就只监听127.0.0.1，外部连不上 - 进容器验证：
netstat -tuln | grep 9229输出必须含0.0.0.0:9229，不是127.0.0.1:9229 -
docker-compose.yml中对应服务必须加ports: ["9229:9229"]，否则宿主机无法转发调试请求
sourceFileMap 或 pathMappings 写错，断点永远不命中
VSCode 断点依赖源码路径一对一映射。容器里报错显示 /app/server.js:12，你就得告诉 VSCode：“这个 /app 对应我本地的 ${workspaceFolder}”。差一个字符都不行。
Dev Containers 模式下，devcontainer.json 默认已将工作区挂载为 /workspace，但如果你在 docker-compose.yml 里用了 volumes: ["./src:/app"]，那实际路径就是 /app，不是 /workspace。
- 别信
type: "docker"自动识别——它常把remoteRoot错判成/workspace，手动写死"remoteRoot": "/app"更安全 - launch.json 中
sourceFileMap示例：{"${workspaceFolder}": "/app"}，注意斜杠方向和结尾无/ - 热重载本身不依赖调试器，但断点失效会让你误以为热重载没生效；先确认断点能命中，再排查 nodemon 或 ts-node-watch 的 reload 行为
热重载需要 volume 挂载 + 工具链配合，不是开个 --inspect 就自动生效
单纯暴露 9229 端口只能调试，不能热重载。热重载本质是文件变更触发进程重启，这需要两层配合：宿主机代码实时同步进容器 + 容器内有监听文件变化的工具。
典型组合：volumes 挂载源码目录 + nodemon 或 ts-node-dev 监听 .ts/.js 变更。
-
docker-compose.yml中必须声明volumes: ["${PWD}/src:/app/src"]（注意路径映射与remoteRoot一致） - package.json 的
dev脚本应包含--watch或交由nodemon托管，例如："dev": "nodemon --watch src --exec ts-node src/index.ts" - 避免在 Dockerfile 中 COPY 整个项目——那样热重载失效；volume 挂载优先级高于 COPY，但前提是挂载路径与应用读取路径一致
最易被忽略的一点：热重载和调试器是两个独立机制。你可能看到终端里 nodemon 重启了，但 VSCode 断点仍不触发——这时候问题大概率出在 sourceFileMap 路径映射上，而不是热重载本身。
