第一次花时间完整读 Docker Compose 的语法说实话我是被一份怎么也起不来的 docker-compose.yml 逼的。之前从各种仓库复制粘贴docker compose up -d一把梭跑不起来就删了重来后来发现真正卡我的不是网络、不是镜像而是语法缩进错一行、端口写成数字没加引号、environment 里混用冒号和等号每一个都能让解析器翻脸。等我把这套语法从头到尾梳理过一遍之后才发现docker compose 语法本身不难难的是很多人把它当普通 YAML 在写忽略了 Compose 自己在字段语义上的约束。这篇文章不聊docker run和docker-compose的老历史直接讲现在的 Docker Compose v2 环境下怎么写一份稳定、可维护、不靠玄学排错的 compose 文件。适合正在学 docker compose 语法的人也适合已经会up/down但每次改文件都要靠报错猜格式的朋友。内容会从顶层结构、高频字段拆解、完整示例、常见报错排查一路讲到未来迁移 Kubernetes 时需要注意的语法习惯。1. 先分清 YAML 语法和 Compose 语义很多坑就是从这里来的1.1 compose 文件其实分三层顶层对象、服务、服务内部字段很多人一上来就盯着services下面的配置看忘了 compose 文件的顶层结构其实有五个常用键services: web: image: nginx:alpine volumes: app_data: networks: app_net: configs: app_config: secrets: db_password:services是必须存在的顶层入口你定义的每一个容器都挂在这里。后面四个按需声明如果用到了某个命名卷、自定义网络、配置或密钥却在顶层没有对应声明docker compose config会直接报“未定义资源”的错误。反过来顶层声明一堆但 services 里没人用配置也能通过只是会有无用代码。有个容易忽略的点volumes和networks顶层不声明也能用。绑定挂载走的是宿主机路径不需要顶层卷声明服务没指定 networks 时会自动加入项目默认网络。所以最小可运行的 compose 文件可以非常精简一个image加一个ports就够了这也是新手不容易理解顶层对象作用的原因。1.2 空格、Tab、冒号、引号的几条硬规则docker compose 语法基于 YAML但如果你只是把它当“缩进格式”迟早会在很难看的报错上浪费时间。我踩过的坑归纳下来就几条缩进只能用空格绝对不能混 Tab。编辑器如果默认把 Tab 插入为空格这个问题很难发现。冒号后面必须跟空格才能表示键值对key:value这种写法不会被当作映射键而是当成一个普通字符串。短横线-后面也要有空格列表项缩进必须一致。值里含有#、:冒号加空格、{}、[]或明显的数字形态时建议加引号。看一段很典型的错误写法services: web: image: nginx:alpine ports: - 8080:80第二行和第四行如果是 Tab解析器会报found a character that cannot start any token或缩进类错误。即使某些环境能忍换到docker compose config校验时也不一定过所以我的习惯是所有 compose 文件统一两空格缩进不用 Tab这样任何编辑器打开都是同一个结果。1.3 version 字段不是必填项别再被老文章带偏网上大量教程开头会写version: 3.8这是 docker-compose v1 时代的写法当时需要version来决定 schema 行为。现在主流的 Docker Compose v2 里version字段已经废弃最新版本如果写了它解析时会出现 obsolete 警告或者被直接忽略。我见过不少新人在旧项目模板基础上加新服务看到警告不知道怎么处理其实答案很简单删掉这行。如果你看到“version 不写默认就是最新语法”的说法也别全信更准确的理解是现代 compose 语法已经不太依赖version去切换功能了顶层有什么键、服务里怎么写由你安装的 compose 版本决定。与其纠结版本号不如先跑一条docker compose version确认环境。2. 高频字段逐一拆解语法正确不等于运行正确2.1 image、build、container_name 怎么选image和build是服务定义里的两种镜像来源。直接部署现成镜像时写image: mysql:8.0需要自己构建时写services: backend: build: ./backend image: blog-backend:latestbuild指向包含 Dockerfile 的目录image在这里的作用是给构建产物打标签。如果不写imagecompose 会生成一个以项目名和服务名组合的镜像名虽然也能用但想手动 push 或二次构建时不好认。重点提醒一下container_name。这个字段语法很简单但语义上是个大坑services: nginx: image: nginx:alpine container_name: my-nginx一旦固定了容器名服务就不能通过docker compose up --scale扩展多副本项目里也不能同时存在第二个同名服务。compose 自带的命名规则是“项目名-服务名-序号”已经能保证唯一性所以我只在对接外部工具、必须用固定容器名的场景才写container_name常规项目一律不写。2.2 ports、expose端口映射的两种写法和“双冒号”习惯端口映射是 compose 里最常见也最容易写错的字段。短语法长这样services: nginx: image: nginx:alpine ports: - 8080:80 - 127.0.0.1:8081:80 - 8080-8085:80-85第一行把容器 80 端口映射到宿主机 8080第二行限制只允许本机访问第三行是端口范围映射。我的习惯是端口永远用字符串引起来写8080:80而不是8080:80。虽然新版 YAML 对无空格的冒号容忍度已经很高但引号能避免在特殊解析环境下被当成数字或其他类型这个习惯成本极低收益却很稳定。如果你想映射随机宿主机端口只写容器端口即可ports: - 80不过这在 compose 里不常用因为每次启动宿主机端口都会变不好维护。另一个容易被忽略的概念是exposeservices: backend: expose: - 9000expose只是声明容器端口可以被同一个 docker 网络里的其他服务访问并不会发布到宿主机。数据库、内部 API 这类不希望外部直连的服务用expose比ports更安全。长短语法对比时长语法适合需要精确控制协议的场景ports: - target: 80 published: 8080 protocol: tcp mode: host日常用短语法就够了但读别人文件时看到这种写法要认识。2.3 environment、env_file变量注入的优先级和转义问题给服务传环境变量有两种常见写法。推荐用映射形式services: mysql: image: mysql:8.0 environment: MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD:-root123} TZ: Asia/Shanghai老教程里还有一种列表形式environment: - MYSQL_ROOT_PASSWORDroot123列表形式语法上合法但有个新手常犯的错把写成:例如- MYSQL_ROOT_PASSWORD: root123。YAML 解析不出错但 compose 解析环境变量列表时找不到等号最后报一个莫名其妙的 invalid environment 错误。能用映射形式就不要用列表能少记一种坑就少记一种。env_file是把整个文件里的变量塞进容器env_file: - .env.db优先级上environment会覆盖env_file文件里声明的同名变量不会反过来覆盖 environment。这里最隐蔽的是$转义。假如密码里真的带美元符号比如pa$$word写进 environment 时要用两个$$environment: DB_PASS: pa$$word因为 compose 会先做一层变量插值$$才表示字面量$。这个知识点平时用不到一用不到就容易忘等你真的遇到“密码怎么总是被解析掉一部分”时再回来看就懂了。2.4 volumes绑定挂载、命名卷和长语法volumes 有两种主要形式。绑定挂载直接映射宿主机目录services: nginx: volumes: - ./html:/usr/share/nginx/html:ro - /data/conf:/etc/nginx/conf.d:ro宿主机路径写相对路径会自动带上 compose 文件所在目录写成绝对路径也行。:ro表示只读建议所有配置类文件都加能防止容器内部误改宿主机文件。容器内路径必须写绝对路径只写一个相对路径会直接报mount path must be absolute。命名卷需要顶层声明services: mysql: image: mysql:8.0 volumes: - db_data:/var/lib/mysql volumes: db_data:加了顶层db_data:之后这个卷就由 compose 管理。相比绑定挂载命名卷不用担心宿主机目录的权限问题MySQL、PostgreSQL 这些数据目录用命名卷几乎是最稳妥的。但要注意数据安全docker compose down -v会连带删除命名卷里的数据。如果既需要精确参数又要可读性用长语法volumes: - type: volume source: db_data target: /var/lib/mysql volume: nocopy: true - type: bind source: ./init target: /docker-entrypoint-initdb.d read_only: true长语法观感复杂但在表达式多、需要区分 type 的场景下能少不少歧义。2.5 depends_on 和 healthcheck让启动顺序真的生效很多人写依赖只懂得用 depends_onservices: web: depends_on: - db这样写语法没问题但它只保证 db 容器先启动不保证 MySQL 已经能接受连接。web 起来后大概率还是连不上然后疯狂重试。要真正实现“依赖就绪再启动”必须配合健康检查services: mysql: image: mysql:8.0 healthcheck: test: [CMD, mysqladmin, ping, -h, 127.0.0.1] interval: 10s timeout: 5s retries: 5 start_period: 20s web: depends_on: mysql: condition: service_healthyhealthcheck 的字段含义需要理解清楚interval是健康检查间隔timeout是单次检查超时时间retries是连续失败多少次判定 unhealthystart_period是启动宽限期。start_period 最容易忽略像 Java 应用启动可能要几十秒没有它的话检查器会从容器启动就开始计数明明只是启动慢却被判成 unhealthy。执行检查命令时如果你的镜像里没有 curl别硬写 curl可以先想清楚基础镜像包含什么。比如 Alpine 系一般有 wget测试命令可以写成healthcheck: test: [CMD-SHELL, wget -qO- http://127.0.0.1:9000/health /dev/null 21 || exit 1]另一个容易翻车的点是test里如果用$引用容器环境变量比如$$MYSQL_ROOT_PASSWORD要写双美元留一个给容器内 shell 展开compose 不会帮你展开。这一点和 environment 的$$是同一套逻辑。2.6 restart、deploy、资源限制本地和集群的差别容器的重启策略写在 restart 里restart: unless-stopped可选值包括no、always、on-failure:3、unless-stopped。我日常用unless-stopped最多因为手动docker stop之后它不会在 Docker 重启时强行拉起always则会。如果你不希望宕机后服务互相拉起打架先想清楚策略再写。真正有迷惑性的是deploydeploy: replicas: 3 resources: limits: cpus: 0.50 memory: 512Mdeploy是 Docker Swarm 时代的字段语法在 compose 文件里合法但用docker compose up在单机跑时replicas并不会真的帮你扩出三个副本。新版本 compose 对resources有部分兼容但你写文件时不能想当然。如果只是单机限制资源更直接的是用mem_limit、cpus这些字段如果面向 swarm 或云平台再写完整的deploy。3. 一份可直接参照的完整示例从前端反代到 MySQL3.1 先明确需求再写结构光说语法容易散我拿一个典型的个人项目举例一个 Nginx 反代静态资源一个后端 API一个 MySQL。目录结构先定好. ├── docker-compose.yml ├── .env ├── nginx/ │ └── conf.d/ │ └── default.conf ├── backend/ │ └── Dockerfile └── static/ └── index.htmlcompose 文件放在根目录配置文件放各自子目录这个结构在后续交接、迁移时都很清晰。3.2 compose 文件逐个解释完整的 docker-compose.yml 如下services: nginx: image: nginx:1.27-alpine ports: - ${WEB_PORT:-80}:80 volumes: - ./nginx/conf.d:/etc/nginx/conf.d:ro - ./static:/usr/share/nginx/html:ro depends_on: backend: condition: service_healthy restart: unless-stopped backend: build: ./backend image: blog-backend:latest environment: DB_HOST: mysql DB_PORT: 3306 DB_NAME: ${MYSQL_DATABASE:-blog} env_file: - .env.backend expose: - 9000 depends_on: mysql: condition: service_healthy healthcheck: test: [CMD-SHELL, wget -qO- http://127.0.0.1:9000/health /dev/null 21 || exit 1] interval: 10s timeout: 3s retries: 5 start_period: 15s restart: unless-stopped mysql: image: mysql:8.0 environment: MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD:?请设置MYSQL_ROOT_PASSWORD} MYSQL_DATABASE: ${MYSQL_DATABASE:-blog} volumes: - db_data:/var/lib/mysql - ./mysql/init:/docker-entrypoint-initdb.d:ro healthcheck: test: [CMD-SHELL, mysqladmin ping -h 127.0.0.1 -uroot -p$$MYSQL_ROOT_PASSWORD --silent] interval: 10s timeout: 5s retries: 10 start_period: 30s restart: unless-stopped volumes: db_data:逐段看为什么要这么写Nginx 服务没有 healthcheck因为它的健康主要由后端决定depends_on的condition: service_healthy会让 nginx 等 backend 健康检查通过后再启动这个顺序在企业内部比较常见。backend 的DB_HOST: mysql不是随便写的。同一个项目默认网络里服务名就是 DNS 名backend 容器访问数据库主机名直接填mysql就行不需要填 IP也不需要links配置。backend 只expose了 9000不发布到宿主机因为只有 Nginx 需要通过内部网络访问它。MySQL 的健康检查用mysqladmin ping。$$MYSQL_ROOT_PASSWORD里的双美元很重要compose 只保留一个$传给容器内的 shellshell 再从容器环境变量里拿到真正的密码。${MYSQL_ROOT_PASSWORD:?...}这种插值语法会在变量缺失时直接让配置失败避免 MySQL 带着空密码启动。如果你不想强制要求可以把:?换成:-默认值。3.3 写完后先用 docker compose config 验证不要在写完文件后直接docker compose up -d。先执行docker compose config --quiet没有输出就代表语法解析通过。想看得更清楚直接跑docker compose config会打印出最终解析结果变量替换、端口映射、挂载路径都会展开。我一般用两步确认docker compose config docker compose config --quiet docker compose up -d这个习惯能帮你区分两类问题配置文件本身的问题还是容器运行时的问题。很多时候日志报错一大段实际上docker compose config早就该提醒你字段写错了。4. 常见报错速查与真实排查流程4.1 高频报错对照表下面的报错是我在群里、公司里、自己项目里见过的真实高频问题整理成速查表报错关键词常见原因处理方式found a tab character that violate indentationYAML 缩进里混入 Tab删除 Tab统一用空格service xx refers to undefined volume使用了命名卷但顶层没声明在顶层加volumes:并声明该卷名mount path must be absolute卷的目标路径写了相对路径容器内目标路径必须以/开头pull access denied for xxx镜像名拼错或私有仓库未登录检查 image 完整名称先docker logincontainer name already in use之前同名容器还存在先docker compose down或在容器管理里删除旧容器version is obsolete引用了老文章的 version 字段把version:整行删掉cant find a suitable configuration file当前目录没有 compose 文件进入正确目录或用-f指定文件路径invalid environment variableenvironment 列表里用了冒号或缺失等号改成KEYvalue或使用映射形式看到报错先别慌把真正“原因”的部分读出来。比如Ports are not available后面一般紧跟bind address already in use这就是宿主机端口被占用和语法没有关系停止占用端口的进程再重试就好。4.2 一个典型的 stop 失败排查过程现在很多人碰到的是这种从客户端封装里跑出来的提示Cannot stop docker compose application. reason: compose [stop] exit status 1它看起来像 stop 命令本身挂了但我在实际项目里发现问题经常不在 stop 动作而在于 compose 在 stop 前要先重新读取并解析当前目录的 compose 文件。如果你刚改完文件改出语法错误、删除或重命名了卷、或者环境变量引用了不存在的内容stop 就可能失败然后这一大段报错把真正原因盖住了。我的排查顺序固定是docker compose config --quiet如果这条都过不了先把语法修好。能过的话再看项目容器状态docker compose ps -a确认容器是否在跑有没有处于异常状态的容器。最后用docker compose stop直接在当前目录重试一次通常能看到最原始的错误文本。在终端里跑命令永远比在带界面的客户端里看封装后的提示更容易定位问题。4.3 “语法没错但行为怪”的两类隐蔽问题第一类是变量插值的缺省逻辑。${VAR:-默认值}表示变量为空或未设置时用默认值${VAR-默认值}表示只有未设置时才用默认值变量为空字符串时会保留空字符串。这个区别很细但影响很实际。比如.env里MYSQL_DATABASE空着用:-能兜底成 blog用-就只能得到空库名。第二类是显式声明了命名卷却不知道它已经被其他项目用过。比如volumes: db_data: external: true一旦加external: truecompose 不再自动创建卷而是要求这个卷在当前机器上已存在。适合多项目共用数据卷的场景但新手很容易因为忘记先建卷而报 “volume not found”。如果是单项目内部数据完全没必要加 external直接顶层声明让 compose 管理就好。5. 想把 compose 迁到 Kubernetes这几个语法习惯要提前改5.1 deploy 字段别当成 K8s 的 replicas有一个热搜词叫“docker compose 升级到 k8s”这确实是想把 compose 用到大集群里的人都会关心的问题。很多工具比如 kompose能把 compose 文件转换成 Kubernetes 的 Deployment、Service、PVC 等清单但转换质量取决于你原文件怎么写。要特别注意deploy字段。它不是 Kubernetes 语义而是从 Docker Swarm 时代保留下来的语法。比如deploy.replicas: 3在 compose 本地跑不会给你创建三个容器转成 K8s 时工具也可能把它当成一个参考而不是严格的副本数契约。与其指望一个万能转换器不如在写 compose 时就明确资源限制、健康检查和持久化卷让这些信息能完整地映射过去。5.2 现在就该改掉的三类写法如果预期会迁移我建议从今天起注意三件事第一少用container_name。这个字段会把服务绑定到一个固定容器名不只是影响 compose 的 expandK8s 里也没有“固定容器名”的概念转换工具看到它往往只能忽略或报错。第二把跨服务访问方式统一成服务名。在 compose 网络里用服务名互相访问迁移到 K8s 后同样能对应上 Service 的 DNS 名比在代码里硬编码容器 IP 稳妥得多。写DB_HOST: mysql而不是DB_HOST: 172.18.0.2这种写法后期会省很多事。第三优先使用命名卷而不是绑定宿主机目录。K8s 里对应的是 PVC 和 StorageClass绑定挂载这种依赖具体宿主机的写法在集群里基本不可移植。虽然单机开发用 bind mount 方便改代码但数据持久化部分我还是会切成命名卷为未来留好余地。打个比方compose 文件写得越“声明式”越容易被其他平台理解。你在 compose 里把健康检查、资源限制、持久化卷都定义好迁移时不是重写而是翻译。最后分享一个我自己长期养成的习惯每个 compose 项目都配一个.env把可变参数放进去文件里用${VAR:-default}引用。无论谁拿到项目先看.env.example再复制成.env最后docker compose config检查整个启动流程就不需要猜了。语法这东西不是靠背字段背出来的是靠反复“写错—看报错—修正”磨出来的。等你把最常见的十来个字段写熟了docker compose 语法对你来说就不再是门槛而是一个顺手到不需要想的工具箱。
第一次花时间完整读 Docker Compose 的语法说实话我是被一份怎么也起不来的 docker-compose.yml 逼的。之前从各种仓库复制粘贴docker compose up -d一把梭跑不起来就删了重来后来发现真正卡我的不是网络、不是镜像而是语法缩进错一行、端口写成数字没加引号、environment 里混用冒号和等号每一个都能让解析器翻脸。等我把这套语法从头到尾梳理过一遍之后才发现docker compose 语法本身不难难的是很多人把它当普通 YAML 在写忽略了 Compose 自己在字段语义上的约束。这篇文章不聊docker run和docker-compose的老历史直接讲现在的 Docker Compose v2 环境下怎么写一份稳定、可维护、不靠玄学排错的 compose 文件。适合正在学 docker compose 语法的人也适合已经会up/down但每次改文件都要靠报错猜格式的朋友。内容会从顶层结构、高频字段拆解、完整示例、常见报错排查一路讲到未来迁移 Kubernetes 时需要注意的语法习惯。1. 先分清 YAML 语法和 Compose 语义很多坑就是从这里来的1.1 compose 文件其实分三层顶层对象、服务、服务内部字段很多人一上来就盯着services下面的配置看忘了 compose 文件的顶层结构其实有五个常用键services: web: image: nginx:alpine volumes: app_data: networks: app_net: configs: app_config: secrets: db_password:services是必须存在的顶层入口你定义的每一个容器都挂在这里。后面四个按需声明如果用到了某个命名卷、自定义网络、配置或密钥却在顶层没有对应声明docker compose config会直接报“未定义资源”的错误。反过来顶层声明一堆但 services 里没人用配置也能通过只是会有无用代码。有个容易忽略的点volumes和networks顶层不声明也能用。绑定挂载走的是宿主机路径不需要顶层卷声明服务没指定 networks 时会自动加入项目默认网络。所以最小可运行的 compose 文件可以非常精简一个image加一个ports就够了这也是新手不容易理解顶层对象作用的原因。1.2 空格、Tab、冒号、引号的几条硬规则docker compose 语法基于 YAML但如果你只是把它当“缩进格式”迟早会在很难看的报错上浪费时间。我踩过的坑归纳下来就几条缩进只能用空格绝对不能混 Tab。编辑器如果默认把 Tab 插入为空格这个问题很难发现。冒号后面必须跟空格才能表示键值对key:value这种写法不会被当作映射键而是当成一个普通字符串。短横线-后面也要有空格列表项缩进必须一致。值里含有#、:冒号加空格、{}、[]或明显的数字形态时建议加引号。看一段很典型的错误写法services: web: image: nginx:alpine ports: - 8080:80第二行和第四行如果是 Tab解析器会报found a character that cannot start any token或缩进类错误。即使某些环境能忍换到docker compose config校验时也不一定过所以我的习惯是所有 compose 文件统一两空格缩进不用 Tab这样任何编辑器打开都是同一个结果。1.3 version 字段不是必填项别再被老文章带偏网上大量教程开头会写version: 3.8这是 docker-compose v1 时代的写法当时需要version来决定 schema 行为。现在主流的 Docker Compose v2 里version字段已经废弃最新版本如果写了它解析时会出现 obsolete 警告或者被直接忽略。我见过不少新人在旧项目模板基础上加新服务看到警告不知道怎么处理其实答案很简单删掉这行。如果你看到“version 不写默认就是最新语法”的说法也别全信更准确的理解是现代 compose 语法已经不太依赖version去切换功能了顶层有什么键、服务里怎么写由你安装的 compose 版本决定。与其纠结版本号不如先跑一条docker compose version确认环境。2. 高频字段逐一拆解语法正确不等于运行正确2.1 image、build、container_name 怎么选image和build是服务定义里的两种镜像来源。直接部署现成镜像时写image: mysql:8.0需要自己构建时写services: backend: build: ./backend image: blog-backend:latestbuild指向包含 Dockerfile 的目录image在这里的作用是给构建产物打标签。如果不写imagecompose 会生成一个以项目名和服务名组合的镜像名虽然也能用但想手动 push 或二次构建时不好认。重点提醒一下container_name。这个字段语法很简单但语义上是个大坑services: nginx: image: nginx:alpine container_name: my-nginx一旦固定了容器名服务就不能通过docker compose up --scale扩展多副本项目里也不能同时存在第二个同名服务。compose 自带的命名规则是“项目名-服务名-序号”已经能保证唯一性所以我只在对接外部工具、必须用固定容器名的场景才写container_name常规项目一律不写。2.2 ports、expose端口映射的两种写法和“双冒号”习惯端口映射是 compose 里最常见也最容易写错的字段。短语法长这样services: nginx: image: nginx:alpine ports: - 8080:80 - 127.0.0.1:8081:80 - 8080-8085:80-85第一行把容器 80 端口映射到宿主机 8080第二行限制只允许本机访问第三行是端口范围映射。我的习惯是端口永远用字符串引起来写8080:80而不是8080:80。虽然新版 YAML 对无空格的冒号容忍度已经很高但引号能避免在特殊解析环境下被当成数字或其他类型这个习惯成本极低收益却很稳定。如果你想映射随机宿主机端口只写容器端口即可ports: - 80不过这在 compose 里不常用因为每次启动宿主机端口都会变不好维护。另一个容易被忽略的概念是exposeservices: backend: expose: - 9000expose只是声明容器端口可以被同一个 docker 网络里的其他服务访问并不会发布到宿主机。数据库、内部 API 这类不希望外部直连的服务用expose比ports更安全。长短语法对比时长语法适合需要精确控制协议的场景ports: - target: 80 published: 8080 protocol: tcp mode: host日常用短语法就够了但读别人文件时看到这种写法要认识。2.3 environment、env_file变量注入的优先级和转义问题给服务传环境变量有两种常见写法。推荐用映射形式services: mysql: image: mysql:8.0 environment: MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD:-root123} TZ: Asia/Shanghai老教程里还有一种列表形式environment: - MYSQL_ROOT_PASSWORDroot123列表形式语法上合法但有个新手常犯的错把写成:例如- MYSQL_ROOT_PASSWORD: root123。YAML 解析不出错但 compose 解析环境变量列表时找不到等号最后报一个莫名其妙的 invalid environment 错误。能用映射形式就不要用列表能少记一种坑就少记一种。env_file是把整个文件里的变量塞进容器env_file: - .env.db优先级上environment会覆盖env_file文件里声明的同名变量不会反过来覆盖 environment。这里最隐蔽的是$转义。假如密码里真的带美元符号比如pa$$word写进 environment 时要用两个$$environment: DB_PASS: pa$$word因为 compose 会先做一层变量插值$$才表示字面量$。这个知识点平时用不到一用不到就容易忘等你真的遇到“密码怎么总是被解析掉一部分”时再回来看就懂了。2.4 volumes绑定挂载、命名卷和长语法volumes 有两种主要形式。绑定挂载直接映射宿主机目录services: nginx: volumes: - ./html:/usr/share/nginx/html:ro - /data/conf:/etc/nginx/conf.d:ro宿主机路径写相对路径会自动带上 compose 文件所在目录写成绝对路径也行。:ro表示只读建议所有配置类文件都加能防止容器内部误改宿主机文件。容器内路径必须写绝对路径只写一个相对路径会直接报mount path must be absolute。命名卷需要顶层声明services: mysql: image: mysql:8.0 volumes: - db_data:/var/lib/mysql volumes: db_data:加了顶层db_data:之后这个卷就由 compose 管理。相比绑定挂载命名卷不用担心宿主机目录的权限问题MySQL、PostgreSQL 这些数据目录用命名卷几乎是最稳妥的。但要注意数据安全docker compose down -v会连带删除命名卷里的数据。如果既需要精确参数又要可读性用长语法volumes: - type: volume source: db_data target: /var/lib/mysql volume: nocopy: true - type: bind source: ./init target: /docker-entrypoint-initdb.d read_only: true长语法观感复杂但在表达式多、需要区分 type 的场景下能少不少歧义。2.5 depends_on 和 healthcheck让启动顺序真的生效很多人写依赖只懂得用 depends_onservices: web: depends_on: - db这样写语法没问题但它只保证 db 容器先启动不保证 MySQL 已经能接受连接。web 起来后大概率还是连不上然后疯狂重试。要真正实现“依赖就绪再启动”必须配合健康检查services: mysql: image: mysql:8.0 healthcheck: test: [CMD, mysqladmin, ping, -h, 127.0.0.1] interval: 10s timeout: 5s retries: 5 start_period: 20s web: depends_on: mysql: condition: service_healthyhealthcheck 的字段含义需要理解清楚interval是健康检查间隔timeout是单次检查超时时间retries是连续失败多少次判定 unhealthystart_period是启动宽限期。start_period 最容易忽略像 Java 应用启动可能要几十秒没有它的话检查器会从容器启动就开始计数明明只是启动慢却被判成 unhealthy。执行检查命令时如果你的镜像里没有 curl别硬写 curl可以先想清楚基础镜像包含什么。比如 Alpine 系一般有 wget测试命令可以写成healthcheck: test: [CMD-SHELL, wget -qO- http://127.0.0.1:9000/health /dev/null 21 || exit 1]另一个容易翻车的点是test里如果用$引用容器环境变量比如$$MYSQL_ROOT_PASSWORD要写双美元留一个给容器内 shell 展开compose 不会帮你展开。这一点和 environment 的$$是同一套逻辑。2.6 restart、deploy、资源限制本地和集群的差别容器的重启策略写在 restart 里restart: unless-stopped可选值包括no、always、on-failure:3、unless-stopped。我日常用unless-stopped最多因为手动docker stop之后它不会在 Docker 重启时强行拉起always则会。如果你不希望宕机后服务互相拉起打架先想清楚策略再写。真正有迷惑性的是deploydeploy: replicas: 3 resources: limits: cpus: 0.50 memory: 512Mdeploy是 Docker Swarm 时代的字段语法在 compose 文件里合法但用docker compose up在单机跑时replicas并不会真的帮你扩出三个副本。新版本 compose 对resources有部分兼容但你写文件时不能想当然。如果只是单机限制资源更直接的是用mem_limit、cpus这些字段如果面向 swarm 或云平台再写完整的deploy。3. 一份可直接参照的完整示例从前端反代到 MySQL3.1 先明确需求再写结构光说语法容易散我拿一个典型的个人项目举例一个 Nginx 反代静态资源一个后端 API一个 MySQL。目录结构先定好. ├── docker-compose.yml ├── .env ├── nginx/ │ └── conf.d/ │ └── default.conf ├── backend/ │ └── Dockerfile └── static/ └── index.htmlcompose 文件放在根目录配置文件放各自子目录这个结构在后续交接、迁移时都很清晰。3.2 compose 文件逐个解释完整的 docker-compose.yml 如下services: nginx: image: nginx:1.27-alpine ports: - ${WEB_PORT:-80}:80 volumes: - ./nginx/conf.d:/etc/nginx/conf.d:ro - ./static:/usr/share/nginx/html:ro depends_on: backend: condition: service_healthy restart: unless-stopped backend: build: ./backend image: blog-backend:latest environment: DB_HOST: mysql DB_PORT: 3306 DB_NAME: ${MYSQL_DATABASE:-blog} env_file: - .env.backend expose: - 9000 depends_on: mysql: condition: service_healthy healthcheck: test: [CMD-SHELL, wget -qO- http://127.0.0.1:9000/health /dev/null 21 || exit 1] interval: 10s timeout: 3s retries: 5 start_period: 15s restart: unless-stopped mysql: image: mysql:8.0 environment: MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD:?请设置MYSQL_ROOT_PASSWORD} MYSQL_DATABASE: ${MYSQL_DATABASE:-blog} volumes: - db_data:/var/lib/mysql - ./mysql/init:/docker-entrypoint-initdb.d:ro healthcheck: test: [CMD-SHELL, mysqladmin ping -h 127.0.0.1 -uroot -p$$MYSQL_ROOT_PASSWORD --silent] interval: 10s timeout: 5s retries: 10 start_period: 30s restart: unless-stopped volumes: db_data:逐段看为什么要这么写Nginx 服务没有 healthcheck因为它的健康主要由后端决定depends_on的condition: service_healthy会让 nginx 等 backend 健康检查通过后再启动这个顺序在企业内部比较常见。backend 的DB_HOST: mysql不是随便写的。同一个项目默认网络里服务名就是 DNS 名backend 容器访问数据库主机名直接填mysql就行不需要填 IP也不需要links配置。backend 只expose了 9000不发布到宿主机因为只有 Nginx 需要通过内部网络访问它。MySQL 的健康检查用mysqladmin ping。$$MYSQL_ROOT_PASSWORD里的双美元很重要compose 只保留一个$传给容器内的 shellshell 再从容器环境变量里拿到真正的密码。${MYSQL_ROOT_PASSWORD:?...}这种插值语法会在变量缺失时直接让配置失败避免 MySQL 带着空密码启动。如果你不想强制要求可以把:?换成:-默认值。3.3 写完后先用 docker compose config 验证不要在写完文件后直接docker compose up -d。先执行docker compose config --quiet没有输出就代表语法解析通过。想看得更清楚直接跑docker compose config会打印出最终解析结果变量替换、端口映射、挂载路径都会展开。我一般用两步确认docker compose config docker compose config --quiet docker compose up -d这个习惯能帮你区分两类问题配置文件本身的问题还是容器运行时的问题。很多时候日志报错一大段实际上docker compose config早就该提醒你字段写错了。4. 常见报错速查与真实排查流程4.1 高频报错对照表下面的报错是我在群里、公司里、自己项目里见过的真实高频问题整理成速查表报错关键词常见原因处理方式found a tab character that violate indentationYAML 缩进里混入 Tab删除 Tab统一用空格service xx refers to undefined volume使用了命名卷但顶层没声明在顶层加volumes:并声明该卷名mount path must be absolute卷的目标路径写了相对路径容器内目标路径必须以/开头pull access denied for xxx镜像名拼错或私有仓库未登录检查 image 完整名称先docker logincontainer name already in use之前同名容器还存在先docker compose down或在容器管理里删除旧容器version is obsolete引用了老文章的 version 字段把version:整行删掉cant find a suitable configuration file当前目录没有 compose 文件进入正确目录或用-f指定文件路径invalid environment variableenvironment 列表里用了冒号或缺失等号改成KEYvalue或使用映射形式看到报错先别慌把真正“原因”的部分读出来。比如Ports are not available后面一般紧跟bind address already in use这就是宿主机端口被占用和语法没有关系停止占用端口的进程再重试就好。4.2 一个典型的 stop 失败排查过程现在很多人碰到的是这种从客户端封装里跑出来的提示Cannot stop docker compose application. reason: compose [stop] exit status 1它看起来像 stop 命令本身挂了但我在实际项目里发现问题经常不在 stop 动作而在于 compose 在 stop 前要先重新读取并解析当前目录的 compose 文件。如果你刚改完文件改出语法错误、删除或重命名了卷、或者环境变量引用了不存在的内容stop 就可能失败然后这一大段报错把真正原因盖住了。我的排查顺序固定是docker compose config --quiet如果这条都过不了先把语法修好。能过的话再看项目容器状态docker compose ps -a确认容器是否在跑有没有处于异常状态的容器。最后用docker compose stop直接在当前目录重试一次通常能看到最原始的错误文本。在终端里跑命令永远比在带界面的客户端里看封装后的提示更容易定位问题。4.3 “语法没错但行为怪”的两类隐蔽问题第一类是变量插值的缺省逻辑。${VAR:-默认值}表示变量为空或未设置时用默认值${VAR-默认值}表示只有未设置时才用默认值变量为空字符串时会保留空字符串。这个区别很细但影响很实际。比如.env里MYSQL_DATABASE空着用:-能兜底成 blog用-就只能得到空库名。第二类是显式声明了命名卷却不知道它已经被其他项目用过。比如volumes: db_data: external: true一旦加external: truecompose 不再自动创建卷而是要求这个卷在当前机器上已存在。适合多项目共用数据卷的场景但新手很容易因为忘记先建卷而报 “volume not found”。如果是单项目内部数据完全没必要加 external直接顶层声明让 compose 管理就好。5. 想把 compose 迁到 Kubernetes这几个语法习惯要提前改5.1 deploy 字段别当成 K8s 的 replicas有一个热搜词叫“docker compose 升级到 k8s”这确实是想把 compose 用到大集群里的人都会关心的问题。很多工具比如 kompose能把 compose 文件转换成 Kubernetes 的 Deployment、Service、PVC 等清单但转换质量取决于你原文件怎么写。要特别注意deploy字段。它不是 Kubernetes 语义而是从 Docker Swarm 时代保留下来的语法。比如deploy.replicas: 3在 compose 本地跑不会给你创建三个容器转成 K8s 时工具也可能把它当成一个参考而不是严格的副本数契约。与其指望一个万能转换器不如在写 compose 时就明确资源限制、健康检查和持久化卷让这些信息能完整地映射过去。5.2 现在就该改掉的三类写法如果预期会迁移我建议从今天起注意三件事第一少用container_name。这个字段会把服务绑定到一个固定容器名不只是影响 compose 的 expandK8s 里也没有“固定容器名”的概念转换工具看到它往往只能忽略或报错。第二把跨服务访问方式统一成服务名。在 compose 网络里用服务名互相访问迁移到 K8s 后同样能对应上 Service 的 DNS 名比在代码里硬编码容器 IP 稳妥得多。写DB_HOST: mysql而不是DB_HOST: 172.18.0.2这种写法后期会省很多事。第三优先使用命名卷而不是绑定宿主机目录。K8s 里对应的是 PVC 和 StorageClass绑定挂载这种依赖具体宿主机的写法在集群里基本不可移植。虽然单机开发用 bind mount 方便改代码但数据持久化部分我还是会切成命名卷为未来留好余地。打个比方compose 文件写得越“声明式”越容易被其他平台理解。你在 compose 里把健康检查、资源限制、持久化卷都定义好迁移时不是重写而是翻译。最后分享一个我自己长期养成的习惯每个 compose 项目都配一个.env把可变参数放进去文件里用${VAR:-default}引用。无论谁拿到项目先看.env.example再复制成.env最后docker compose config检查整个启动流程就不需要猜了。语法这东西不是靠背字段背出来的是靠反复“写错—看报错—修正”磨出来的。等你把最常见的十来个字段写熟了docker compose 语法对你来说就不再是门槛而是一个顺手到不需要想的工具箱。
