Docker Compose 本地开发环境：从“能跑”到“好用”的五条实践

很多团队的本地开发环境都停留在“能跑就行”的阶段：新同事入职先花半天装数据库、配缓存、改一堆本地配置，换一台电脑又要重来一遍。Docker Compose 本来就是为了解决这个问题而生的，但如果只把它当成启动几个容器的工具，就浪费了它大半的价值。下面五条实践，都是我在日常开发里反复验证过、能直接让本地环境好用一个档次的做法。

一、一个命令拉起整套依赖

本地环境的第一个目标，是让“从零到能跑”变成一条命令。把应用、数据库、缓存、消息队列都写进同一个 compose.yaml，新人只需要 docker compose up -d 就能开始写代码，而不是先读三页环境搭建文档。

services:
  app:
    build: .
    ports:
      - "8080:8080"
    depends_on:
      db:
        condition: service_healthy
  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: dev-only-password

关键在于 depends_on 配合健康检查，而不是让应用启动后自己去重试连库。环境文件用一个提交进仓库的 .env.example 做模板，真实的 .env 永远不要进版本库。

二、把代码目录和数据卷分清楚

本地开发最常见的两个坑，都和挂载有关。第一是把代码目录挂载进容器后，容器内的依赖目录被宿主机空目录覆盖，导致启动就报错；第二是数据库数据没有持久化，容器一删数据全丢。

正确的做法是分开处理：代码用绑定挂载实现热更新，依赖目录用匿名卷挡住，数据库用命名卷持久化。

services:
  app:
    volumes:
      - .:/app
      - /app/node_modules
  db:
    volumes:
      - pgdata:/var/lib/postgresql/data
volumes:
  pgdata:

- /app/node_modules 这一行看起来奇怪，却是关键：它让容器内的依赖目录不被宿主机的挂载覆盖。数据卷起个有意义的名字，清理时也知道自己在删什么。

三、用健康检查代替 sleep 等待

不少启动脚本里藏着 sleep 10 这样的写法：等数据库“大概”启动好了再启动应用。机器快的时候白白浪费十秒，机器慢的时候十秒根本不够，失败还查不出原因。

给每个有依赖关系的服务加上健康检查，让 Compose 自己判断什么时候可以继续：

services:
  db:
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 3s
      retries: 10

这样启动顺序由真实状态驱动，而不是靠猜时间。排障时 docker compose ps 一眼就能看到哪个服务不健康，再用 docker compose logs db 看具体原因，比对着 sleep 猜要可靠得多。

四、环境变量分层：默认值进仓库，密钥放本地

环境变量的管理原则是：能进仓库的只放默认值，凡是密钥、令牌一律只存在本地。Compose 支持多层覆盖，compose.yaml 里写开发默认值，需要覆盖时再用 compose.override.yaml 或者本地 .env，后者不要提交。

docker compose -f compose.yaml -f compose.override.yaml up -d

另外注意一个细节：不要在 compose 文件里写死宿主机的绝对路径和个人用户名，这会让文件在别人的机器上直接失效。路径用相对路径，端口用变量，默认值写在文件里，个性化配置留给本地覆盖。

五、给常用操作起短名字

docker compose down -v、docker compose logs -f app 这些命令每天要敲很多次，记全了也不轻松。可以在项目里放一个简单的 Makefile 或者 shell 脚本，把高频操作收敛成 make up、make logs、make reset。

up:
	docker compose up -d --build
logs:
	docker compose logs -f app
reset:
	docker compose down -v
	docker compose up -d

reset 尤其有用：数据库被脏数据搞乱时，一条命令就能回到干净状态，而且因为数据卷是命名卷，删之前心里也有数。团队统一用同一套短命令，新人也不用再问“清理环境该敲什么”。

结语

Docker Compose 的价值不在于启动了几个容器，而在于把“本地环境”变成一份可版本化、可复现、可分享的配置。做到一键拉起、卷挂载分明、健康检查驱动、变量分层、操作收敛这五点之后，本地环境就不再是每个人的私人手艺，而是团队共享的基础设施。环境问题少了，写代码的时间自然就多了。