3.2 docker-compose.yml 文件详解

docker-compose.yml 是 Docker Compose 用于定义多容器应用的配置文件。理解其结构和各字段，有助于高效编排和管理复杂的多服务环境。

一、基本结构

version: '3.9'   # Compose 文件格式版本，推荐写明

services:        # 服务区块，每个服务相当于一个容器
  web:
    ...
  db:
    ...

networks:        # 可选，自定义网络
  mynet:
    driver: bridge

volumes:         # 可选，自定义数据卷
  dbdata:

• version：指定 Compose 文件格式（如 3、3.8、3.9 等）
• services：定义所有服务（每个服务对应一个容器）
• networks：自定义网络，服务之间通信/隔离
• volumes：自定义持久化卷

二、服务定义详解

每个 service 支持丰富的配置项，常见如下：

services:
  web:
    image: nginx:alpine          # 使用现成镜像
    build: .                     # 或用 build 构建镜像（下方可指定上下文、Dockerfile 等）
    container_name: my-web       # 容器名（可选，不建议大规模用）
    command: ["nginx", "-g", "daemon off;"]  # 启动命令
    environment:                 # 环境变量（等价于 ENV）
      - NGINX_PORT=80
    ports:                       # 端口映射（主机:容器）
      - "8080:80"
    volumes:                     # 挂载卷
      - ./conf/nginx.conf:/etc/nginx/nginx.conf:ro
      - webdata:/usr/share/nginx/html
    networks:
      - mynet
    depends_on:                  # 服务依赖，确保启动顺序
      - db
    restart: unless-stopped      # 容器重启策略
    healthcheck:                 # 健康检查机制
      test: ["CMD", "curl", "-f", "http://localhost/"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 10s

  db:
    image: mysql:8
    environment:
      MYSQL_ROOT_PASSWORD: example
    volumes:
      - dbdata:/var/lib/mysql

字段说明与补充

• image / build：二选一，image 指定已有镜像，build 指定构建上下文和 Dockerfile。
• container_name：手动指定容器名（不建议大规模用，易冲突）。
• command / entrypoint：覆盖默认启动命令。
• environment / env_file：注入环境变量，可配合 .env 文件。
• ports：端口映射，支持 “主机端口:容器端口”。
• volumes：数据挂载，本地路径/命名卷/只读等多种写法。
• depends_on：声明依赖关系，实现服务启动顺序（不等同于“完全可用”）。
• restart：
  • no（默认，不重启）
  • always（总是重启）
  • unless-stopped（除非手动停止）
  • on-failure[:max-retries]
• healthcheck：监控容器健康，影响 depends_on: condition 用法。
• networks：指定容器加入的网络。

三、多环境支持（.env 文件、环境变量注入）

1. .env 文件

• 与 docker-compose.yml 同目录下的 .env 文件会自动被识别，优先级高于 YAML 里的 environment 字段。

• 格式：

  MYSQL_ROOT_PASSWORD=example
  NGINX_PORT=80
  

• 在 compose 文件中可用 ${VAR_NAME} 引用：

  environment:
    - MYSQL_ROOT_PASSWORD=${MYSQL_ROOT_PASSWORD}
  ports:
    - "${NGINX_PORT}:80"
  

2. env_file 字段

• 可引用任意目录下的环境变量文件

  env_file:
    - ./envs/web.env
  

3. 环境变量优先级

1. CLI 明确指定的变量（docker compose run -e）
2. environment 字段
3. env_file
4. .env 文件

四、多 Compose 文件合并与覆盖（-f 参数）

1. 作用场景

• 支持分环境、多场景、多团队协作（如 base、dev、prod 各自有独立配置）
• 可覆盖/扩展基础配置而无需重复写

2. 用法

docker compose -f docker-compose.yml -f docker-compose.prod.yml up
# 后面的文件会覆盖前面的同名配置

• 举例：
  • docker-compose.yml：基础定义
  • docker-compose.override.yml：自动应用，适合开发环境
  • docker-compose.prod.yml：生产环境覆盖端口、镜像、环境变量等

3. 合并规则

• services、networks、volumes 等对象按名字合并
• 后加载的文件会覆盖前文件的同名字段
• 数组型字段（如 environment、volumes）会合并/追加

五、完整案例

version: '3.9'
services:
  web:
    build: .
    ports:
      - "${WEB_PORT}:80"
    environment:
      - ENV=production
    depends_on:
      - db
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost/"]
      interval: 30s
      retries: 3
  db:
    image: postgres:16
    volumes:
      - dbdata:/var/lib/postgresql/data
    environment:
      POSTGRES_PASSWORD: ${DB_PWD}
volumes:
  dbdata:
networks:
  default:
    driver: bridge

.env 文件内容：

WEB_PORT=8080
DB_PWD=supersecret

六、参考资料

• Compose 文件官方文档
• Compose 环境变量与覆盖机制
• Compose 多文件合并规则