Compose 文件是什么
compose.yaml 用一份声明式文件描述整个多容器应用：services 段定义每个容器怎么起，顶层 networks、volumes、secrets、configs 定义它们共享的资源，name 指定项目名。项目名会影响容器、网络与卷的命名前缀，因此同一台机器上跑多个项目时，靠项目名就能实现隔离。较新的规范已不再需要 version 字段。
顶层字段
| services | 每个键是一个服务：镜像或构建、端口、卷、环境变量、依赖 |
|---|---|
| networks | 自定义网络；不声明时 Compose 自动创建 项目名_default 网络 |
| volumes | 具名数据卷声明区，服务里引用后按名复用 |
| secrets 与 configs | 敏感信息与配置文件的声明式注入，可挂载为文件 |
| name | 项目名，默认取目录名，影响容器、网络与卷的前缀 |
| version | 旧版字段，新规范已不需要，写了会有提示 |
典型使用场景
- 单机多服务：web、api、数据库用一份文件一键起停
- 开发环境标准化：新同事 clone 后一条命令即可跑起全套依赖
- 环境复用：用不同的 env 文件在同一份 compose 上切换开发与测试
- 演示与交付：把产品栈打包成可一键运行的编排文件
- 本地复现线上问题：按线上拓扑在本地起一套最小依赖
最小完整示例
最小完整示例
name: myapp # 项目名，决定容器与网络前缀
services:
web:
image: nginx:1.27-alpine
ports:
- "8080:80" # 短语法端口必须加引号
volumes:
- ./html:/usr/share/nginx/html:ro
depends_on:
db:
condition: service_healthy # 等数据库健康后再启动
db:
image: mysql:8.0
environment:
MYSQL_ROOT_PASSWORD: example
volumes:
- db-data:/var/lib/mysql # 引用顶层声明的具名卷
volumes:
db-data:常用服务级字段
| 字段 | 作用 | 注意点 |
|---|---|---|
| image 与 build | 指定镜像或本地构建上下文 | 两者可同时写，build 配 image 可命名产物 |
| ports | 发布端口到宿主 | 务必加引号，避免被解析成六十进制 |
| volumes | 挂载数据与配置 | 具名卷需在顶层声明 |
| environment 与 env_file | 注入环境变量 | 敏感值不要写进仓库 |
| depends_on | 声明启动依赖 | 短语法只控顺序，不保证就绪 |
| restart | 重启策略 | 长期运行的服务建议 unless-stopped |
services 里引用的卷或网络名称，必须先在顶层对应段落声明；漏声明会直接报 undefined volume 之类错误，启动失败但信息不够直观。
YAML 缩进只能用空格，用 Tab 会直接报解析错误。建议编辑时开启显示空白字符，或直接用编辑器校验插件提前发现问题。