.envファイルの適用順序を理解する（feat. NextJS）

一般的な.envファイルの構造

ほとんどのプロジェクトでは、様々な環境に合わせて複数の.envファイルを使用します。

• .env: すべての環境で共通して使用される基本的な環境変数
• .env.local: ローカル開発環境でのみ使用（バージョン管理から除外）
• .env.development: 開発環境で使用
• .env.development.local: 開発環境のローカル設定（バージョン管理から除外）
• .env.production: 本番環境で使用
• .env.production.local: 本番環境のローカル設定（バージョン管理から除外）
• .env.test: テスト環境で使用

.local接尾辞が付いたファイルは、開発者個人の設定を保存し、バージョン管理から除外するのが一般的です。

一般的な優先順位

一般的に、環境変数は次の順序で適用されます（フレームワークやライブラリによって異なる場合があります）：

1. OS環境変数
2. .env.[環境].local
3. .env.[環境]
4. .env.local
5. .env

Next.jsでの環境変数ロードの優先順位

Next.jsは環境変数をロードする際に、次のような明確な優先順位に従います：

1. .env.local: 最優先
2. .env.[MODE].local: 特定環境のローカル設定
3. .env.[MODE]: 特定環境の設定
4. .env: デフォルト設定

Next.jsのMODE値

Next.jsで[MODE]に入れることができる値：

• production: next startまたはnext build実行時に自動指定
• development: next dev実行時に自動指定
• test: next test実行時に自動指定

特定の環境ファイルを強制指定する

Next.jsでビルド時にproduction以外の環境の変数を使用したい場合は、env-cmdライブラリを活用できます。

# env-cmdのインストール
npm install env-cmd --save-dev

// package.json
"scripts": {
  "build:dev": "env-cmd -f .env.development.local next build"
}

# 実行
yarn build:dev

この方法は次のような状況で使用できます：

• ステージング環境用のビルド作成
• 開発環境設定でのテストビルド実行
• 特定の環境変数でのローカルテスト

注意事項

共通の注意事項

• .localファイルは.gitignoreに追加してバージョン管理から除外する
• 同じ変数名が複数のファイルにある場合、優先順位に従って値が決定される
• 機密情報は必ず.localファイルに保存する

Next.js特有の注意事項

• ブラウザに公開する必要がある環境変数にはNEXT_PUBLIC_接頭辞が必要
• .env.testファイルはテスト実行時にのみロードされる
• 環境変数は実行時に変更できない（ビルド時点で決定）

このように環境変数ファイルの優先順位を理解しながら、プロジェクトの状況に合わせて各環境に必要な設定を効果的に管理しましょう。