Docker Compose profiles 怎麼用：把本機除錯工具與正式服務分開啟動

把核心服務維持在預設路徑#

1
services:
2
  app:
3
    build: .
4
    ports: ['3000:3000']
5

6
  mailpit:
7
    image: axllent/mailpit
8
    profiles: ['mail']
9
    ports: ['8025:8025']
10

11
  adminer:
12
    image: adminer
13
    profiles: ['db-ui']
14
    ports: ['8080:8080']

不含 profiles 的 app 會一直在預設 application model 內。要開郵件測試工具時：

1
docker compose --profile mail up

也可用 COMPOSE_PROFILES=mail,db-ui 啟動多個集合。指定某一個帶 profile 的 service，例如 docker compose run adminer，Compose 會啟用該 service 的 profile；但不要把這當成它會自動展開所有可選相依服務。

最容易踩到的是跨 profile 依賴#

Compose 不會因為某 service 引用了 depends_on、links、extends 或 service:... 形式的共用資源，就自動啟用被 profile 排除的 service。profile 組合讓引用的目標不存在時，Compose 會回報設定錯誤。

因此 app 若永遠需要 redis，兩者都不該拆進彼此不同、可任意關閉的 profile。反過來，只有 migration 時才需要的工具可以與核心 app 解耦，必要時用明確命令啟動。

1
# 看目前啟用 profile 後的完整設定，而不是只讀 YAML
2
docker compose --profile mail config
3

4
# 只檢查設定與 service 模型，不在背景留下容器
5
docker compose --profile mail config --services

profiles、include 與多份設定檔的分工#

profiles 適合「同一個 application 裡的可選 service」。若一組 service 有自己的 .env、路徑與維護責任，例如另一個團隊維護的監控 stack，使用 include 更清楚；可參考 Docker Compose include 拆檔的路徑與變數檢查。

若設定差異是正式環境不同 image tag、secret 或資源限制，應用部署環境的明確設定檔或平台變數，不要靠開或關 profile 偷渡 production 行為。這樣才能從命令列清楚重現「這次到底啟動了什麼」。

上線前的最小驗證#

1. 不帶 profile 執行 docker compose config --services，確認只有核心服務。
2. 每一個 profile 個別執行 config，確認沒有缺少相依服務。
3. 在 README 列出 profile 名稱、用途與需要的環境變數。
4. CI 若需啟動測試依賴，明確傳入 --profile，不要依賴開發者本機環境變數。

參考資料：

Docker Docs：Compose profiles

Docker Docs：docker compose CLI