include 解决什么
较新的 Compose V2 支持顶层 include：把网络、监控、日志等公共定义拆到独立文件后引入，多个项目共享同一份基础编排。被 include 的文件与主文件合并成同一个项目，最终结果可以用 compose config 展开核对。
基本信息
| 字段 | include: [路径…] 或 [{path: …}] |
|---|---|
| 路径语义 | 相对引用方编排文件所在目录 |
| 支持版本 | 较新的 Compose V2 |
| 核对方式 | docker compose config 展开查看 |
| 合并结果 | 进入同一项目命名空间 |
典型使用场景
- 多项目共享网络、日志、监控等基础定义，避免复制粘贴
- 公共片段由平台团队维护，业务团队只写自己的服务
- 迁移期渐进拆分庞大的单文件编排
- 跨目录复用：把上级目录的公共编排引入当前项目
- 基础文件加环境叠加文件组合出不同环境的编排
Compose 写法示例
Compose 写法示例
include:
- path: ./infra/compose.network.yaml # 公共网络定义
- path: ../shared/compose.monitoring.yaml # 上级目录的监控片段
services:
api:
image: app/api:1.4.2 # 本项目自己的服务核对合并结果
核对合并结果
docker compose config | head -40 # 展开 include 后的最终编排
docker compose config --services # 确认服务清单与预期一致
docker compose up -d # 确认无误后再启动使用要点
| 要点 | 说明 | 注意 |
|---|---|---|
| 路径基准 | 相对引用方编排文件目录 | 跨目录时容易算错 |
| 命名空间 | 合并进同一项目 | 服务重名会冲突 |
| 嵌套 | 被包含文件可再有 include | 层数过深难以排查 |
| 版本要求 | 需较新的 Compose V2 | 旧版本不支持 |
被 include 的文件里的服务会进入同一个项目命名空间，服务重名会冲突；拆分时给公共片段的服务起有区分度的名字。
老版本 Compose 不支持 include，团队内版本基线要先统一，否则同一份编排在不同机器上行为不一致。
被包含的文件可以继续有自己的 include，但层数过深会让排障困难；一般控制在两层以内，并以 config 展开结果作为唯一事实来源。
include 只做文件级复用，不改变服务归属；需要按环境覆盖同一个服务时仍要用覆盖文件或 profiles，两种机制混用容易看不清最终结果。