x-扩展字段通过锚点引用实现配置复用,支持环境变量、日志、健康检查等任意yaml结构,结合profiles可分环境精准启用。

用 x- 扩展字段能显著减少重复、提升可读性,关键不是“加字段”,而是把通用配置抽出来,再按需注入。
定义可复用的配置块
在文件顶层用 x- 开头声明配置片段,比如环境变量、日志设置或健康检查。Compose 会跳过这些字段,不报错也不执行,只当它们是“模板”。
- 必须以
x-开头,例如x-common-env、x-logging-defaults - 推荐命名带语义,如
x-healthcheck-prod比x-hc更易懂 - 支持任意合法 YAML 结构:字符串、列表、嵌套对象都行
用锚点 & 和别名 * 实现引用
单纯定义 x- 字段没用,得配合 YAML 锚点才能复用。先打标记(&name),再用 *name 引入,或者用合并语法 把整个结构“展开”到服务里。
-
x-common:&common environment: - NODE_ENV=production—— 定义并打锚点 web: —— 合并进服务,环境变量自动生效- 多个服务共用同一套配置,改一处,全部同步更新
组合复杂结构,不止于 environment
扩展字段不只是塞环境变量。你可以把卷挂载、部署约束、网络设置甚至 healthcheck 全部打包进去,一次定义,多处调用。
- 例如统一日志策略:
x-logging:&log logging: {driver: json-file, options: {max-size: 10m}} - 或标准化健康检查:
x-hc:&hc healthcheck: {interval: 30s, timeout: 5s},各服务再覆盖test命令 - 还能嵌套使用,比如一个
x-deploy-linux包含placement.constraints和resources
配合 profiles 做环境分层
扩展字段 + profiles 是管理多环境的黄金组合。把开发专用配置(如调试工具、宽松超时)放进 x-dev-config,再通过 profile 控制是否加载对应服务。
- 定义
x-dev-env:&dev environment: - DEBUG=true - LOG_LEVEL=debug - 服务中写
api: - 运行
docker compose --profile dev up,只有标记 dev 的服务才启用该配置











