在多服务项目中，Docker Compose 配置很容易出现大量重复内容：相同的重启策略、日志参数、环境变量、网络设置和健康检查被复制到多个服务。一旦公共配置发生变化，逐项修改不仅耗时，还可能造成环境不一致。借助 YAML 锚点、别名、合并键以及 Compose 扩展字段，可以将重复配置提取为可复用片段，让 compose.yaml 更简洁、更易维护。🧩
一、先理解四个核心概念
锚点使用 &名称 标记一个 YAML 节点，相当于为这段配置起名；别名使用 *名称引用已定义的节点；合并键使用 << 将映射内容合并到当前位置；扩展字段则以 x- 开头，用于存放 Compose 不直接执行的自定义配置片段。
例如，&service-defaults 定义公共服务配置，*service-defaults 表示引用它，而 <<: *service-defaults 表示把这段映射合并到当前服务。Docker 官方将锚点与别名归入 Compose fragments，并建议结合扩展字段组织跨服务的公共配置。详细语义可参考 Compose Fragments 官方文档。
二、基础实战：复用服务公共配置
假设 web、api 和 worker 都需要相同的重启策略、日志限制及网络配置，可以先定义一个扩展字段：
x-service-defaults: &service-defaults
restart: unless-stopped
logging:
driver: json-file
options:
max-size: "10m"
max-file: "3"
networks:
- backend
services:
web:
<<: *service-defaults
image: nginx:alpine
api:
<<: *service-defaults
image: example/api:latest
worker:
<<: *service-defaults
image: example/worker:latest
x-service-defaults 不会被当成实际服务启动，但它承载的映射可以通过锚点被多个服务合并。这样，修改日志轮转参数或网络名称时，只需调整公共片段即可。Compose 会忽略以 x- 开头的扩展字段，这也是扩展字段适合保存复用模板的重要原因，相关规则见 Extensions 官方说明。♻️
三、局部覆盖：公共默认值与服务差异并存
配置复用并不意味着所有服务必须完全相同。合并公共映射后，可以在当前服务中重新声明同名键。例如，大多数服务使用 unless-stopped，但一次性任务希望失败后不重启：
services:
migrate:
<<: *service-defaults
image: example/migrate:latest
restart: "no"
这里的 restart 会覆盖公共片段中的值。建议把 << 合并语句放在服务配置前部，再在后面排列差异项，使阅读者能够快速区分“继承了什么”和“修改了什么”。覆盖嵌套对象时要格外谨慎：YAML 合并并不是自动递归的深合并，如果重新声明 logging，通常需要完整写出希望保留的子项，否则可能丢失公共配置中的部分内容。
四、环境变量应使用映射形式
环境变量既可以写成列表，也可以写成键值映射，但需要通过 << 合并时，应选择映射形式，因为 YAML 合并键只适用于映射，不能直接合并序列。✅
x-common-env: &common-env
TZ: Asia/Shanghai
LOG_LEVEL: info
APP_MODE: production
services:
api:
image: example/api:latest
environment:
<<: *common-env
HTTP_PORT: "8080"
worker:
image: example/worker:latest
environment:
<<: *common-env
LOG_LEVEL: warn
api 在公共变量基础上增加 HTTP_PORT，worker 则覆盖 LOG_LEVEL。若使用“- KEY=value”列表写法，就无法利用映射合并实现这种增补与覆盖。涉及端口、布尔值或可能被 YAML 自动转换的内容时，使用引号通常更稳妥。
五、组合多个扩展片段
当一个公共模板包含环境变量、日志、健康检查、资源配置等所有内容时，模板容易变得臃肿。更实用的方式是按职责拆分，例如 x-logging、x-healthcheck 和 x-environment，再根据服务需要选择性组合：
x-logging: &logging
driver: json-file
options:
max-size: "10m"
x-healthcheck: &healthcheck
interval: 30s
timeout: 5s
retries: 3
services:
api:
image: example/api:latest
logging: *logging
healthcheck:
<<: *healthcheck
test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
这种“小片段组合”比单一巨型模板更灵活，也能降低无关配置相互影响的风险。锚点名称应体现用途，例如 common-env、default-logging，而不要使用 config1、temp 等含义模糊的名称。🔧
六、常见误区与排查方法
- 把合并键用于列表：ports、volumes、depends_on 的列表形式不能通过 << 直接拼接，应整体引用列表，或改用适合的映射结构。
- 误认为支持深度继承：覆盖嵌套映射时，要检查子项是否被整体替换；复杂配置可继续拆分锚点。
- 尝试动态生成锚点名：锚点解析早于 Compose 的变量插值，因此不能使用环境变量动态决定锚点或别名名称。
- 跨文件引用锚点：锚点属于单个 YAML 文档，不应把一个文件中的锚点直接交给另一个文件引用；多文件场景应使用 Compose 的文件合并机制。
- 只检查语法，不检查最终模型：运行 docker compose config 展开并校验配置，重点核对环境变量、端口、卷、健康检查和覆盖结果。
七、适合团队落地的实践规范
- 优先提取至少被两个服务共同使用且相对稳定的配置。
- 扩展字段统一放在文件前部，并使用 x-业务含义 的命名方式。
- 公共片段保持单一职责，避免建立层级过深的“配置继承树”。
- 密钥和密码只保留变量引用，不要直接写入锚点或提交到仓库。
- 在持续集成流程中执行 docker compose config，及早发现解析和覆盖问题。
总结
Docker Compose 配置复用的关键思路是：用 & 定义锚点，用 * 引用节点，用 << 合并映射，再用 x- 扩展字段集中存放公共片段。它尤其适合统一日志、环境变量、重启策略和健康检查，但不能把合并键当作深度继承或列表拼接工具。合理拆分、显式覆盖并检查最终展开结果，才能在减少重复的同时保持配置清晰可靠。🚀
