devcontainer.json的service字段必须严格匹配docker-compose.yml中services下一级键名且区分大小写，否则fallback到本地构建；node须以pid 1前台监听0.0.0.0:9229，跨容器通信必须用服务名而非localhost。
devcontainer.json 的 service 字段必须严格匹配 docker-compose.yml 中 services 键名
VSCode 不解析 container_name、aliases 或 extends，只认 docker-compose.yml 里 services 下第一级键名，且大小写敏感。配错就 fallback 到本地构建，根本连不上你 docker-compose up 起来的容器。
常见错误现象：Building image… 卡住不 attach，或调试器提示“connection refused”——其实它压根没找对容器。
- 若
docker-compose.yml写的是services: api:，devcontainer.json就必须写"service": "api" - 写成
"service": "API"、"service": "backend"或漏写该字段，都会失败 - 如果
docker-compose.yml在子目录（如./infra/docker-compose.yml），devcontainer.json必须显式声明"dockerComposeFile": "./infra/docker-compose.yml" - 多服务场景下，
service只能填一个主服务名；数据库、Redis 等靠depends_on启动，不参与service字段配置
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"] - 验证方式：进容器执行
netstat -tuln | grep 9229，输出必须含0.0.0.0:9229，不是127.0.0.1:9229 -
package.json中脚本建议写死 host："debug": "node --inspect=0.0.0.0:9229 --enable-source-maps server.js"
pathMappings 必须精确一对一映射本地与容器路径
VSCode 断点靠源码路径严格匹配。容器里报错显示 /app/src/index.js:42，你就得告诉它“/app 对应我本地 ${workspaceFolder}”。少个斜杠、目录层级没对齐，断点直接灰掉。
- 先查容器内实际工作路径：
docker exec -it <container> pwd</container>，常见是/app或/workspace，不是/usr/src/app -
devcontainer.json中"workspaceFolder"值（如"/workspace"）要和pathMappings里的"remoteRoot"一致 - 推荐写死映射，别依赖自动推断：
"pathMappings": { "/workspace": "${workspaceFolder}" } - 检查容器内路径是否真实存在：比如挂载了
./src:/app/src，但代码里引用的是../lib，映射链就断了
服务间网络通不通，比调试器连不连得上更重要
本地 E2E 链路（前端 → 后端 API → 数据库 + Redis）调试失败，90% 是因为跨容器调用时用了 localhost，而不是 service 名，或者 pathMappings 错位导致源码找不到，而非调试器本身问题。
- 容器内访问其他服务必须用
docker-compose.yml中定义的service名（如http://db:5432），不能用localhost或127.0.0.1 - 前端调后端时，若前后端都在容器里，也要用服务名（如
http://api:3000），不是http://localhost:3000 - 检查
docker network inspect确认所有服务是否在同一个自定义网络里 - 调试时优先
docker exec -it api curl -v http://db:5432，确认网络层通了再查调试逻辑
路径映射错一位、service 名差一个字母、Node 监听绑错 host——这些地方不校验，其余配置全对也白搭。
