Docker Composeで環境変数が反映されない原因と対処法｜.env・env_file・environmentの違い

Byinfosugars

Docker Composeで環境変数が反映されない原因

Docker Composeでアプリケーションを起動したとき、.envに設定した値がコンテナ内で取得できないことがあります。

たとえば、データベースの接続先やアプリケーションの実行モードを.envで指定したのに、コンテナ内では値が空になっていたり、以前の設定が使われたりするケースです。

この問題は、.envとenv_fileの役割を混同している場合や、environmentとの優先順位、コンテナの再作成が関係していることがあります。

まずは、次の3つを区別しておきましょう。

  • .env：Docker Composeファイル内の変数を置き換えるために使う
  • env_file：ファイルに記載した環境変数をコンテナに渡す
  • environment：Composeファイル内でコンテナの環境変数を指定する

同じ環境変数を扱う設定でも、役割は異なります。

.envとenv_fileの違い

特に間違えやすいのが、.envとenv_fileの違いです。

.envはComposeファイル内の変数を置き換える

プロジェクトディレクトリに.envを作成し、次のように記述したとします。

APP_MODE=production
APP_PORT=8080

このファイルを作成しただけでは、変数が自動的にコンテナ内へ渡されるわけではありません。

Composeファイル側で変数を参照する必要があります。

services:
  app:
    image: nginx:latest
    environment:
      APP_MODE: ${APP_MODE}
      APP_PORT: ${APP_PORT}

このように設定すると、Composeが.envの値を読み取り、コンテナの環境変数として設定します。

env_fileはコンテナに環境変数を渡す

一方、env_fileは指定したファイルの環境変数をコンテナに渡すための設定です。

APP_MODE=production
APP_PORT=8080

このファイルをapp.envという名前で保存した場合、Composeファイルは次のようになります。

services:
  app:
    image: nginx:latest
    env_file:
      - ./app.env

env_fileに指定したファイルのパスは、原則としてComposeファイルの場所を基準に解決されます。

.envと違い、env_fileはコンテナへ渡す環境変数を指定するために使います。

どちらを使うかは、設定ファイルの構成や管理方法に合わせて選びましょう。

環境変数が反映されないときの確認方法

原因を特定するには、いきなりコンテナを削除するのではなく、設定ファイルと実際のコンテナの状態を順番に確認するのがおすすめです。

1. Composeファイルの設定を確認する

最初に、Docker Composeが読み込んでいる設定を確認します。

docker compose config

このコマンドは、Composeファイルの変数置換などを反映した設定を表示します。

たとえば、次のように表示された場合は、環境変数の値がComposeの設定に反映されています。

services:
  app:
    environment:
      APP_MODE: production
      APP_PORT: "8080"

ここで値が空になっていたり、想定と違う値になっていたりする場合は、.envの読み込み場所や変数名、シェル側の環境変数などを確認してください。

なお、docker compose configの出力にはパスワードやトークンなどの機密情報が含まれる可能性があります。公開サイトや第三者にそのまま貼り付けないようにしましょう。

2. Composeが読み込んでいる変数を確認する

.envの値が正しく読み込まれているか確認したい場合は、次のコマンドを使います。

docker compose config --environment

Composeファイルの変数置換に使用される環境変数を確認できます。

ここに想定している変数が表示されない場合は、次の点を確認してください。

  • .envが正しいディレクトリにあるか
  • ファイル名が.envになっているか
  • 変数名のスペルが一致しているか
  • --env-fileで別のファイルを指定していないか
  • シェル側に同じ変数名が設定されていないか

特に、別のディレクトリからComposeを実行している場合は、.envの読み込み場所に注意が必要です。

3. コンテナ内に環境変数が存在するか確認する

Composeファイルの設定が正しくても、実際のコンテナに環境変数が渡されているとは限りません。

起動中のコンテナで次のコマンドを実行します。

docker compose exec app printenv APP_MODE

appはComposeファイルに記載したサービス名に置き換えてください。

設定した値が表示されれば、コンテナ内で環境変数を取得できています。

複数の環境変数をまとめて確認したい場合は、次のようにします。

docker compose exec app printenv

ただし、このコマンドではパスワードやAPIキーなども表示される可能性があります。出力内容の取り扱いには注意してください。

4. environmentとenv_fileの優先順位を確認する

同じ環境変数を複数の場所に設定していると、意図しない値が使われることがあります。

Docker Composeでは、コンテナ内の環境変数について、設定元によって優先順位が決まっています。

主な優先順位は次のとおりです。

優先順位設定元
高いdocker compose run -eで指定した値
2シェル環境や.envなどから置換されたenvironment・env_file
3Composeファイルのenvironment
4Composeファイルのenv_file
低いDockerfileのENV

たとえば、次のような設定があるとします。

services:
  app:
    image: nginx:latest
    env_file:
      - ./app.env
    environment:
      APP_MODE: production

app.envに次の値が書かれていても、

APP_MODE=development

コンテナ内で使われる値はenvironmentに指定したproductionになります。

複数の場所に同じ変数を設定している場合は、どの設定が優先されているか確認しましょう。

5. 環境変数を変更した後にコンテナを再作成する

.envやComposeファイルを変更したのに、コンテナ内の値が変わらない場合は、コンテナが以前の設定で動いている可能性があります。

設定変更後は、次のコマンドで対象サービスを再作成できます。

docker compose up -d --force-recreate app

appは対象のサービス名に置き換えてください。

再作成後、もう一度環境変数を確認します。

docker compose exec app printenv APP_MODE

変更後の値が表示されれば、設定が反映されています。

ただし、再作成によってアプリケーションの再起動が発生します。稼働中のサービスで実行する場合は、停止の影響を確認してから作業してください。

よくある原因と対処法

ここまでの確認内容を、原因別に整理します。

原因確認・対処方法
.envを作成しただけComposeファイルで${VARIABLE}を参照する
env_fileの指定ミスファイル名とパスを確認する
environmentが優先されている同じ変数が複数箇所にないか確認する
シェルの変数が優先されている実行環境の変数を確認する
古いコンテナが動いている対象サービスを再作成する
変数名が一致していない大文字・小文字やスペルを確認する
変数が空になっているdocker compose configで置換結果を確認する

特に多いのは、.envをコンテナ内に自動で渡されるファイルだと思い込んでしまうケースです。

まずは.envとenv_fileの役割を区別すると、原因を絞り込みやすくなります。

パスワードやAPIキーを環境変数に保存するときの注意点

データベースのパスワードやAPIキーなどを環境変数で管理する場合は、情報の取り扱いにも注意が必要です。

環境変数は便利ですが、設定内容やコンテナの情報を確認する操作によって、値が表示される場合があります。

たとえば、次のような情報をGitHubなどの公開リポジトリに含めないようにしてください。

  • データベースのパスワード
  • APIキー
  • アクセストークン
  • 外部サービスの認証情報

.envを使う場合は、Git管理の対象から除外する方法も検討しましょう。

また、Docker公式ドキュメントでは、パスワードなどの機密情報を環境変数で渡すのではなく、Docker Secretsを利用する方法も案内されています。

本番環境で重要な認証情報を扱う場合は、Secretsなどの仕組みを検討するとよいでしょう。

まとめ

Docker Composeで環境変数が反映されない場合は、.env、env_file、environmentの役割と優先順位を確認することが大切です。

確認するときは、次の順番で進めると原因を特定しやすくなります。

  1. docker compose configで設定内容を確認する
  2. docker compose config --environmentで変数の読み込み状態を確認する
  3. docker compose execでコンテナ内の値を確認する
  4. environmentとenv_fileの優先順位を確認する
  5. 必要に応じて対象コンテナを再作成する

.envに値を書いただけでは、必ずしもコンテナ内の環境変数になるわけではありません。

設定ファイルの役割を理解し、Composeが読み込んだ値とコンテナ内で実際に使われている値を分けて確認することが、トラブル解決への近道です。

類似投稿