能跑通，但关键不在“怎么连”，而在“哪一环先断”：90%的VSCode+Docker Compose E2E调试失败源于服务间网络不通（跨容器须用service名而非localhost）或路径映射错位（pathMappings必须严格一对一），而非调试器连接问题。
能跑通，但关键不在“怎么连”，而在“哪一环先断”。本地 E2E 链路（比如前端调后端 API，后端连数据库+Redis）在 VSCode + Docker Compose 下调试失败，90% 是因为服务间网络不通或路径映射错位，不是调试器没连上。
docker-compose.yml 里 service 名和 devcontainer.json 必须严格对齐
VSCode 的 Dev Containers 不认 container_name，只认 service 名。你写 services: api:，devcontainer.json 里就得是 "service": "api"；写成 "service": "backend" 或漏写，VSCode 就找不到主容器，后续所有调试、挂载、端口转发全失效。
-
docker-compose.yml中定义的 service 名（如api、web、db）是唯一标识，不能带下划线或大写字母（Docker Compose 规范要求小写+短横线） -
devcontainer.json中的"service"字段必须一字不差匹配，大小写敏感 - 如果用了多文件 compose（比如
docker-compose.prod.yml），devcontainer.json中"dockerComposeFile"要写全路径，例如"dockerComposeFile": ["docker-compose.yml", "docker-compose.debug.yml"]
Node 进程必须监听 0.0.0.0，不是 127.0.0.1
容器内 Node 启动时用 --inspect=127.0.0.1:9229 或默认不指定 host，VSCode 就连不上——因为 127.0.0.1 在容器里指向它自己，而 VSCode 是从宿主机发请求，走的是 Docker 网络桥接层。
- 启动命令必须显式写
--inspect=0.0.0.0:9229，不能只写--inspect=9229（Node 默认绑定 127.0.0.1） -
package.json中脚本示例："debug": "node --inspect=0.0.0.0:9229 --enable-source-maps server.js" - 验证方式：进容器执行
netstat -tuln | grep 9229，输出里必须含0.0.0.0:9229，不是127.0.0.1:9229
pathMappings 错一个字符，断点就永远不命中
VSCode 断点靠源码路径一对一映射。容器里报错显示 /app/src/index.js:42，你就得告诉它“/app 对应我本地 ${workspaceFolder}”，少个斜杠、多层目录没对齐，断点直接灰掉。
- 检查容器内实际工作路径：
docker exec -it <container> pwd，常见是/app或/workspace，不是/usr/src/app -
devcontainer.json中"workspaceFolder"值（如"/workspace"）要和pathMappings里的"remoteRoot"一致 - 推荐写死映射，别依赖自动推断：
"pathMappings": [{ "localRoot": "${workspaceFolder}", "remoteRoot": "/workspace" }] - 如果项目结构是
src/在子目录，"remoteRoot"应设为/workspace/src，对应"localRoot": "${workspaceFolder}/src"
E2E 链路里跨服务调用必须用 service 名，不是 localhost
前端容器里 fetch http://localhost:3000/api 肯定失败——localhost 指向它自己，不是后端服务。Docker Compose 内部网络靠 service 名解析 DNS，这是最常被忽略的 E2E 卡点。
- 前端代码中 API 地址必须写成
http://api:3000（假设后端 service 名是api），而不是http://localhost:3000 - 环境变量统一注入：在
docker-compose.yml的前端 service 下加environment: - API_URL=http://api:3000 - 浏览器访问前端时，走的是宿主机
localhost:8080→ 前端容器 → 容器内 DNS 解析api→ 后端容器，全程不经过宿主机网络栈
真正卡住的往往不是调试器连不上，而是前端发请求根本没发出去，或者后端连不上 Redis/DB——这些都发生在容器网络内部，跟 VSCode 无关。先确认 docker-compose logs -f api 里有没有连接拒绝错误，再查 VSCode 调试配置。
