Docker Compose 配置文件常用语法归纳与示例-豆包

发布时间：2026/10/27 1:41:06
Docker Compose 配置文件常用语法归纳与示例-豆包

Docker Compose 配置文件常用语法归纳与示例

Docker Compose 配置文件默认名为docker-compose.yml，遵循 YAML 语法规范（缩进敏感，推荐使用 2 空格缩进）。当前主流遵循Compose Specification规范，可省略旧版的version字段；旧版 v2/v3 语法仍向下兼容。

以下从顶层配置、服务级核心配置、网络与数据卷配置三个维度，归纳最常用的语法并附详细示例。

一、顶层核心配置项

顶层字段定义 Compose 项目的全局资源，最常用的有 5 个：

字段作用
services核心必填项，定义所有应用服务，每个服务对应一组容器
networks定义自定义网络，实现服务间网络互通与隔离
volumes定义持久化数据卷，用于容器数据持久化与跨服务共享
configs管理配置文件，以文件形式挂载到容器内
secrets管理敏感数据（密码、密钥等），安全挂载到容器

二、服务级（services 下）常用语法详解

services下每个子项代表一个服务，是 Compose 配置的核心。以下按使用频率排序，逐一说明语法与用法。

1. image：指定基础镜像

使用已有镜像启动容器，是最基础的配置。

services:nginx:image:nginx:1.25-alpine# 格式：镜像名:标签# 支持私有仓库：image: registry.example.com/myapp:v1.0

2. build：从 Dockerfile 构建镜像

基于本地 Dockerfile 构建镜像，替代image字段，支持短格式和长格式。

services:webapp:# 短格式：直接指定构建上下文目录# build: ./app# 长格式：精细化配置build:context:./app# 构建上下文（工作目录）dockerfile:Dockerfile.prod# Dockerfile 文件名，默认 Dockerfileargs:# 构建时参数，对应 Dockerfile 的 ARGNODE_ENV:productiontags:-my-webapp:v1.0# 构建后镜像的标签

3. container_name：自定义容器名称

指定启动后的容器名称，替代默认的项目名_服务名_序号。

services:mysql:image:mysql:8.0container_name:mysql-db

⚠️ 注意：自定义容器名后，该服务无法横向扩展（scale），因为容器名具有唯一性。

4. ports：端口映射（宿主机→容器）

将容器端口映射到宿主机端口，对外提供服务访问，支持短格式和长格式。

services:nginx:image:nginx:1.25ports:-"80:80"# 短格式：宿主机端口:容器端口-"443:443/tcp"# 指定传输协议-"127.0.0.1:8080:8080"# 仅绑定宿主机本地IP，不对外暴露# 长格式写法-target:3306# 容器内端口published:33060# 宿主机端口protocol:tcp# 协议类型mode:host# 映射模式

💡 建议端口用引号包裹，避免 YAML 解析时分号格式异常。

5. expose：内部暴露端口

向同网络的其他服务暴露端口，不映射到宿主机，仅用于服务间内部通信。

services:redis:image:redis:7expose:-"6379"

同网络下的服务可直接通过服务名:端口访问，例如其他服务用redis:6379连接该缓存。

6. environment：注入环境变量

向容器内注入环境变量，是应用配置的主流方式，支持字典和列表两种写法。

services:mysql:image:mysql:8.0# 字典格式（推荐，可读性更好）environment:MYSQL_ROOT_PASSWORD:123456MYSQL_DATABASE:mydbMYSQL_USER:appuser# 列表格式# environment:# - MYSQL_ROOT_PASSWORD=123456# - MYSQL_DATABASE=mydb

7. env_file：从文件批量加载环境变量

从外部文件批量加载环境变量，适合多环境配置、敏感信息隔离。

services:webapp:image:node:18env_file:-.env# 单个文件-./config/app.env# 多个文件，后加载的会覆盖同名变量

.env文件格式为每行KEY=VALUE，注释以#开头。

8. volumes：数据卷挂载

实现容器数据持久化、宿主机文件挂载，分为命名卷、绑定挂载、临时卷三类。

services:mysql:image:mysql:8.0volumes:# 1. 命名卷挂载（Docker管理，推荐用于数据库持久化）-mysql-data:/var/lib/mysql# 2. 宿主机路径绑定挂载（适合配置文件、代码热更新）-./nginx.conf:/etc/nginx/nginx.conf:ro# ro=只读权限，默认rw=读写-./logs:/var/log/nginx# 3. 长格式精细化配置-type:bindsource:./configtarget:/etc/configread_only:true# 命名卷必须在顶层 volumes 字段声明volumes:mysql-data:

9. networks：指定服务所属网络

将服务加入指定网络，实现服务间互通或网络隔离。

services:nginx:image:nginxnetworks:-frontend-backendwebapp:image:myappnetworks:-backend# 顶层定义网络networks:frontend:driver:bridgebackend:driver:bridge

💡 默认情况下，所有服务会自动加入项目名_default网络，服务之间可通过服务名互访。

10. depends_on：服务启动依赖

指定服务启动顺序，被依赖的服务优先启动。

services:webapp:image:myappdepends_on:-mysql-redismysql:image:mysql:8.0redis:image:redis:7

⚠️ 关键注意：depends_on仅保证容器启动顺序，不保证依赖服务完全就绪（例如 MySQL 启动后还需初始化才能连接）。

进阶用法：配合健康检查，等待服务真正就绪：

services:webapp:image:myappdepends_on:mysql:condition:service_healthy# 等待MySQL健康检查通过redis:condition:service_started# 仅等待Redis启动mysql:image:mysql:8.0healthcheck:test:["CMD","mysqladmin","ping","-uroot","-p123456"]interval:5stimeout:3sretries:5

11. restart：重启策略

配置容器退出时的自动重启行为，保障服务可用性。

策略值说明
no默认值，不自动重启
always总是重启，即使手动停止容器，Docker 守护进程重启后也会恢复
on-failure仅非正常退出（退出码非0）时重启
unless-stopped总是重启，除非手动停止容器（生产环境推荐）
services:nginx:image:nginxrestart:unless-stopped

12. command：覆盖默认启动命令

替换 Dockerfile 中CMD定义的默认启动命令。

services:python-app:image:python:3.11# 字符串格式command:python app.py--port=8000# 列表格式（推荐，避免Shell解析歧义）# command: ["python", "app.py", "--port=8000"]

13. healthcheck：容器健康检查

检测容器内服务是否正常运行，配合depends_on实现就绪等待，也用于容器异常自动重启。

services:web:image:nginxhealthcheck:test:["CMD","curl","-f","http://localhost/"]# 检查命令interval:10s# 检查间隔timeout:5s# 单次检查超时时间retries:3# 失败重试次数start_period:10s# 容器启动后多久开始第一次检查

14. logging：日志配置

配置容器日志驱动与参数，避免日志文件占满磁盘。

services:nginx:image:nginxlogging:driver:json-file# 默认日志驱动options:max-size:"10m"# 单个日志文件最大10MBmax-file:"3"# 最多保留3个日志文件

15. extra_hosts：添加 hosts 映射

向容器的/etc/hosts文件添加自定义域名解析记录。

services:webapp:image:myappextra_hosts:-"api.example.com:192.168.1.100"-"db.internal:10.0.0.5"

三、顶层 networks 与 volumes 进阶配置

1. networks 常用配置

  • driver：网络驱动，单机常用bridge（默认）、host、none；集群用overlay
  • ipam：自定义子网、网关
  • external：复用外部已存在的网络
networks:# 自定义固定子网的桥接网络my-net:driver:bridgeipam:config:-subnet:172.20.0.0/16gateway:172.20.0.1# 复用外部已创建的网络existing-net:external:truename:my-precreated-network

2. volumes 常用配置

  • driver：卷驱动，默认local
  • external：复用外部已存在的命名卷
  • driver_opts：驱动参数（如指定挂载设备）
volumes:# 复用外部已创建的数据卷shared-data:external:truename:existing-data-volume

四、完整综合示例

以下是一个典型的 Web 应用栈（Nginx 反向代理 + Node 应用 + MySQL + Redis），覆盖以上 90% 常用语法：

services:# Nginx 反向代理nginx:image:nginx:1.25-alpinecontainer_name:nginx-proxyports:-"80:80"-"443:443"volumes:-./nginx/conf.d:/etc/nginx/conf.d:ro-./nginx/ssl:/etc/nginx/ssl:ro-nginx-logs:/var/log/nginxdepends_on:-webapprestart:unless-stoppednetworks:-frontend-backendhealthcheck:test:["CMD","wget","--spider","http://localhost/"]interval:15stimeout:3sretries:3# 业务应用服务webapp:build:context:./webappdockerfile:Dockerfilecontainer_name:node-webappexpose:-"3000"environment:NODE_ENV:productionDB_HOST:mysqlDB_PORT:3306REDIS_HOST:redisenv_file:-.envvolumes:-./webapp/uploads:/app/uploadsdepends_on:mysql:condition:service_healthyredis:condition:service_startedrestart:unless-stoppednetworks:-backendlogging:options:max-size:"10m"max-file:"3"# MySQL 数据库mysql:image:mysql:8.0container_name:mysql-dbexpose:-"3306"environment:MYSQL_ROOT_PASSWORD:${MYSQL_ROOT_PWD}MYSQL_DATABASE:mydbMYSQL_USER:appuservolumes:-mysql-data:/var/lib/mysql-./mysql/init.sql:/docker-entrypoint-initdb.d/init.sql:rorestart:unless-stoppednetworks:-backendhealthcheck:test:["CMD","mysqladmin","ping","-uroot","-p${MYSQL_ROOT_PWD}"]interval:5stimeout:3sretries:10start_period:20s# Redis 缓存redis:image:redis:7-alpinecontainer_name:redis-cacheexpose:-"6379"volumes:-redis-data:/datarestart:unless-stoppednetworks:-backend# 自定义网络networks:frontend:driver:bridgebackend:driver:bridge# 持久化数据卷volumes:nginx-logs:mysql-data:redis-data:

五、语法注意事项

  1. 缩进敏感：YAML 严格依赖缩进，必须使用空格，不能用 Tab 键，同级元素左对齐。
  2. 变量替换：支持${变量名}语法，自动从系统环境变量或.env文件中读取值。
  3. 服务名即域名：同网络下，服务名可直接作为域名被其他服务解析访问（例如mysql:3306）。
  4. 特殊字符包裹：包含冒号、空格等特殊字符的字符串，建议用引号包裹避免解析错误。

在 Docker Compose 的ports长格式配置中，mode字段用于定义端口的发布模式，合法取值共有 2 种：host和ingress，两者核心差异在于端口绑定范围和转发逻辑，以下分别说明。

mode 有哪几种模式

1.host模式（主机模式）

这是单机 Docker Compose 环境下的默认行为，也是日常开发、单机部署最常用的模式。

  • 工作逻辑：将容器端口直接绑定到容器实际运行的那台宿主机的网络接口上，访问宿主机 IP + 端口即可直达容器。
  • 核心特点：
    • 网络转发路径最短，性能损耗极小
    • 仅在运行容器的宿主机上监听对应端口，其他节点无法访问
    • 单机docker compose up场景下，省略mode字段时默认就是该行为
  • 适用场景：单机部署、对网络性能要求高的场景
services:nginx:image:nginxports:-target:80published:8080protocol:tcpmode:host# 直接绑定到宿主机本地端口

2.ingress模式（入口/路由网格模式）

这是Docker Swarm 集群专属的端口发布模式，单机环境配置不生效。

  • 工作逻辑：基于 Swarm 的路由网格（Routing Mesh）实现，端口会在集群所有节点上统一监听；无论访问集群中哪一台节点的 IP + 端口，都会通过内部路由转发到运行服务的容器上，自带集群负载均衡。
  • 核心特点：
    • 是 Swarm 集群模式（docker stack deploy）下的默认端口模式
    • 访问任意节点 IP 都能访问服务，无需关心容器实际运行在哪个节点
    • 多一层集群路由转发，性能相比host模式略有损耗
  • 适用场景：Swarm 集群部署、多节点统一访问入口、服务多副本负载均衡
services:web:image:nginxports:-target:80published:8080protocol:tcpmode:ingress# Swarm 集群路由网格模式

两种模式核心对比

对比维度host 模式ingress 模式
适用环境单机 / 集群均可仅 Docker Swarm 集群
端口监听范围仅容器所在的宿主机集群所有节点
性能损耗极小略高（多一层路由转发）
负载均衡无自带集群负载均衡
默认场景单机 compose 默认Swarm stack 默认

补充注意事项

  1. 日常单机使用 Docker Compose 时，几乎只用到host模式，mode字段通常可以直接省略。
  2. ingress是 Swarm 集群特性，普通单机执行docker compose up时配置该值不会报错，但不会产生集群路由效果。
  3. Swarm 场景下如果需要保证端口只在容器运行的节点上监听、追求极致性能，才需要显式指定mode: host。