编排文件结构
一份编排文件用 YAML 描述整套环境：顶层声明有哪些服务、用到哪些网络与卷，服务段里再写镜像或构建方式、端口、挂载、变量与依赖。它既是部署依据也是文档，新成员读一遍就能理解系统结构。语法校验命令可以在拉起前发现绝大多数书写错误。
基本信息
| 顶层节 | 服务、网络、卷，按需再加密钥与配置对象 |
|---|---|
| 服务段常用字段 | 镜像或构建、端口、挂载、环境变量、依赖关系、重启策略 |
| 变量替换 | 支持从环境读取变量填充文件内容 |
| 校验方式 | 用配置校验子命令解析并输出最终生效的内容 |
| 缩进约定 | 统一使用两个空格，制表符会直接报错 |
典型使用场景
- 本地开发：一条命令起全套依赖，开发者不必手工装数据库与缓存
- 测试环境部署：把整套关系固化，换机器也能得到一致环境
- 环境差异化：用变量文件区分开发、测试、生产，文件主体共用
- 多服务构建：在服务里声明构建方式与上下文，统一构建整套镜像
- 交付与评审：编排文件进版本库，变更可评审可回溯
结构与缩进示例
结构与缩进示例
services:
web:
image: nginx:1.27-alpine
ports:
- "8080:80"
db:
image: postgres:16-alpine
environment:
POSTGRES_PASSWORD: ${DB_PASSWORD}
volumes:
- dbdata:/var/lib/postgresql/data
volumes:
dbdata:
networks:
default:
driver: bridge常见书写错误
| 错误 | 表现 | 处理 |
|---|---|---|
| 缩进不一致 | 解析报错，指向的行号未必准确 | 统一两个空格并逐层核对 |
| 用了制表符 | 直接报错无法解析 | 替换为空格 |
| 同层出现重复键 | 后一个覆盖前一个且不报错 | 靠校验命令发现，人工核对服务定义 |
| 键名拼写错误 | 该字段被忽略，容器按默认行为运行 | 与参考文档核对字段名 |
| 变量未定义 | 替换结果为空，配置悄悄变形 | 给变量提供默认值或先确认变量已设置 |
组织文件的建议
- 服务按角色分组书写，数据库、缓存、应用、网关依次排列，便于阅读
- 公共配置用锚点或片段复用，减少重复字段带来的不一致
- 环境差异集中到变量文件，主文件保持稳定
- 密钥与口令不写进主文件，用变量或专用密钥对象承载
- 文件顶部写清用途与最近变更，交接时成本更低
解析不报错不代表字段有效：拼错的字段会被直接忽略，容器按默认值运行。改完文件后用校验命令看最终解析结果，比只看文件内容可靠。
同一层级的重复键不会报错，后写的会静默覆盖前面。服务定义较长时，用校验命令输出的最终结果做一次通读，能发现这类隐患。