根本原因是VSCode只等待容器状态为running，不等待健康检查通过；需为MySQL/Redis配置真实业务就绪的healthcheck，Node服务健康检查须验证DB/Redis连接，service名、端口、PID1等必须严格对齐。
VSCode Dev Container 启动时 Node 服务连不上 MySQL/Redis
根本原因不是网络不通，而是 VSCode 只等容器状态变成 running，不等健康检查通过。Node 进程一启动就立刻去连 mysql:3306，但此时 MySQL 还在初始化表结构，Connection refused 就必然发生。
- 必须给所有依赖服务（
mysql、redis）加healthcheck，且test命令要真实验证业务就绪（比如mysqladmin ping -h localhost -u root -p$MYSQL_ROOT_PASSWORD） -
start_period至少设为 40s：MySQL 容器冷启动时初始化可能耗时 20–30 秒，留足缓冲 -
interval别设太短——设成10s没问题，但若配成2s，MySQL 未响应时会快速刷满日志，还可能触发 Docker 的重试限流 - Node 应用代码里别硬写
localhost：它在容器内指向自己，要用mysql这个 service 名
Node 容器本身健康检查总失败或延迟标记 healthy
常见于 Express/Koa 服务监听了端口但还没完成中间件加载、数据库连接池建立等初始化动作。健康检查命令返回 0 太早，VSCode 就认为“已就绪”，结果调试器 attach 上去后请求直接 500。
- 健康检查
test必须走业务接口，不是只curl -f http://localhost:3000：加一个/health路由，里面显式检查 DB 连接、Redis ping、必要配置加载完成 -
timeout至少设为5s：Node 启动时首次请求可能因模块加载慢而超时，3s容易误判 - 别依赖
depends_on+healthcheck自动等待：Docker Compose 不会自动阻塞下游服务启动，得靠应用层重试或启动脚本轮询 - VSCode 的 Dev Container 不读取
depends_on的condition: service_healthy，它只管自己的service容器是否 running
devcontainer.json 里 service 名和 docker-compose.yml 对不上
VSCode 报错 Service 'app' not found 或静默 fallback 到本地构建，90% 是大小写或拼写不一致。它不解析 container_name，只认 services 下第一级 key。
- 检查
docker-compose.yml顶层services:下的键名，比如是backend:还是node-app:，然后严格复制到devcontainer.json的"service"字段 - compose 文件若放在
.devcontainer/docker-compose.yml，devcontainer.json中必须写"dockerComposeFile": "docker-compose.yml"（路径相对于.devcontainer/） - 如果用了 profile（如
docker-compose --profile dev up），Dev Containers 默认不加载 profile，得把目标服务配置“展开”到主 compose 文件里
Node 调试器连不上或断点不命中
不是端口没暴露，而是 PID 1 不是 Node 进程本身，或者 --inspect 参数被 shell 层吞掉。
- Dockerfile 中避免
CMD ["npm", "run", "dev"]：某些 npm 版本 fork 子进程后让父进程 exit，导致 PID 1 是短命 shell。改用CMD ["sh", "-c", "exec npm run dev"] -
--inspect=0.0.0.0:9229必须出现在最终执行命令里，且不能被包裹在未加exec的 shell 中；VSCode 的 attach 配置里port要和容器内监听端口一致 - 确认
forwardPorts包含9229，且app容器的ports段没写错（应为- "9229:9229"或干脆不写——Dev Containers 会自动处理） - Node 版本 ≥ 14 时，
node --inspect=0.0.0.0:9229 app.js才真正绑定所有网卡；旧版本默认只绑127.0.0.1，容器内无法被 VSCode 访问
VSCode 和 Docker Compose 的协同边界很窄：它不管健康状态流转，不解析 depends_on condition，也不等 service_healthy。所有“同步”都得靠显式配置对齐——network、healthcheck、service 名、PID 1、端口映射，漏掉任何一环，就只能看到容器 running 但服务不可用。
