Vercel で環境変数が反映されない

要約

Vercel で env が反映されない原因は 環境のチェック漏れ、NEXT_PUBLIC_ 接頭辞忘れ、追加後の再デプロイ忘れ の 3 つにほぼ集約される。
env は Production / Preview / Development の 3 環境ごとに別保存される点を理解すれば、大半は解決する。

よくある原因

1. 環境別チェック漏れ: Production だけにチェックを入れて、Preview（プルリク用デプロイ）に入れ忘れる。
   プルリクからの動作確認だけ env が undefined になる。
2. NEXT_PUBLIC_ 接頭辞忘れ: クライアント JS から process.env.API_URL を読もうとしても undefined。
   Next.js は build 時にこの接頭辞のみクライアントへ文字列置換する。
3. 再デプロイ未実施: env を変えても既存デプロイの build artifact には焼き込まれた古い値が残るため、再ビルドしないと反映されない。
4. build-time vs runtime: build 時に展開される NEXT_PUBLIC_* を、runtime しか持たない .env 経由で渡そうとしている。
5. .env.local 依存: ローカルだけ .env.local で動かしていて、Vercel 側に登録していないため本番だけ落ちる。

解決策

1. 3 環境ともチェックして登録する

公式の Environment Variables ドキュメント のとおり、Project Settings → Environment Variables の追加画面で Production / Preview / Development を必要に応じて全てチェックする。
サーバー専用なら Sensitive も併用する。

2. クライアント参照は NEXT_PUBLIC_ を付ける

# サーバー専用（API ルート / RSC からのみアクセス）
DATABASE_URL=postgres://...
 
# クライアントへ露出してよい値（build 時に文字列置換される）
NEXT_PUBLIC_API_URL=https://api.example.com

接頭辞が無い値はブラウザに渡らない。
API キーのようなサーバー専用にしたい値はむしろ接頭辞を 付けない。

3. env 変更後は必ず再デプロイ

# CLI から再デプロイ
npx vercel --prod

ダッシュボードからは Deployments 画面で対象を選び Redeploy をクリックする。
Redeploy を行わない限り、既存 build にはどれだけ env を更新しても反映されない。

4. ローカルと同期する

npx vercel link
npx vercel env pull .env.local

CLI ドキュメント の vercel env pull でリモートの env をローカルに取得できる。.env.local は .gitignore に入れる前提。