Docker Compose include 怎麼拆檔：先釐清路徑、變數與名稱衝突

最小拆分方式#

先把基礎服務放進 infra/compose.yaml，主專案只保留應用程式與 include：

1
include:
2
  - path: ./infra/compose.yaml
3

4
services:
5
  web:
6
    build: .
7
    depends_on:
8
      redis:
9
        condition: service_healthy

1
services:
2
  redis:
3
    image: redis:7-alpine
4
    healthcheck:
5
      test: ["CMD", "redis-cli", "ping"]
6
      interval: 5s
7
      timeout: 3s
8
      retries: 5

載入後，web 可以直接依賴 redis；不需要把 service 再複製回主檔。這與 extends 的用途不同：include 匯入整份 Compose application，extends 則是讓某個 service 繼承另一個 service 的設定。

最容易錯的是相對路徑#

短寫法會以被 include 檔案所在資料夾作為預設 project directory。因此 infra/compose.yaml 裡的 build: .、bind mount 路徑與預設 .env 都是相對於 infra/，不是根目錄。

需要明確指定時，改用長寫法：

1
include:
2
  - path: ./infra/compose.yaml
3
    project_directory: .
4
    env_file:
5
      - ./infra/defaults.env

這不是「把所有環境變數集中」的捷徑。被 include 檔案的預設值可由主專案的環境覆寫；部署前仍應列出實際生效的值，避免 development 的 host、port 或 credential 名稱被意外帶到 production。

名稱衝突不會自動合併#

include 完成後，Compose 會把資源帶入目前的 application model。若兩份檔案定義同名 resource，Compose 會顯示警告，而不是替你猜要怎麼 merge。這正是拆檔前要先定義所有權的原因：

不要把同一個 redis 同時放在主檔與 infra 檔，再期待後讀取的設定贏得不透明的合併規則。

用 render 結果驗證，而不是只看 YAML#

每次拆檔後，先在 repository root 執行：

1
docker compose config
2
docker compose up -d
3
docker compose ps

第一個指令會輸出 Compose 解析後的 model，最適合確認 service 是否真的載入、路徑是否正確與變數是否被插值。之後再用 ps 檢查 healthcheck；只有 YAML 能通過不代表服務間真的能連線。

若你是把既有自架服務拆成多份 Compose，升級前的備份與還原邊界仍要先確認，可搭配 Dify 升級前的 Docker Compose 備份檢查 一起看。

參考資料：

Docker Docs：Use include to modularize Compose files

Docker Docs：How Compose works