Docker Composeの環境変数管理｜.env・env_file・environment の違い

開発・ステージング・本番で設定値を切り替える——DBパスワード、API キー、接続先URL。Compose にはこれを扱う仕組みが3つあり、紛らわしい。この記事で違いと優先順位をはっきりさせます。

目次

1. 3つの仕組みの棲み分け
2. .env（プロジェクト変数）
3. env_file（サービスごとに読み込み）
4. environment（YAML直書き）
5. 優先順位（どれが勝つか）
6. 機密情報の扱い
7. 現場で使えるパターン
8. まとめ

1. 3つの仕組みの棲み分け

2. .env（プロジェクト変数）

compose.yml と同じディレクトリに置いた .env ファイルは Compose が自動で読み込み、YAML 内の ${VAR} を置換します。

2-1. 書式

# .env
DB_PASSWORD=s3cret
DB_PORT=5432
IMAGE_TAG=v1.2.3
COMPOSE_PROJECT_NAME=myapp   # 特殊変数：プロジェクト名自体を指定

# compose.yml
services:
  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: ${DB_PASSWORD}    # .env から展開
    ports:
      - "${DB_PORT}:5432"
  app:
    image: myapp:${IMAGE_TAG}              # タグを切り替え可能に

2-2. 展開を確認

$ docker compose config
services:
  app:
    image: myapp:v1.2.3
  db:
    environment:
      POSTGRES_PASSWORD: s3cret
    image: postgres:16
    ports:
      - published: "5432"

3. env_file（サービスごとに読み込み）

env_file: は、指定したファイルの中身をコンテナ内プロセスの環境変数として渡します。

# app.env
REDIS_URL=redis://cache:6379
LOG_LEVEL=info
FEATURE_FLAGS=new_ui,beta_api

# compose.yml
services:
  app:
    image: myapp
    env_file:
      - app.env           # 複数可
      - secrets.env

.env と env_file の違いをもう一度

4. environment（YAML直書き）

# 2通りの書き方（どちらでも同じ）

# マッピング形式
services:
  app:
    environment:
      LOG_LEVEL: info
      DEBUG: "false"
      DATABASE_URL: postgres://postgres:${DB_PASSWORD}@db:5432/postgres

# 配列形式
services:
  app:
    environment:
      - LOG_LEVEL=info
      - DEBUG=false
      - DATABASE_URL=postgres://postgres:${DB_PASSWORD}@db:5432/postgres

5. 優先順位（どれが勝つか）

同じ変数名が複数箇所で定義されたとき、強い順は以下。

6. 機密情報の扱い

DB パスワード等を environment: に書くと、次のリスクがあります：

• docker inspect で誰でも丸見え
• プロセスリストの中に出る可能性（言語・設定次第）
• コンテナログに誤って吐いてしまう事故が起きやすい

# 本番推奨：secrets を使う（6-2 の compose configs/secrets の応用）
services:
  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD_FILE: /run/secrets/db_password
    secrets:
      - db_password

secrets:
  db_password:
    file: ./secrets/db_password.txt

公式イメージは _FILE 付き環境変数をサポートしているものが多く（POSTGRES_PASSWORD_FILE, MYSQL_ROOT_PASSWORD_FILE, 等）、ファイル経由で安全に値を渡せます。

7. 現場で使えるパターン

パターンA：.env + environment（ミニマル）

# .env
DB_PASSWORD=s3cret

# compose.yml
services:
  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: ${DB_PASSWORD}

パターンB：環境別の env_file

# dev.env
LOG_LEVEL=debug
DATABASE_URL=postgres://postgres:dev@db:5432/devdb

# prod.env
LOG_LEVEL=warn
DATABASE_URL=postgres://app@prod-db:5432/appdb

# compose.yml（開発）
services:
  app:
    env_file:
      - dev.env

# 本番だけ別ファイル
docker compose --env-file prod.env up -d

パターンC：ホストの環境変数を透過（CI）

# GitHub Actions の secrets から渡す
services:
  app:
    environment:
      - DATABASE_URL        # ホストの DATABASE_URL を透過
      - API_KEY             # 同上

8. まとめ

参考リンク

• Environment variables in Compose（公式） — 3つの仕組みと優先順位の一次情報源。
• Use secrets in Compose（公式） — 機密情報の安全な扱い方。

Dockerの基礎を動画で体系的に学びませんか？

実務で使う基礎だけを3時間に凝縮。環境構築から丁寧に解説しています。

クーポン割引で講座を見る →