できない.dev

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

Vercel の環境変数は Production / Preview / Development の 3 環境で別管理される。
環境チェック漏れ、NEXT_PUBLIC_ 接頭辞不足、変更後の再デプロイ忘れ、build-time / runtime の混同が反映されない典型原因。

公開: 更新:

要約

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

解決策

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

公式の Environment Variables ドキュメント（新しいタブで開く） のとおり、Project Settings → Environment Variables の追加画面で Production / Preview / Development を必要に応じて全てチェックする。
API キーやトークンのように保存後に値を見せたくないものは、種類を Secret にする（2026-08-24 に Sensitive トグルが Config / Secret の選択に置き換わり、既存の Sensitive 変数は Secret として扱われる。Vercel Changelog（新しいタブで開く））。

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 に入れる前提。

よくある原因

  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 側に登録していないため本番だけ落ちる。
#vercel #environment #deploy #runtime #build

この手順で直った？