Docker Compose extends 如何复用服务配置片段

Docker Compose 的 extends 适合解决“多个服务共用一组配置，但启动命令和端口不同”的问题。把公共部分放到一个 Compose 片段，再在主文件中选择服务继承并覆盖，最后用 docker compose config 看展开后的模型，就能避免凭感觉判断 YAML 是否生效。

官方地址：https://docs.docker.com/compose/

extends 只会继承指定服务的配置，不会自动把它依赖的网络、卷、数据库或其他服务带入当前项目；这些资源必须在最终 Compose 模型中显式声明。

第1步：准备可复用的公共服务片段

先在项目目录建立 common.yaml，把镜像、构建目录、环境变量等稳定配置集中起来。这个文件可以是只服务于继承的片段，不必单独承担完整项目的启动职责。

services:
  app-base:
    build: .
    working_dir: /workspace
    environment:
      APP_ENV: development
      LOG_LEVEL: info
    volumes:
      - .:/workspace
    # 这里只放多个服务都会使用的公共配置

编辑器中的入口路径是“项目文件夹 → common.yaml → services → app-base”。先确认服务名是 app-base，后面 extends.service 必须逐字匹配。

第2步：用 extends 生成不同的具体服务

打开主文件 compose.yaml，在目标服务下选择“Compose 文件 → services → 具体服务 → extends”。其中 file 是公共片段路径，service 是被继承的服务名。下面让 Web 服务和后台 worker 共用 app-base，但分别覆盖启动命令。

services:
  web:
    extends:
      # 从同目录片段中选择 app-base 服务
      file: common.yaml
      service: app-base
    command: ./bin/web
    ports:
      - "8080:8080"
    depends_on:
      - db

  worker:
    extends:
      # worker 复用同一组构建、环境和卷配置
      file: common.yaml
      service: app-base
    command: ./bin/worker
    depends_on:
      - db

  db:
    image: postgres:16
    # 依赖的实际服务必须在当前模型中显式声明

此时检查三件事：service 是否与片段中的名称一致，覆盖项是否位于具体服务下，以及 db 是否真的声明在当前文件。继承不会自动把 db 创建出来。

第3步：用 config 查看合并后的结果

不要直接运行 up 来猜配置。进入主文件所在目录，点击终端中的“项目目录 → 校验 → 展开 Compose 模型”，对应命令是：

# 在 compose.yaml 所在目录输出 Compose 合并后的模型
docker compose -f compose.yaml config

输出中应能看到 web 继承了 build、working_dir、环境变量和卷，同时保留自己的 command: ./bin/web 与端口；worker 则显示自己的命令。若文件路径位于其他目录，优先把相对路径按主文件的位置核对，避免片段移动后仍指向旧位置。

第4步：补齐依赖并确认 extends 的使用边界

如果被继承服务引用了网络、卷、配置、密钥或其他服务，主文件要逐项补齐。可以把验收清单放在提交前：

还要避免循环继承：A 继承 B、B 又继承 A 时，Compose 会报错。若团队需要导入完整的另一个 Compose 应用，应该另行评估 include；本题的 extends 只针对“选择一个服务并复用其配置”。

常见问题

extends 能让 common.yaml 里的原服务也自动启动吗？

不能。跨文件继承时，当前文件只得到被选择服务的配置；要启动原服务，必须在主文件中另外声明它。

为什么 config 里看不到我以为会出现的数据库？

因为依赖关系不会自动导入资源。把数据库服务、网络或卷显式写进当前 Compose 文件，再运行 config 检查最终模型。

extends 和 YAML 锚点该怎么选？

同一文件内复用少量字段时锚点更直接；需要从另一个文件选择完整服务配置并允许覆盖时，extends 更贴合这个边界。