拆分含锚点与片段的docker-compose文件后运行报错，求解决方法

问题描述 #

现有包含YAML锚点和片段的大型docker-compose文件，拆分后启动报错：unknown anchor 'source-bin' referenced。拆分结构如下：

common.yml（公共片段）：

version: '3'

x-common-repo-volumes:
 - &source-bin /path/lib/:/work/lib/
 - ...
 - ...

main.yml（服务内容）：

services:    
  foobar:
    image: ...
    volumes:
      - *source-bin
      - ...
      - ...

启动命令：

docker compose -f common.yml -f main.yml up -d

原因分析 #

YAML锚点&和引用*的作用域仅限单个文件。Docker Compose处理多个-f参数时，会先独立解析每个YAML文件，再合并配置结果。这意味着common.yml中定义的&source-bin锚点，在解析main.yml时完全不可见，因此触发“未知锚点”错误。

解决方法 #

方法1：使用extends关键字（官方推荐） #

将公共配置封装为基础服务，其他服务通过extends继承公共配置，同时可添加自定义内容：

修改common.yml：

version: '3'
services:
  # 定义基础服务，包含公共卷配置
  base-service:
    volumes:
      - /path/lib/:/work/lib/
      - ... # 其他公共卷

修改main.yml：

version: '3'
services:
  foobar:
    image: your-image:tag
    extends:
      file: common.yml
      service: base-service
    # 添加当前服务专属配置
    volumes:
      # 额外卷会与基础服务的卷自动合并
      - /path/custom:/work/custom
    ports:
      - "8080:80"

启动命令保持不变：

docker compose -f common.yml -f main.yml up -d

方法2：合并YAML文件后再启动（保留锚点语法） #

如果需要保留原有的锚点/片段语法，可先用工具合并所有YAML文件，再交给Docker Compose处理。推荐使用yq工具：

1. 安装yq（根据系统选择对应安装方式）
2. 合并文件：

yq eval-all '. as $item ireduce ({}; . * $item)' common.yml main.yml > merged.yml

3. 用合并后的文件启动：

docker compose -f merged.yml up -d

方法3：使用扩展字段直接嵌入 #

将公共片段定义为Docker Compose扩展字段（前缀x-），在服务配置中直接引用整个字段内容：

common.yml：

version: '3'
x-common-repo-volumes:
  - /path/lib/:/work/lib/
  - ... # 其他公共卷

main.yml：

version: '3'
services:
  foobar:
    image: your-image:tag
    volumes:
      # 直接引入公共卷列表
      - /path/lib/:/work/lib/
      - ... # 同步公共卷内容
      - /path/custom:/work/custom

注：此方法需手动同步公共片段内容，适合片段较少的场景。

内容的提问来源于stack exchange，提问作者Mojtaba Kamyabi