用 Docker Compose 固化本地开发环境：一份可提交、可复现的编排文件

先说结论

把本地依赖从「口口相传的操作步骤」变成一份能提交进仓库的编排文件，是消除「我这里能跑、你那里跑不起来」成本最低的办法。下面用一个 Node 服务 + PostgreSQL + Redis 的最小组合，讲讲实践中真正影响体验的几个细节。

一、镜像别写 latest

postgres:16.3-alpine 比 postgres:latest 稳得多。写死小版本，半年后同事拉下来的还是同一个镜像；写 latest，上游某天发个版，所有人的本地环境同时变脸，而且没人知道为什么昨天还好的代码今天挂了。

二、depends_on 要配 healthcheck

只写 depends_on 只保证容器「启动了」，不保证数据库「能接受连接」。PostgreSQL 初始化数据目录的那几秒，应用已经在疯狂重连。加上 healthcheck，并用 condition: service_healthy，才真正解决启动顺序问题。

一个能直接用的骨架长这样：

services:
  db:
    image: postgres:16.3-alpine
    environment:
      POSTGRES_PASSWORD: ${DB_PASSWORD:?need DB_PASSWORD}
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      retries: 10

  app:
    build: .
    depends_on:
      db:
        condition: service_healthy
    ports:
      - "3000:3000"

volumes:
  pgdata:

三、数据卷用具名卷

匿名卷在 compose down 之后容易变成孤儿，down -v 又会把同事三个月的数据一起清掉。具名卷至少在 docker volume ls 里一眼能认出来，删的时候要打全名，多一道心理防线。

四、密码走 .env，不要硬编码

变量写成 ${DB_PASSWORD:?need DB_PASSWORD}，缺变量时 compose 会直接报错退出，比默默起一个空密码的数据库安全得多。仓库里只留 .env.example，.env 进 .gitignore。

五、日常就这几条命令

只起依赖、应用在宿主机跑：docker compose up -d db cache；全量起：docker compose up -d --build；看日志：docker compose logs -f app；彻底重置：docker compose down -v（会删卷，谨慎）。

项目里还有只在特定场景用的服务，比如一次性跑数据迁移、本地 mailhog，可以用 profiles 把它们隔离，默认不启动，需要时 docker compose --profile mail up -d 再拉起来。一份文件同时服务日常开发和偶发需求，不至于越堆越长。

最后说一句

环境一致性的收益不在第一次跑通，而在于第 N 次新人入职、第 N 次切分支、第 N 次重装系统的时候——那时你只需要一条 up -d，而不是翻半年前的笔记。