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.02. 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_PASSWORD123456# - MYSQL_DATABASEmydb7. env_file从文件批量加载环境变量从外部文件批量加载环境变量适合多环境配置、敏感信息隔离。services:webapp:image:node:18env_file:-.env# 单个文件-./config/app.env# 多个文件后加载的会覆盖同名变量.env文件格式为每行KEYVALUE注释以#开头。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:511. restart重启策略配置容器退出时的自动重启行为保障服务可用性。策略值说明no默认值不自动重启always总是重启即使手动停止容器Docker 守护进程重启后也会恢复on-failure仅非正常退出退出码非0时重启unless-stopped总是重启除非手动停止容器生产环境推荐services:nginx:image:nginxrestart:unless-stopped12. command覆盖默认启动命令替换 Dockerfile 中CMD定义的默认启动命令。services:python-app:image:python:3.11# 字符串格式command:python app.py--port8000# 列表格式推荐避免Shell解析歧义# command: [python, app.py, --port8000]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集群用overlayipam自定义子网、网关external复用外部已存在的网络networks:# 自定义固定子网的桥接网络my-net:driver:bridgeipam:config:-subnet:172.20.0.0/16gateway:172.20.0.1# 复用外部已创建的网络existing-net:external:truename:my-precreated-network2. volumes 常用配置driver卷驱动默认localexternal复用外部已存在的命名卷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:443volumes:-./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:-3000environment: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:10mmax-file:3# MySQL 数据库mysql:image:mysql:8.0container_name:mysql-dbexpose:-3306environment: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:-6379volumes:-redis-data:/datarestart:unless-stoppednetworks:-backend# 自定义网络networks:frontend:driver:bridgebackend:driver:bridge# 持久化数据卷volumes:nginx-logs:mysql-data:redis-data:五、语法注意事项缩进敏感YAML 严格依赖缩进必须使用空格不能用 Tab 键同级元素左对齐。变量替换支持${变量名}语法自动从系统环境变量或.env文件中读取值。服务名即域名同网络下服务名可直接作为域名被其他服务解析访问例如mysql:3306。特殊字符包裹包含冒号、空格等特殊字符的字符串建议用引号包裹避免解析错误。在 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 默认补充注意事项日常单机使用 Docker Compose 时几乎只用到host模式mode字段通常可以直接省略。ingress是 Swarm 集群特性普通单机执行docker compose up时配置该值不会报错但不会产生集群路由效果。Swarm 场景下如果需要保证端口只在容器运行的节点上监听、追求极致性能才需要显式指定mode: host。