Docker Compose 的 env_file 與 ${VAR} 怎麼分？解決變數插值為空

env_file 和 --env-file 的工作位置不同#

env_file 是 service 的設定，不會在 Compose 已經解析 image、volume、port 或 build argument 之後回頭補值。這也是為什麼只改 runtime.env，卻看不到 image: "my-web:${IMAGE_TAG}" 改變。

先重現「容器有值、model 沒值」的情境#

下面的設定把兩個階段放在一起，正好能看出問題：

1
services:
2
  web:
3
    env_file:
4
      - ./runtime.env
5
    image: "my-web:${IMAGE_TAG}"

runtime.env 可以讓 web container 在啟動後讀到 IMAGE_TAG，但 Compose 要先在建立 application model 時解析 image。若執行指令的 shell、CLI --env-file 或 project .env 沒有 IMAGE_TAG，${IMAGE_TAG} 可能被警告後替換成空字串。

用 .env 或 --env-file 提供插值來源#

1
IMAGE_TAG=2026.08
2
PUBLIC_ORIGIN=https://example.com

1
services:
2
  web:
3
    image: "my-web:${IMAGE_TAG}"
4
    environment:
5
      PUBLIC_ORIGIN: "${PUBLIC_ORIGIN}"

1
IMAGE_TAG=2026.08-rc1
2
PUBLIC_ORIGIN=https://staging.example.com

1
docker compose --env-file ./config/.env.ci config
2
docker compose --env-file ./config/.env.ci up -d

需要值時，用 required expression 讓它提早失敗#

如果空字串會產生無效 image、錯誤 host path 或連錯資料庫，不要讓錯誤拖到 container 啟動後才出現：

1
services:
2
  web:
3
    image: "my-web:${IMAGE_TAG:?請先設定 IMAGE_TAG}"
4
    environment:
5
      PUBLIC_ORIGIN: "${PUBLIC_ORIGIN:?請先設定 PUBLIC_ORIGIN}"

需要預設值時才使用 :-：

1
services:
2
  web:
3
    environment:
4
      LOG_LEVEL: "${LOG_LEVEL:-info}"

${VAR:-default} 會把未設定或空字串都視為缺少；${VAR?error} 只檢查是否已設定。選擇哪一種，要看空值是否與你的部署契約相容。

先看 Compose 真正使用的值#

不要直接把完整設定檔倒進 CI log，因為解析後的 model 可能包含密碼或連線字串。先看插值環境，再針對非敏感欄位檢查：

1
set -euo pipefail
2

3
docker compose --env-file ./config/.env.ci config --environment
4
docker compose --env-file ./config/.env.ci config > /tmp/compose.resolved.yaml
5
rg 'image:|PUBLIC_ORIGIN:|LOG_LEVEL:' /tmp/compose.resolved.yaml

docker compose config --environment 會列出 Compose 用來插值的環境；docker compose config 則輸出解析後的 model。兩個指令要和 CI 使用相同的工作目錄、-f 檔案與 --env-file 參數，否則你驗證的是另一份設定。

若設定拆在多個 Compose application，先參考 Compose include 的相對路徑、變數與名稱衝突。若問題是 app 太早連資料庫，則看 healthcheck 與 service_healthy 的啟動順序；那是服務就緒問題，不是變數插值問題。

不要把 Compose CLI 行為套到 Swarm#

Docker 官方文件特別註明，.env 的 substitution 是 Docker Compose CLI 的功能，docker stack deploy 不支援同一套插值行為。若最後部署入口是 Swarm，請用實際的 stack deploy 路徑測試，不要因為 docker compose config 成功就推論另一個命令也會得到相同 model。

結論是：用 .env、--env-file 或 shell 解決 ${VAR}；用 service env_file 提供 container 的 runtime environment。把這兩層拆開，再用 config --environment 和 config 驗證，Compose 的空 image tag 通常就能在啟動前被抓出來。

常見問題#