用 Docker Compose 十分钟搭好一套本地开发环境

很多项目在本地跑不起来，问题往往不在代码，而在环境：数据库大版本不一致、Redis 忘了装、依赖服务启动顺序不对，同事机器上能跑、换台电脑就报错。Docker Compose 的价值，是把这套环境写成一份声明式配置，用一条命令拉起全部依赖。

一、为什么不用一堆 docker run

用 docker run 逐个启动服务，命令又长又容易漏参数，换台机器还得重新敲一遍。Compose 把这些参数固化到 docker-compose.yml 里，配置即文档，团队成员 clone 下来就能复现同一套环境。

二、一份最小可用的配置

以一个 Web 应用加 PostgreSQL、Redis 为例，核心片段如下：

services:

  app:

    build: .

    ports:

      - "8080:8080"

    environment:

      - DATABASE_URL=postgres://dev:dev@db:5432/appdb

      - REDIS_ADDR=redis:6379

    depends_on:

      db:

        condition: service_healthy

  db:

    image: postgres:16-alpine

    environment:

      - POSTGRES_USER=dev

      - POSTGRES_PASSWORD=dev

      - POSTGRES_DB=appdb

    volumes:

      - pgdata:/var/lib/postgresql/data

    healthcheck:

      test: ["CMD-SHELL", "pg_isready -U dev -d appdb"]

      interval: 5s

      retries: 10

  redis:

    image: redis:7-alpine

    ports:

      - "6379:6379"

volumes:

  pgdata:

三、几个容易忽略的关键点

第一，容器之间用服务名通信。配置里连数据库写的是 db 而不是 localhost，因为每个容器都有自己的网络命名空间，localhost 指向容器自身。

第二，给数据库加 healthcheck。容器启动不等于服务可用，PostgreSQL 初始化需要几秒。配合 depends_on 的 service_healthy 条件，可以避免应用启动时连不上数据库而反复崩溃。

第三，数据必须落到命名卷。把数据目录挂到 pgdata 卷上，执行 docker compose down 不会丢数据，只有加 -v 参数才会连卷一起删除。

第四，环境变量不要写死。生产环境可以用 env_file 指定 .env 文件，并把 .env 加入 .gitignore，避免密码进入版本库。

四、日常命令

docker compose up -d 后台启动全部服务；docker compose ps 查看状态；docker compose logs -f app 跟踪某个服务日志；docker compose exec app sh 进入容器排查；docker compose down 停止并清理容器网络。

五、三个常见坑

端口冲突：宿主机 8080 被占用时，改成 "8081:8080"，容器内部端口不用动。

构建缓存导致改动不生效：Dockerfile 里先拷贝依赖清单再拷贝源码，能最大化利用缓存；如果确实需要全量重建，用 docker compose build --no-cache。

镜像体积过大：优先选择 alpine 或 slim 基础镜像，多阶段构建只把产物复制到运行镜像，能显著减小体积和拉取时间。

六、小结

Compose 并不复杂，真正省时间的是它带来的确定性：环境可复现、依赖可声明、启动顺序可控。把这份配置纳入版本管理，新同事入职时不用再花半天配环境，一条 up 命令就能开始写业务代码。