VSCode 配合 Docker Compose 实现多容器微服务一键运行

先说个观察：VSCode配合Docker Compose的确能做到一键启动多容器微服务，但所谓一键，只是把费力气的部分前置了。翻开无数踩坑贴，真正让人血压飙升的，从来不是命令行敲得不够快，而是容器之间连不上、某个服务怎么都启不动、端口映射写错了——这三个点但凡有一个没对齐，在VSCode里点十次"Docker: Compose Up"都白搭。

接下来逐一拆解，看看真正卡住的关键在哪里。

docker-compose.yml 必须显式声明自定义网络

默认的 bridge 网络下，容器之间只能靠 IP 地址通信。很多人以为写了 depends_on 就万事大吉，其实它只控制启动顺序，并不保证 MySQL 进程已经监听端口、Redis 已经 ready。VSCode 启动 Dev Container 的那一瞬间，如果 app 容器立刻去连 mysql:3306，大概率会撞见 Connection refused 的报错。

正确的做法是：

• 在 docker-compose.yml 的顶层加一个 networks 块。比如：

networks:
  app-net:
    driver: bridge
    ipam:
      config:
        - subnet: 172.20.0.0/16

• 涉及的所有服务（app、mysql、redis）都必须显式写上 networks: [app-net]。
• 不要图省事用 host 或内置 bridge，因为这两种网络不支持通过容器名自动解析。换句话说，它们无法让你用 mysql 这样的服务名当 host。

devcontainer.json 的 service 字段必须严格匹配 service 键名

这一步简单但容易忽视。VSCode 读取 devcontainer.json 后，会把 service 字段的值当作容器名去匹配 docker-compose.yml 里的 services 键。哪怕只写错一个字母，就会弹出 Service 'xxx' not found。

• devcontainer.json 里写 "service": "app"，那么 docker-compose.yml 里必须有 services: { app: { ... } }。
• 如果 Compose 文件放在 .devcontainer/docker-compose.yml，记得在 devcontainer.json 里配 "dockerComposeFile": "docker-compose.yml"（路径相对于 .devcontainer/ 目录）。
• workspaceFolder 的路径必须和 volume 挂载路径一致。比如 volumes: ["../src:/workspace/src"]，那么 workspaceFolder 就应该是 /workspace。

MySQL 和 Redis 必须加 healthcheck 与密码验证

这是很多人会踩的一个坑。VSCode 启动 Dev Container 时，只检查容器状态是否变成 running，它不会等 MySQL 初始化完表结构，也不会等 Redis 加载完配置。哪怕 depends_on 生效了，你的应用代码第一次连上去仍然可能失败。

• 给 MySQL 加上 healthcheck：

healthcheck:
  test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-u", "root", "-p$$MYSQL_ROOT_PASSWORD"]
  timeout: 20s
  retries: 10

• 给 Redis 加上 command 显式启用密码：

command: redis-server --requirepass $$REDIS_PASSWORD

• ports 字段只用于主机访问（比如本地用 DBea ver 来连接），容器间通信必须用服务名加默认端口（mysql:3306、redis:6379）。

应用层仍需重试逻辑，不能全依赖 Compose

这一点容易被忽略，但恰恰是最关键的。VSCode Dev Containers 不会等 healthcheck 成功才让 app 容器启动。它只看 Docker 返回的 running 状态。换句话说，healthcheck 是为你自己排查准备的，不是给 VSCode 用的。

• 应用代码里必须实现数据库连接重试。比如 Node.js 项目用 mysql2 时，要配置 connectTimeout 和 acquireTimeout，或者直接手动轮询。
• 另一个方法是在 devcontainer.json 的 postCreateCommand 里写一段 shell 脚本，循环检查 mysqladmin ping 成功之后再启动主进程。
• 不要指望 depends_on + healthcheck 的组合就能让应用一上来就稳连。Docker 层面的依赖，不等于应用层面的就绪。