Docker Compose 改了環境變數沒生效？restart 不會重建容器

restart 為什麼不會讀回新設定？#

Container 建立時，Compose 會把 environment 或 env_file 的值寫進該 container 的執行設定。restart 只停止並重新啟動這個既有 container，不會重新建立一份新的設定。

例如：

1
services:
2
  web:
3
    image: alpine:3.22
4
    command: ['sh', '-c', 'while true; do sleep 3600; done']
5
    environment:
6
      APP_MODE: ${APP_MODE:?請先設定 APP_MODE}

第一次以 APP_MODE=staging 建立 container 後，即使你把 .env 改成 APP_MODE=production，下面的指令也不會把新值寫進既有 container：

1
docker compose restart web
2
docker compose exec web printenv APP_MODE

restart 適合處理程序卡住、需要重新載入已存在的 runtime 設定，或只想重啟服務的情境；它不是設定變更的部署指令。

先看 Compose 實際解析到什麼值#

在重建前，先確認你執行命令的工作目錄、Compose 檔案與環境檔都和正式流程相同：

1
docker compose config --environment
2
docker compose config
3
docker compose ps

docker compose config --environment 會列出 Compose 用來做插值的環境；docker compose config 則會 render 出準備送給 Docker Engine 的 model。兩個輸出都可能包含敏感資料，CI log 只保留非敏感欄位。

如果你把 env_file 與 ${VAR} 混在同一份設定裡，先看 Docker Compose 的 env_file 與變數插值差異。service 的 env_file 是提供 container runtime environment，.env、shell 或 CLI --env-file 則可能是 Compose 解析 ${VAR} 的來源。

用 up 重新建立 container#

1
docker compose up -d web

1
docker compose up -d --force-recreate web

1
docker compose up -d --build --force-recreate web

新值仍沒出現時，沿著這四層檢查#

1. Compose 來源：shell、CLI --env-file、project .env 與 service env_file 不是同一層，優先順序也不同。
2. 實際 service：確認你重建的是正確的 project、service 名稱與 -f 檔案組合。
3. container 值：用 docker compose exec web printenv APP_MODE 看 container 真正拿到什麼，而不是只看主機上的 .env。
4. 程式啟動時機：有些程式只在 process 啟動時讀取環境變數；container 已重建後，才算讓程式重新取得新值。

不要為了更新環境變數直接執行 docker compose down -v。-v 會移除 volume，資料庫或上傳檔案可能因此失去可還原的儲存。設定變更通常只需要針對正確 service 執行 up 和 recreate。

run -e 不是 service 的長期設定#

docker compose run -e 適合一次性的 command 或 migration，不會改寫 compose.yaml，也不會更新已經由 up 建立的 service container：

1
docker compose run --rm -e APP_MODE=maintenance web sh -c 'printenv APP_MODE'

若你要讓下一次部署仍使用同一個值，應把來源放在清楚的 Compose 設定或指定的 --env-file，再用 config 和 up 驗證。不要把一次性的 run 結果當成 service 已經換環境。

常見問題#