目次
開発環境では動いていたのに、本番に出した途端に動かない。調べてみると、設定したはずの環境変数がundefinedになっている——Next.jsとVercelでシステムを作っていると、一度は出会う症状です。
私たちも実案件（匿名）でこの症状に当たり、原因の切り分けに半日かかりました。最終的な主因はコード側の書き方でしたが、そこにたどり着くまでに迷った理由は、Vercelの管理画面の見え方にありました。
この記事では、切り分けを遠回りさせた周辺要因2つと、同じ迷い方をしないための確認手順を整理します。
この記事の結論
- 設定画面の見た目だけで設定済みと判断しない
- 環境変数は環境タブごとに別管理だと意識する
- 迷ったら各環境で実際に読み込まれた値を確かめる
Vercelの環境変数が本番で反映されない原因
本番で環境変数がundefinedになるとき、原因は大きく2系統に分かれます。
| 系統 | 中身 | この記事での扱い |
|---|---|---|
| コード側 | 環境変数の参照の書き方が、ビルド時の置換の対象外になっている | 別記事で解説 |
| 設定側 | 管理画面での登録漏れ・登録ミス | 本記事の主題 |
今回の主因はコード側でした。process.env[name] のように変数名を動的に組み立てて参照していたため、ビルド時の静的な置換の対象にならなかったのです。この詳細は別記事に譲ります。
厄介だったのは、設定側にも紛らわしい要因が重なっていたことです。コードを疑う前に「そもそも設定が正しいのか」を確かめようとして、管理画面の見え方に何度も引っかかりました。
落とし穴1：キー名が省略表示され、設定済みか判断しにくい
最初に迷ったのは、Vercelの管理画面で環境変数のキー名が省略されて表示されていたことです。
キー名が長いと、画面上では途中で切れて表示されます。似た接頭辞の変数が並んでいると、どれが目的の変数なのか、綴りが正しいのかを画面だけでは判断できません。
その結果、こんな堂々巡りが起きました。
- 「一覧に並んでいるから、設定済みのはず」と思い込む
- 実は綴りが1文字違うかもしれないが、省略表示で確かめられない
- 設定が正しいのか、コードが悪いのか、切り分けの起点が定まらない
画面に「それらしい名前がある」ことは、正しい名前で登録されていることの証明になりません。見た目で安心してしまうと、ここで時間を失います。
落とし穴2：環境タブごとに別管理で、反映漏れが起きる
次に迷ったのが、Vercelの環境変数が環境タブごとに別々に管理されていることです。
ある環境には登録してあっても、別の環境には自動で反映されません。今回は、確認していた環境と、実際に不具合が出ていた環境の設定がそろっておらず、反映漏れが起きていました。
このずれがあると、「ある環境では動くのに、別の環境では動かない」という症状になります。すると、環境差の問題なのかコードの問題なのかが見分けにくくなり、主因を探す道のりがさらに長くなりました。
なお、Vercelの環境の種類や管理画面の表示は変わることがあるため、最新の仕様は公式ドキュメントで確認してください。
環境変数が反映されないときの対策：環境ごとに実際の値を確かめる
2つの落とし穴に共通するのは、設定画面の見た目を信じてしまったことです。持ち帰るべき判断軸はひとつで、「画面に何が見えるか」ではなく「その環境で実際に何が読み込まれているか」を確かめることです。
- 対象環境を特定する：不具合が出ているのがどの環境なのかを先に決めます。確認する環境と、症状が出ている環境を取り違えないことが出発点です。
- キー名を全文で照合する：省略表示のまま判断せず、編集画面などでキー名の全文を表示し、コード側の名前と1文字ずつ照合します。
- 実際の値を確かめる：その環境で値が読み込まれているかを、動いているアプリ側から確認します。値そのものを画面やログに出すと漏えいの恐れがあるため、値の有無や先頭数文字の一致だけを一時的に確かめ、確認後は必ず消します。
- 設定かコードかを切り分ける：値が入っているのにundefinedなら、設定ではなくコード側の参照方法を疑います。今回の主因はここでした。
この順番で進めれば、「設定の問題か、コードの問題か」を早い段階で切り分けられます。私たちが半日かけた遠回りの大半は、手順2と3を飛ばして見た目で判断したことによるものでした。
社内で引き継ぐときのポイント
環境変数は、作った本人しか全体像を知らない状態になりがちです。どの環境に何を登録したかを一覧で残しておくと、担当者が変わっても同じ迷い方を防げます。値そのものは書かず、キー名と登録先の環境だけを記録すれば十分です。
よくある質問
Q. Vercelで環境変数を設定したのに本番でundefinedになるのはなぜ？ 原因は、コード側の参照方法とVercel側の設定漏れの2系統に分かれます。設定側では、値を登録した環境タブが本番と違う、キー名が省略表示されて誤りに気づけない、といった見落としが起きます。まず本番で実際の値を確認してください。
Q. Vercelの環境変数は環境ごとに別々に設定が必要ですか？ はい、環境タブごとに別管理です。ある環境に登録しても、別の環境には自動では反映されません。使う環境それぞれに登録されているかを個別に確認する必要があります。仕様は変わるため、最新の挙動は公式ドキュメントで確認してください。
Q. 環境変数が正しく設定されているかを確実に確かめる方法は？ 管理画面の見た目ではなく、各環境で実際に読み込まれた値を確かめることです。値そのものを表示すると漏えいの恐れがあるため、値の有無や先頭数文字の一致だけを一時的に確認し、確認が済んだら必ずその処理を削除します。
まとめ
- 本番で環境変数がundefinedになる原因は、コード側と設定側の2系統に分かれる
- Vercelの管理画面ではキー名が省略表示され、設定済みかを見た目で判断しにくい
- 環境変数は環境タブごとに別管理で、登録漏れがあると環境差の症状になる
- 対策は、設定画面の見た目を信じず、環境ごとに実際の値を確かめること
RENOYでは、Next.jsやVercelを使ったシステムの開発から、本番運用で起きたトラブルの切り分けまで、無料相談で承っています。「本番だけ動かない原因が分からない」「引き継いだシステムの設定が把握できていない」という段階のご相談も歓迎です。まずはお気軽に無料個別相談（オンライン・60分）をご利用ください。サービス内容をまとめた資料は資料請求からご覧いただけます。