Next.js で環境変数 (process.env) が読み込めない
Next.js の環境変数はビルド時にインライン化される。
ブラウザに露出する値は NEXT_PUBLIC_ プレフィックスが必須で、.env ファイルの優先順位とビルドの再実行も意識する必要がある。
公開: 更新:
grep -rl https://api.example.com .next/static
npm run build > build.log 2>&1 grep -E "Environments|Compiled successfully" build.log ✓ Compiled successfully in 3.9s
2026-11-08 に node:20(Next.js 15.5.29 / Node.js 20.20.2) で実際に打って取った出力。検証環境の詳細
要約
Next.js の環境変数はサーバ側とブラウザ側で扱いが違う。
ブラウザに渡したい値は NEXT_PUBLIC_ プレフィックス必須で、付け忘れると process.env.FOO は undefined になる。
.env.local を変更した後は dev サーバの再起動が必要、本番ビルド時はビルド実行シェルに値があることを確認する。
仕様は Environment Variables(新しいタブで開く) に明記されている。
実行例
node:20 で Next.js の本番ビルドを繰り返すと、プレフィックスの無い API_URL は .next/static から見つからなかった。NEXT_PUBLIC_API_URL に改めた時点で、クライアント JS に URL が埋め込まれた。.env.production に別の URL を足しても、採用されたのは .env.local 側の値だった。
値を持たずにビルドした成果物は、next start に値を渡しても API: undefined のままだった。
ビルドするシェルで export し直してから作り直すと、API: https://api.example.com が返った。
$ npm run build > build.log 2>&1
$ echo $?
0$ grep -E "Environments|Compiled successfully" build.log
- Environments: .env.local
✓ Compiled successfully in 5.8s$ grep -rl https://api.example.com .next/static
$ echo $?
1$ cat .env.local
DATABASE_URL=postgres://db.internal:5432/app
NEXT_PUBLIC_API_URL=https://api.example.com$ npm run build > build.log 2>&1
$ echo $?
0$ grep -E "Environments|Compiled successfully" build.log
- Environments: .env.local
✓ Compiled successfully in 6.0s$ grep -rhoE 'https://api[.a-z]*example.com' .next/static | sort -u
https://api.example.com$ cat .env.production
NEXT_PUBLIC_API_URL=https://api.production.example.com$ npm run build > build.log 2>&1
$ echo $?
0$ grep -E "Environments|Compiled successfully" build.log
- Environments: .env.local, .env.production
✓ Compiled successfully in 5.0s$ grep -rhoE 'https://api[.a-z]*example.com' .next/static | sort -u
https://api.example.com$ npm run build > build.log 2>&1
$ echo $?
0$ grep -E "Environments|Compiled successfully" build.log
✓ Compiled successfully in 3.9s$ NEXT_PUBLIC_API_URL=https://api.example.com npm run start -- -p 3000 > start.log 2>&1 &$ curl -s http://localhost:3000/ | grep -o 'API: [^<]*'
API: undefined$ export NEXT_PUBLIC_API_URL=https://api.example.com$ npm run build > build.log 2>&1
$ echo $?
0$ grep -E "Environments|Compiled successfully" build.log
✓ Compiled successfully in 3.9s$ npm run start -- -p 3001 > start.log 2>&1 &$ curl -s http://localhost:3001/ | grep -o 'API: [^<]*'
API: https://api.example.com— 2026-11-08 時点の出力
検証環境Node.js 20.20.2 / npm 10.8.2 / Python 3.11.2 / 2026-11-08 検証(ほか 2 件)
- 検証日
- 実行環境
node:20Debian GNU/Linux 12 (bookworm)- バージョン
- Node.js 20.20.2
- npm 10.8.2
- Python 3.11.2
- Git 2.39.5
- Next.js 15.5.29
この記事の「実行例」は、上記の環境で実際にコマンドを実行して得られた出力をそのまま掲載しています。 再現手順はリポジトリの検証スクリプトとして管理し、定期的に再実行して出力を更新しています。
解決策
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); // undefined2. dev サーバを再起動
# Ctrl+C で止めて
npm run devホットリロードは .env* の変更を検出しない。
3. 本番ビルドのシェルで export
export NEXT_PUBLIC_API_URL=https://api.example.com
export DATABASE_URL=postgres://...
npm run buildCI ではビルドステップの環境に値を渡す。
Vercel / Cloud Run / Amplify などは UI で設定する。
4. ファイル優先順位を確認
.env.development.local ← dev 時のローカル上書き(git ignore 推奨)
.env.local ← 全環境のローカル上書き(git ignore 推奨)
.env.development ← dev のデフォルト
.env ← ベース複数ファイルがある場合、上のファイルの値が下を上書きする。
環境別のデフォルト(.env.development / .env.production)よりも .env.local のほうが強い。
ただし NODE_ENV が test のときだけは .env.local が読まれない。
空文字を書くと、その変数は「未設定」ではなく「空文字」として扱われる。
よくある原因
- ブラウザに露出させる値には、明示的に
NEXT_PUBLIC_を付ける必要がある。
付け忘れた値は、クライアント側でundefinedになる。 - dev サーバを再起動していない。
.env*ファイルはプロセス起動時に読み込まれるので、編集後は Ctrl+C で停止して再起動しないと反映されない。 - ビルド時に値が定義されていない。
next buildの時点で値が無いと、その値はundefinedとしてバンドルされ、実行時の env を変えても上書きされない。 - ファイルの優先順位を誤解している。
.env.production.local>.env.local>.env.production>.envの順で読まれるので、上位ファイルで意図せず空文字を入れていないかを確かめる。