docker compose で env_file が読み込まれない

要約

Compose の env は 2 系統ある。
プロジェクト直下の .env は YAML 内 ${VAR} の補間用、env_file: と environment: は コンテナに渡す用。
混同すると「YAML 上は正しいのにコンテナ内で空」になる。

よくある原因

1. 役割の混同: ${IMAGE_TAG} を展開したいのに env_file: に書いている。
2. 上書き: environment: で書いた DEBUG=false が env_file: の DEBUG=true を勝ち抜く。
3. ディレクトリ違い: compose.yml のあるディレクトリではなく親で docker compose up している。
4. export 付き: Bash 流に export FOO=bar と書くと Compose は警告を出し、KEY=VALUE 部分しか拾わない場合がある。
5. クォート問題: PASSWORD="a b" のような引用符はそのまま値の一部になる（外す必要がある）。

解決策

1. 用途で書く場所を分ける

# compose.yml
services:
  app:
    image: myapp:${TAG}          # .env の TAG を補間
    env_file: .env.app           # コンテナ内で読みたい値
    environment:
      LOG_LEVEL: debug           # 個別上書き

2. 優先順位を理解する

公式ドキュメント に明記された順:

1. docker compose run -e 引数
2. environment:
3. env_file:
4. shell 環境変数
5. プロジェクト直下の .env
6. Dockerfile の ENV

下位は上位で上書きされる。

3. .env の書式は KEY=VALUE のみ

# OK
DB_HOST=localhost
DB_PORT=5432
 
# NG（export は付けない）
export DB_USER=admin

4. config サブコマンドで展開後を確認

docker compose config

${VAR} が解決済みの YAML が表示される。
空欄や ${TAG} のまま残っていれば .env が読まれていない。