用 Docker Compose 管住本地开发依赖：一个最小可用的实例

为什么要用 Compose 管本地依赖

本地开发最烦的不是写业务代码，而是"我的电脑上到底装了什么"。PostgreSQL 装成 14 还是 16、Redis 有没有开持久化、同事的机器上能跑而我的报端口占用——这些问题靠一份 README 是说不清的。

Docker Compose 的价值就在于把这些依赖写成声明式配置：一条 `docker compose up -d` 起来，一条 `docker compose down -v` 清干净，任何人 clone 仓库后行为一致。

一个最小可用的 compose.yaml

假设我们有一个 Python 服务，依赖 PostgreSQL 和一个 Redis 做缓存：

services:
  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: dev
      POSTGRES_PASSWORD: devpass
      POSTGRES_DB: app
    ports:
      - "5432:5432"
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U dev -d app"]
      interval: 5s
      retries: 10

  cache:
    image: redis:7-alpine
    command: ["redis-server", "--appendonly", "yes"]
    ports:
      - "6379:6379"

  api:
    build: .
    environment:
      DATABASE_URL: postgresql://dev:devpass@db:5432/app
      REDIS_URL: redis://cache:6379/0
    depends_on:
      db:
        condition: service_healthy
    ports:
      - "8000:8000"

volumes:
  pgdata:

几个容易踩的点：

1. **`depends_on` 默认只等容器启动，不等服务可用**。要等数据库真的能连，必须配合 `healthcheck` \+ `condition: service_healthy`，否则第一次启动时应用会因为连不上库直接退出。 2. **`localhost` 在容器里指向容器自己**。连接串里必须写服务名 `db`、`cache`，这是新手最常见的报错来源。 3. **端口映射写 `"5432:5432"` 而不是 `5432`**，只写一个数字会随机映射到宿主机端口，本地客户端就连不上了。 4. **数据要放 named volume**。不挂 volume 的话，`down` 之后数据全丢，调试时容易误判是代码问题。

日常怎么用

# 起依赖，不动本地 Python，方便在 IDE 里打断点
docker compose up -d db cache

# 只看某一个服务的日志
docker compose logs -f api

# 改了 Dockerfile 之后重建
docker compose up -d --build api

# 彻底清理，包括数据卷
docker compose down -v

我最常用的其实是第一条：数据库和缓存放容器里，业务代码留在宿主机跑。这样既有环境隔离，又能保留 IDE 的热重载和断点调试，比整套服务都塞进容器舒服得多。

小结

Compose 不是"上生产"的工具，它解决的是**开发环境的可复现性**。把依赖版本、初始化参数、健康检查都写进 `compose.yaml`，团队里"我这跑不起来"的对话会少一大半。