Next.js で環境変数 (process.env) が読み込めない

要約

Next.js の環境変数はサーバ側とブラウザ側で扱いが違う。
ブラウザに渡したい値は NEXT_PUBLIC_ プレフィックス必須で、付け忘れると process.env.FOO は undefined になる。
.env.local を変更した後は dev サーバの再起動が必要、本番ビルド時はビルド実行シェルに値があることを確認する。
仕様は Environment Variables に明記されている。

よくある原因

1. NEXT_PUBLIC_ 付け忘れ: ブラウザに露出させる値は明示的に NEXT_PUBLIC_ を付ける必要がある。
   付けない値はクライアント側で undefined
2. dev サーバ未再起動: .env* ファイルはプロセス起動時に読み込まれる。
   編集後は Ctrl+C で停止して再起動しないと反映されない
3. ビルド時に未定義: next build の時点で値が無いと、その値は undefined としてバンドルされ、実行時の env を変えても上書きされない
4. ファイル優先順位の誤解: .env.production.local > .env.local > .env.production > .env の順で読まれる。
   上位ファイルで意図せず空文字を入れていないか確認

解決策

1. NEXT_PUBLIC_ プレフィックスを付ける

# .env.local
DATABASE_URL=postgres://...           # サーバ専用
NEXT_PUBLIC_API_URL=https://api.example.com   # クライアントから参照可

// app/page.tsx (Server Component なら両方読める)
console.log(process.env.DATABASE_URL);
 
// app/components/Client.tsx ("use client")
console.log(process.env.NEXT_PUBLIC_API_URL);   // OK
console.log(process.env.DATABASE_URL);          // undefined

2. dev サーバを再起動

# Ctrl+C で止めて
npm run dev

ホットリロードは .env* の変更を検出しない。

3. 本番ビルドのシェルで export

export NEXT_PUBLIC_API_URL=https://api.example.com
export DATABASE_URL=postgres://...
npm run build

CI ではビルドステップの環境に値を渡す。
Vercel / Cloud Run / Amplify などは UI で設定する。

4. ファイル優先順位を確認

.env.development.local   ← dev 時のローカル上書き（git ignore 推奨）
.env.development         ← dev のデフォルト
.env.local               ← 全環境のローカル上書き（git ignore 推奨）
.env                     ← ベース

複数ファイルがある場合、上のファイルの値が下を上書きする。
空文字を書くと「未設定」ではなく「空文字」になるので注意。