Vercelの環境変数は、Production・Preview・Developmentの環境ごとに値を分けて登録し、デプロイのビルド時と関数の実行時に読み込ませる仕組みです。この記事では、ダッシュボードとvercel env addでの登録、Previewのブランチ別の上書き、vercel env pullでのローカルへの取り込みをコマンド付きで示します。2026年8月に導入されたConfig型とSecret型の選び方、NEXT_PUBLIC_の値が反映されない原因と再デプロイの要否も、2026年10月時点の公式ドキュメントで整理しました。
まとめ：Vercelの環境変数は環境の分け方・Secret型・再デプロイの3点で決まる
値を登録したのに効かない、という相談の大半は再デプロイ忘れです。Vercelの環境変数のドキュメントは、変更は以前のデプロイに適用されず、新しいデプロイにだけ適用されると明記しています。保存したら、対象の環境で新しいデプロイを作るところまでが1つの作業です。
APIキーやトークンはSecret型で登録します。Secret型は保存後に誰も値を読み返せず、2026年4月のVercelのセキュリティインシデントでも、露出の対象になったのはSensitive指定のない変数でした。公開してよい設定値だけをConfig型にし、NEXT_PUBLIC_を付けた変数はブラウザに配られる前提で中身を選びます。
ローカル開発ではvercel env pullでDevelopmentの値を取り込みます。本番と同じ秘密値をローカルへ持ち出さない運用にしておくと、端末の紛失やリポジトリへの誤コミットでの被害を本番に波及させずに済みます。
Vercelの環境変数が効く範囲：3つの環境・カスタム環境・64KBの上限
Vercelそのものの仕組みと料金体系はVercel（ヴァーセル）とは？サーバー不要の仕組みとできること・料金【2026年】で扱っています。OSやDockerでの環境変数の基本は環境変数とは？Linux・Windowsの設定方法とDocker・CIでの受け渡しを参照してください。ここでは、Vercelで値を登録する前に決めておく範囲だけを示します。
Production・Preview・Developmentの3環境の適用条件
どの環境の値が使われるかは、デプロイの作られ方で決まります。表の本番へのpushは、本番ブランチへのpushを指します。Developmentの値を使う場面は、vercel devでの起動や、vercel env pullで値を取り込んだローカルでの開発です。
| 環境 | 値が使われる場面 | 主な用途 |
|---|---|---|
| Production | 本番へのpush、vercel --prod |
本番のDB・決済キー |
| Preview | 本番以外のブランチへのpush、PR、vercel |
検証用のDB・サンドボックスのキー |
| Development | vercel dev・pull後のローカル |
手元の開発サーバー |
見落としやすいのは、新しいプロジェクトの最初のデプロイが必ずProductionになる点です。Environmentsのドキュメントによると、本番以外のブランチからデプロイしてもこの扱いは変わりません。最初のデプロイの前にProductionの値を登録しておかないと、空の値でビルドが走ります。
Proで1つ作れるカスタム環境とstaging運用の要件別の選び方
Previewとは別に、stagingやqaのような名前付きの環境を持てるのがカスタム環境です。作れる数はプロジェクトあたりProが1つ、Enterpriseが12で、Hobbyでは使えません。プランごとの料金はVercel料金プラン｜Hobby無料枠とPro($20)の中身・超過単価【2026年10月】にまとめています。
Hobbyのままstagingを用意するなら、stagingブランチを切ってPreviewのブランチ別の値を登録する方法が公式に案内されています。ステージングの接続先を本番と完全に分けたい、独自ドメインを固定したい、という要件が出た時点でProのカスタム環境へ移るのが妥当な線引きです。
1デプロイ合計64KBとEdgeランタイムの1変数5KBの上限
環境変数の容量は、1つのデプロイに入る全変数の合計で64KBまでです。Node.js・Python・Ruby・Go・PHPのランタイムが対象で、証明書や長いJWTも1つの値として入れられます。ただしedgeランタイムで動く関数とミドルウェアは、1変数あたり5KBに制限されます。
サービスアカウントのJSON鍵のような大きな値をミドルウェアで読む構成は、この5KBで止まります。大きな秘密値はNode.jsランタイムの関数側だけで読む形に寄せておくと、上限に当たりません。
ダッシュボードとvercel env addで環境変数を登録する手順
登録はダッシュボードのプロジェクト設定からでもできますが、検証環境と本番環境で同じ手順を繰り返すならCLIで残しておくと再現できます。2026年10月時点のVercel CLIは64系です。
vercel linkからvercel env addまでのCLI登録コマンド例
まずリポジトリのディレクトリをVercelのプロジェクトに紐付け、環境を指定して値を登録します。コマンドの書式はvercel envのリファレンスのとおりです。
# ローカルのディレクトリをVercelのプロジェクトに紐付ける
vercel link
# 公開してよい設定値はConfig型で登録する
vercel env add API_BASE_URL production --value "https://api.example.com" --no-sensitive --yes
# APIキーはSecret型（本番の既定）で、値はファイルから標準入力で渡す
vercel env add STRIPE_SECRET_KEY production < ./secrets/stripe_live.txt
# 登録済みの変数を環境ごとに確認する
vercel env ls production値をechoでパイプして渡す書き方もありますが、リファレンス自身が「シェルの履歴に値が残るので秘密値には勧めない」と注記しています。秘密値はファイルからのリダイレクトか、対話プロンプトで入力してください。既存の値を変えるときはvercel env update、消すときはvercel env rmを使います。
Previewのブランチ別の上書きで共有値と差分値を分ける書き方
Previewの値は、本番以外の全ブランチに効く既定値と、特定のブランチだけに効く値の2段で持てます。ブランチ別の値は同じ名前のPreviewの値を上書きするので、ブランチごとに全変数を複製する必要はありません。
# Preview全体の既定値（共有の検証用DB）
vercel env add DATABASE_URL preview < ./secrets/db_preview.txt
# feature-billingブランチだけ決済検証用のDBへ向ける
vercel env add DATABASE_URL preview feature-billing < ./secrets/db_billing.txt
# そのブランチで有効な値の一覧を確かめる
vercel env ls preview feature-billingブランチごとに別のDBを自動で作りたい場合は、ブランチ別の値を手で登録するより、DBサービス側の連携に任せたほうが手数は減ります。Supabaseで自動同期される変数とプレビュー用DBの分け方はSupabase Vercelデプロイ連携｜環境変数の自動同期とプレビュー環境のDB分離で詳しく扱いました。
2026年8月導入のConfig型とSecret型の既定値と選び方
2026年8月24日のVercelの変更履歴で、従来の「Sensitive」の切り替えは、Config型とSecret型の選択に置き換わりました。既存のSensitive変数はSecret型として扱われ、移行作業は不要です。
ConfigとSecretのドキュメントによると、Config型は保存後もアクセス権のあるメンバーが値を読めます。Secret型は保存後に読み返せず、32文字以上の値がビルドログに出たときの表示は[REDACTED]です。CLIの既定型はProduction・Preview・カスタム環境がSecret、DevelopmentがConfigで、NEXT_PUBLIC_のような公開用の接頭辞を持つ変数は常にConfigとして保存されます。
判断は単純です。漏れたら差し替えが必要な値はSecret、画面で中身を確かめたい非機密の値はConfigにします。保存したSecretはその場でConfigへ変えられず、キー名も編集できないので、型を間違えたら削除して作り直します。以前はSecret（旧Sensitive）をDevelopmentに置けませんでしたが、この変更で使えるようになりました。
vercel env pullとvercel env runでローカル開発へ値を渡す手順
ローカルの開発サーバーにVercelの値を渡す方法は、ファイルに書き出すvercel env pullと、ファイルに書かずにコマンドへ渡すvercel env runの2つです。.envファイル自体の扱いはdotenvとは？.envで環境変数を管理する仕組みと言語別の使い方で解説しています。
vercel env pullの書き出し先と既存ファイルへのマージ挙動
書き出し先の既定のファイル名は、公式ドキュメントのページによって.envと.env.localの記述が混在しています。取り違えを避けるため、ファイル名は毎回引数で指定します。
# Developmentの値を.env.localへ書き出す
vercel env pull .env.local
# Previewの特定ブランチの値を別ファイルへ書き出す
vercel env pull .env.preview.local --environment=preview --git-branch=feature-billing
# ファイルに書かずにPreviewの値でテストを走らせる
vercel env run -e preview -- npm test書き出し先のファイルが既にあると、vercel env pullは上書きせずにマージします。Vercel側に無いローカルだけの変数は残り、VERCEL_OIDC_TOKENは常に最新の値に差し替わります。ダッシュボードで値を変えたら、その都度pullし直さない限り手元の値は古いままです。
vercel buildやvercel devを使う場合は、vercel env pullではなくvercel pullで.vercel/配下に設定ごと取り込みます。
Secret型の値がローカルに来ないときの開発用の値への置き換え方
Secret型の値はVercelから読み出せないため、vercel env pullは本物の値を書き出しません。ローカルのファイルに実値があればそれを残し、無ければプレースホルダを書き込みます。プレースホルダのまま開発サーバーを起動すると、外部APIの認証エラーとして表に出ます。
この挙動は、本番の秘密値を手元に置かない運用と相性が良い仕様です。Developmentには決済のテストキーや開発用DBの接続文字列のような別の値を登録し、本番キーはProductionだけに置きます。チームのオーナーがSecurity設定で「Separate Production Secret Values」を有効にすると、Secretの本番の値を他の環境と同じにできなくなり、この分離を仕組みで強制できます。
vercel env pullで付かないNEXT_PUBLIC_接頭辞の補い方
Vercelは、VERCEL_ENVのようなシステム環境変数にNEXT_PUBLIC_を付けた版を、本番とプレビューのデプロイでは自動で用意します。フレームワーク環境変数のドキュメントによると、vercel env pullで取り込んだローカルの値には、この接頭辞付きの変数が付きません。
ローカルでもNEXT_PUBLIC_VERCEL_ENVを読むコードを動かすなら、接頭辞付きの名前でDevelopmentに変数を登録してからpullします。プレビューでは画面に値が出るのに手元ではundefinedになる、という食い違いの原因はたいていこれです。
NEXT_PUBLIC_の露出とビルド時の埋め込みで値が変わらない原因
Next.jsでは、環境変数の読まれるタイミングが接頭辞の有無で変わります。Next.jsの基本はNext.jsとは？16系App Routerで最小アプリを動かす手順と採用判断で扱っており、2026年10月時点の最新は16.4系です。
NEXT_PUBLIC_付きの値がブラウザのJavaScriptに残る仕組み
Next.jsの環境変数のガイドによると、NEXT_PUBLIC_付きの変数はnext buildの時点で値がJavaScriptのバンドルに直接書き込まれます。ブラウザで開発者ツールを開けば誰でも読める状態です。
// lib/config.ts
// サーバー側だけで読む値（ブラウザのバンドルには入らない）
export const stripeSecretKey = process.env.STRIPE_SECRET_KEY;
// NEXT_PUBLIC_付きは next build の時点で文字列に置き換わる
export const analyticsId = process.env.NEXT_PUBLIC_ANALYTICS_ID;
// 変数名を経由した参照は置き換わらない
const name = "NEXT_PUBLIC_ANALYTICS_ID";
export const notInlined = process.env[name];接頭辞を付けてよいのは、計測IDや公開APIのエンドポイントのように、ページのソースに載っても困らない値だけです。SupabaseのanonキーやStripeの公開可能キーのように、公開を前提に設計されたキーもここに入ります。サーバーで使う秘密キーに誤ってNEXT_PUBLIC_を付けた場合、名前を直して再デプロイしても、それまでに配られたバンドルには値が残っています。キー自体の差し替えが必要です。
値を変えても反映されない再デプロイの要否とロールバックの注意
値の変更が効かない原因は2段に分かれます。1段目はVercel側の仕様で、保存しただけでは既存のデプロイに届きません。2段目はNext.js側の仕様で、NEXT_PUBLIC_付きの値はビルドし直さない限り古い文字列のままです。どちらも、新しいデプロイを作れば解消します。
# 直近の本番デプロイのURLを確かめる
vercel ls --prod
# そのデプロイを最新の環境変数で再ビルドして出し直す
vercel redeploy https://my-app-abc123.vercel.app --target=productionvercel redeployは既存のデプロイを再ビルドします。逆の落とし穴がロールバックです。古いデプロイへ戻すと、そのデプロイが作られた時点の値で動きます。無効にしたAPIキーを持つ古いデプロイへ戻すと、外部APIの呼び出しが失敗します。
VERCEL_ENVなどのシステム環境変数で処理を分岐するコード例
環境ごとに処理を変えたいとき、自前でAPP_ENVのような変数を3環境に登録する必要はありません。システム環境変数のドキュメントにあるVERCEL_ENVが、production・preview・developmentのいずれかを返します。
// lib/site-url.ts
export function siteUrl(): string {
// 本番は独自ドメイン、プレビューはデプロイごとのURLを返す
if (process.env.VERCEL_ENV === "production") {
return `https://${process.env.VERCEL_PROJECT_PRODUCTION_URL}`;
}
if (process.env.VERCEL_URL) {
return `https://${process.env.VERCEL_URL}`;
}
return "http://localhost:3000";
}VERCEL_PROJECT_PRODUCTION_URLはプレビューでも常に本番ドメインを返すので、OGP画像のURLのように本番を指したい箇所に向きます。VERCEL_URLはStandardのDeployment Protectionと併用できないとドキュメントに注記があり、保護をかけたプレビューで外部から呼ばれるURLには使えません。システム環境変数の公開設定を切ると、デプロイIDが渡らずVersion Skew（バージョンスキュー）とは？原因とNext.js・Vercelでの対策を実測で解説で扱うSkew Protectionも止まります。
2026年4月のインシデントから見たSecret化とローテーションの判断基準
Vercelの環境変数は保存時に暗号化されますが、Config型（旧来の非Sensitive）は復号して読める値です。この差が実際の被害の差になった事例があります。
Secret型にしていなかった値の露出とローテーションの順番
Vercelの2026年4月のセキュリティインシデントの告知では、社員が使っていた外部のAIツールを起点にVercelの内部システムへ不正アクセスがあり、一部の顧客のSensitive指定のない環境変数が露出したとされています。Vercelは該当する値を露出したものとして扱い、ローテーションすることを推奨しました。告知は2026年10月16日にクローズされています。攻撃の手口全般はVercelハッキングの手口と対策｜情報漏洩・脆弱性・DDoSを実例で整理にまとめました。
ローテーションは、ローテーションの手順書のとおり、古い値を先に無効にしない順番で進めます。
- 外部サービスで新しいキーを発行する。古いキーはまだ有効なまま残す
vercel env update STRIPE_SECRET_KEY production < ./secrets/stripe_live_new.txtで値を差し替える。Config型で登録していた秘密値は、削除してSecret型で登録し直す- 本番とプレビューを再デプロイし、新しいキーで動くことを確かめる
- 外部サービスで古いキーを無効にする
チーム単位の共有変数を差し替えた場合は、それを参照する全プロジェクトの再デプロイが済むまで4の手順に進みません。1つでも再デプロイが漏れると、そのプロジェクトだけ認証エラーで止まります。
Vercelの環境変数で済ませず外部のシークレット管理へ移す条件
Vercelだけで完結するWebアプリなら、秘密値はVercelのSecret型で管理して問題ありません。外部のシークレット管理を足す価値が無いのは、プロジェクトが数個で、値を使うのがVercelのデプロイだけという構成です。この規模で専用の仕組みを入れても、同期の手間が増えるだけです。
移すべきなのは次の条件のどれかに当たるときです。同じDBの資格情報をVercel・AWSのバッチ・GitHub Actionsの3か所以上で使っている。資格情報を定期的に自動でローテーションしたい。誰がいつ値を読んだかの監査記録を求められている。この場合はAWS Secrets Managerなどを正本にして、Vercelには参照用の値だけを配ります。AWS側の設計はAWS Secrets Managerとは？料金・ローテーション設定と採用判断を実装者目線で解説【2026年版】、CI側の値の受け渡しはGitHub Actionsの環境変数｜env・vars・secretsの使い分けと受け渡しで扱っています。
環境の分け方、秘密値の置き場所、デプロイとローテーションの手順をチームの運用としてまとめて整えたい場合は、DevOps・CI/CD導入支援で現状の構成から相談できます。
Vercelの環境変数の設定と反映でよく挙がる質問と公式の回答
Vercelの環境変数を設定し始めたときに出やすい疑問に、公式ドキュメントの記述をもとに答えます。
環境変数を変更したら再デプロイは必要ですか？
必要です。Vercelの環境変数の変更は以前のデプロイには適用されず、新しく作るデプロイにだけ反映されます。ダッシュボードのDeploymentsから直近の本番デプロイを選んでRedeployするか、CLIのvercel redeployで再ビルドします。プレビューで使っている値を変えたときは、プレビューのデプロイも作り直してください。
ローカルの.env.localはGitにコミットしてよいですか？
コミットしないでください。Next.jsのcreate-next-appのテンプレートは.env系のファイルを.gitignoreに入れています。値の正本をVercelに置き、各開発者がvercel env pull .env.localで取り込む運用です。どうしてもリポジトリで値を共有したい場合は、暗号化して管理する方法がdotenvxとは｜.envを暗号化してGitで安全に管理する仕組み・使い方・移行手順にあります。
Secret型にした値を後から確認できますか？
確認できません。Secret型は保存後に書き込み専用となり、ダッシュボードでもCLIでも値を表示できません。値を忘れた場合は、発行元のサービスで新しい値を作ってVercel側を差し替えます。保存後にConfig型へ変えることもできないため、読み返す必要がある非機密の値は最初からConfig型で登録します。
Hobbyプランでもstaging用の環境変数を分けられますか？
ブランチ別の設定で分離が可能です。カスタム環境はProとEnterpriseの機能ですが、Hobbyでもstagingという名前のブランチを作り、そのブランチ専用のPreviewの値を登録すれば、ステージング用の接続先を持てます。ブランチ別の値は同名のPreviewの値を上書きするので、差分の変数だけを登録すれば足ります。
GitHub Actionsからデプロイする場合、値はどちらに置きますか？
アプリが実行時に読む値はVercel側に置きます。GitHub Actionsには、Vercelへデプロイするためのトークンなど、CIの処理そのものに要る値だけを置きます。Gitの連携だけでデプロイしている構成ならGitHub側に値を置く必要はありません。Vercelへのデプロイの流れはReactアプリをVercelにデプロイする方法｜Next.js・Vite対応の手順とCLI・CI/CDで扱っています。
関連記事
- Vercel（ヴァーセル）とは？サーバー不要の仕組みとできること・料金【2026年】：Vercelの全体像と料金の考え方
- Supabase Vercelデプロイ連携｜環境変数の自動同期とプレビュー環境のDB分離：連携で自動登録される変数とプレビュー用DBの分け方
- ReactアプリをVercelにデプロイする方法｜Next.js・Vite対応の手順とCLI・CI/CD：環境変数を設定したあとのデプロイ手順
- dotenvxとは｜.envを暗号化してGitで安全に管理する仕組み・使い方・移行手順：.envを暗号化してリポジトリで扱う選択肢
- Vercelハッキングの手口と対策｜情報漏洩・脆弱性・DDoSを実例で整理：環境変数の漏えいを含むVercelの攻撃事例
