基本规则

• 文件格式：YAML 格式，严格缩进（使用空格，不可用 Tab）。
• 版本声明：旧版本需在文件开头指定 version（如 version: "3.8"），新版本（Compose V2+）无需指定，直接使用 services 和 networks 等字段。
• 服务定义：每个服务对应一个容器，通过 services 块定义。
• 键值语法：键值对、列表、嵌套结构均可使用。

2. 核心配置项

2.1 服务（Services）

services:
  web:  # 服务名称（自定义）
    build: .  # 指定 Dockerfile 路径（自动构建镜像）
    image: myapp:latest  # 直接使用预构建的镜像（与 build 二选一）
    ports:
      - "8000:8000"  # 端口映射 [宿主机端口:容器端口]
    environment:
      - DEBUG=1  # 环境变量
      - DB_HOST=db
    env_file:
      - .env  # 从文件加载环境变量
    volumes:
      - ./app:/code  # 挂载宿主机目录到容器 [宿主机目录:容器目录]
      - logs:/var/log  # 使用命名卷
    depends_on:
      - db  # 依赖的服务（控制启动顺序）
    networks:
      - backend  # 指定网络
    restart: unless-stopped  # 重启策略
    healthcheck:  # 健康检查
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 30s
      timeout: 10s
      retries: 3

  db:
    image: postgres:15
    environment:
      POSTGRES_PASSWORD: mysecretpassword
    volumes:
      - pgdata:/var/lib/postgresql/data  # 持久化数据库数据
    networks:
      - backend

2.2 网络（Networks）

networks:
  backend:  # 自定义网络名
    driver: bridge  # 网络驱动类型（默认 bridge）
    # 高级配置（如自定义子网）
    # ipam:
    #   config:
    #     - subnet: 172.28.0.0/16

2.3 卷（Volumes）

volumes:
  pgdata:  # 命名卷（Docker 自动管理）
    driver: local
  # 自定义卷路径
  # logs:
  #   driver: local
  #   driver_opts:
  #     type: none
  #     o: bind
  #     device: ./logs

3. 常用配置示例

3.1 多服务协作（Web + Redis + DB）

services:
  web:
    build: .
    ports:
      - "8000:8000"
    depends_on:
      - redis
      - db
    networks:
      - backend

  redis:
    image: redis:7
    networks:
      - backend

  db:
    image: postgres:15
    environment:
      POSTGRES_PASSWORD: mysecretpassword
    volumes:
      - pgdata:/var/lib/postgresql/data
    networks:
      - backend

networks:
  backend:

volumes:
  pgdata:

3.2 开发环境配置（热更新）

services:
  web:
    build: .
    ports:
      - "3000:3000"
    volumes:
      - ./src:/app/src  # 代码目录挂载（实时同步修改）
    environment:
      - NODE_ENV=development
    command: npm run dev  # 启动开发服务器

4. 最佳实践

1. 避免使用 latest 标签：显式指定镜像版本（如 python:3.11-slim）。
2. 精简容器：每个服务只运行一个进程（如 Web 服务和 DB 分开）。
3. 利用 .env 文件：将敏感信息（如密码）存储在外部文件，不要硬编码。
   # .env 文件示例
DB_PASSWORD=mysecretpassword

# YAML 文件示例
environment: POSTGRES_PASSWORD: ${DB_PASSWORD}
4. 多阶段构建：在 docker-compose.yml 中结合多阶段 Dockerfile，减少生产镜像体积。
5. 网络隔离：为不同服务组分配独立网络（如 frontend 和 backend）。

5. 常用命令

6. 常见错误

• 缩进错误：YAML 必须使用空格（如 2 或 4 空格），不可用 Tab。
• 服务名称非法：仅允许小写字母、数字和下划线（如 web-service 非法）。
• 端口冲突：确保宿主机端口未被占用。
• 依赖顺序问题：depends_on 仅控制启动顺序，不保证服务可用性，需配合健康检查。