Docker Compose 本地開發工作流最佳化

為什麼用 Docker Compose 管理本地環境

本地開發環境一旦超過三個服務（前端、後端、資料庫），手動管理啟動順序和環境變數就會變得痛苦。Docker Compose 讓你用一個 YAML 聲明所有服務，並透過 docker compose up 一鍵啟動。

基本結構

# docker-compose.dev.yml
services:
  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: myapp
      POSTGRES_USER: myapp
      POSTGRES_PASSWORD: secret
    ports:
      - "5432:5432"
    volumes:
      - pg_data:/var/lib/postgresql/data

  api:
    build:
      context: ./apps/api
      dockerfile: Dockerfile.dev
    depends_on:
      - db
    environment:
      DATABASE_URL: postgresql://myapp:secret@db:5432/myapp
    volumes:
      - ./apps/api:/app
    ports:
      - "3000:3000"
    command: npm run dev

  python-service:
    build:
      context: ./apps/python-service
    depends_on:
      - db
    volumes:
      - ./apps/python-service:/app
    ports:
      - "8000:8000"
    command: uvicorn app.main:app --reload --host 0.0.0.0

volumes:
  pg_data:

關鍵技巧

1. 健康檢查 (healthcheck)

避免應用在資料庫就緒前啟動：

db:
  image: postgres:16-alpine
  healthcheck:
    test: ["CMD-SHELL", "pg_isready -U myapp"]
    interval: 5s
    timeout: 5s
    retries: 5

api:
  depends_on:
    db:
      condition: service_healthy

2. 熱重載 Volume 掛載

開發用 Dockerfile 安裝依賴後，透過 volume 掛載源碼讓熱重載生效。但要注意把 node_modules 排除在外：

volumes:
  - ./apps/api:/app
  - /app/node_modules  # 匿名 volume 保護 node_modules

3. 環境變數集中管理

用 .env 搭配 env_file 指令，避免 secrets 散落各 Compose 檔案：

api:
  env_file:
    - .env

常用指令

# 啟動所有服務（背景）
docker compose -f docker-compose.dev.yml up -d

# 只重建特定服務
docker compose -f docker-compose.dev.yml up --build api

# 查看日誌
docker compose logs -f api

# 進入容器 shell
docker compose exec api sh

結語

一個設計良好的 docker-compose.dev.yml 讓新人 onboarding 從「花半天設定環境」縮短到「10 分鐘跑起來」。