Vercel環境変数の使い分け実務ガイド CLI・REST API・Sensitive・Custom Environments

こんにちは、豊島です。

WebアプリケーションをVercelで動かしていると、本番・ステージング・開発でDB接続先やAPIキーを使い分ける場面が必ず出てきます。
環境ごとに設定ファイルを書き換えたり、デプロイパイプラインを分けたりする運用は、案件が増えるほど煩雑になりがちです。

Vercelでは同じキーの環境変数をProduction/Preview/Developmentそれぞれに別の値で設定できる仕組みが用意されています。
本記事ではCLIとREST APIでの管理方法、機密値を扱うためのSensitive Environment Variables、そしてDB接続先の環境別分離の実例までを順にまとめます。

Vercelの環境変数モデル

VercelにはProduction/Preview/Developmentの3環境があり、デプロイのされ方・アクセス対象・想定する値が異なります（参考: Environments 公式ドキュメント）
3環境に分かれているのは、本番ユーザー向け・レビュー向け・ローカル開発向けで参照すべきリソースが違うからで、環境変数もこの枠組みに合わせて値を分けて登録するのが基本になります。

Production

本番ユーザーが触れる公開環境です。Production Branch（通常は main）へのプッシュ、または vercel deploy --prod でデプロイされ、カスタムドメインの紐付け先になります。ロールバックやRolling Releasesなど安定運用向けの機能が効く対象もここです。
本番DBの接続先や本番APIキー、課金が発生するサービスのキーなど、誤って他環境に漏らしたくない値を入れます。

Preview

本番以外のブランチへのプッシュやPR作成のたびに自動生成される、レビュー用の使い捨て環境です。デプロイごとにユニークなURLが払い出され、Productionとほぼ同じビルド・ランタイムでマージ前の挙動を確認できます。
レビュー担当やQAが共有URLで動作確認するため、本番DBに書き込みが届くと事故になりやすい場面です。ステージングDB・サンドボックス用APIキーなど、壊しても痛くない値に向けます。

Development

ローカル開発で使う環境で、クラウド上にデプロイすることはありません。vercel dev から参照するほか、vercel env pull で .env.local に書き出して next dev などから読ませる用途で使います。
実行環境は各開発者のマシンなので、個人発行のAPIキーやローカルDBの接続先など、開発者ごとに値が違ってよい用途にも対応できます。

同じキーを環境ごとに別の値で持つ

同じキー名（例えば DATABASE_URL）を3環境すべてに登録し、それぞれ別の値を持たせることができます。さらにPreview環境については、特定のGitブランチだけ別の値に切り替えることも可能です（後述の「Branchごとに異なる値を設定する」を参照）

CI側で NODE_ENV を見て分岐したり、.env.production と .env.development を別々にビルドへ混ぜ込んだりする必要はなく、デプロイ時にVercelが対象環境の値だけを注入してくれます。

CLIで環境変数を設定する

Vercel CLIの vercel env サブコマンドで、環境変数の追加・更新・削除・一覧・エクスポートをまとめて操作できます。

環境別に値を追加する

vercel env add の対話プロンプトに値を貼り付ける形が基本です。シェル履歴やプロセス一覧に値が残らないので、機密値を含むキーをそのまま投入できます。

vercel env add DATABASE_URL production
# ? What's the value of DATABASE_URL? <ここに値を貼り付け>

production を preview / development に置き換えれば、同じキーを環境ごとに別の値で登録できます。

vercel env add DATABASE_URL preview
vercel env add DATABASE_URL development

複数のキーをまとめて流し込みたいときは、後述の「REST APIによる一括登録」を使うと、JSON形式でまとめて投入できます。

既存の値を更新する

vercel env update サブコマンドで、既存の環境変数の値を更新できます。

vercel env update DATABASE_URL development

vercel env add ... --force でも上書きできますが、update の方が意図が伝わりやすいので、更新時はこちらをおすすめします。

特定環境の値だけ削除する

vercel env rm DATABASE_URL development --yes

--yes を付けると確認プロンプトをスキップできます。Production/Previewの値はそのまま残ります。

一覧表示

vercel env ls                           # すべての環境変数を表示
vercel env ls production                # Production環境のみ
vercel env ls preview feature-a         # 特定ブランチ用のPreview値

環境変数をローカルにエクスポートする

ローカルで vite dev や next dev を動かすときは、vercel env pull でクラウド側の値を .env.local に取り込めます。

vercel env pull                                          # Development（デフォルト）
vercel env pull --environment=production                 # Production
vercel env pull --environment=preview                    # Preview
vercel env pull --environment=preview --git-branch=feature-a  # 特定ブランチのPreview値

これは地味に重要な機能で、従来「.env ファイルをSlack DMで共有する」「パスワードマネージャーに置いて誰かが手動でコピーする」といった運用をしていたチームにとっては、運用が大きく変わります。
Vercel側の値が一元管理された正本になるので、新しくチームに入ったメンバーも vercel env pull を1回叩けば最新の .env.local が手元に揃います。値を更新したときも、メンバーへ周知して各自再実行してもらえば全員の .env.local が同期されます。

ファイルに書き出さずに実行したい場合

vercel env run -- <command> を使うと、環境変数をファイルに書き出さずにコマンドへ直接注入できます。.env.local のようなファイルを残したくないとき、CIっぽく一時的に値を渡したいときに便利です。

vercel env run -- next dev                    # Development変数でnext devを起動
vercel env run -e preview -- npm test         # Preview変数でテスト実行
vercel env run -e production -- next build    # Production変数でビルド

Sensitive Environment Variables

機密値を扱う場合に押さえておきたいのが、Sensitive Environment Variablesです（参考: Sensitive Environment Variables 公式ドキュメント）

何が違うか

通常のEncrypted変数はDashboardやCLIから値を再表示できますが、Sensitive変数は一度設定すると値を読み戻すことができません。

ビルド時とランタイムでは通常通り値が利用できるので、機能面に影響はありません。「過去に登録した値を後から確認できなくなる」という運用上の制約だけが追加される形です。

利用可能な環境

Sensitiveが指定できるのはProduction/Preview/Custom Environmentsで、Development環境では指定できません。Developmentで --sensitive を付けて実行すると、APIから次のエラーが返ります

"You cannot set a Sensitive Environment Variable's target to development."

CLIでのデフォルト挙動

vercel env add は、Vercel CLI 51.8.0以降、チームポリシーの設定有無にかかわらず、Production/Preview/Custom Environmentsへの追加でデフォルトSensitive扱いになります（vercel env CLI ドキュメント）--sensitive を明示しなくても機密値として保存され、Dashboardや vercel env ls からは値を再表示できません。

対話モードで vercel env add を実行すると、対象環境と値の入力のあとに Make it sensitive? の確認プロンプトが出ます（デフォルトyes）--sensitive / --no-sensitive を明示しているとき、またはチームポリシーで挙動が固定されているときは、このプロンプトはスキップされます。

明示的にSensitiveとして登録したいときは、--sensitive を付けておくと対話プロンプトを介さずに済みます。

vercel env add API_TOKEN production --sensitive

逆にDashboardやREST APIから後で値を確認したいケース（Marketplace連携の自動設定値をデバッグしたい等）でEncryptedとして登録したい場合は、--no-sensitive を付けます。

vercel env add API_TOKEN production --no-sensitive

チームポリシーでの強制

Production/Preview/Custom EnvironmentsはCLIレベルで既にデフォルトSensitiveになるため、--no-sensitive を打たない限りEncryptedにはなりません。--no-sensitive も封じてSensitiveを強制したいなら、「Enforce Sensitive Environment Variables」ポリシーを有効化します。

チームのオーナー権限でDashboardのTeam Settings → Security & Privacy → Environment Variable Policiesから「Enforce Sensitive Environment Variables」をオンにすると、CLIの挙動が次のように変わります（公式ドキュメント）

• Production/Previewへの vercel env add で --no-sensitive を指定しても無視され、Sensitiveとして登録される
• Development環境への vercel env add 自体がエラーになり、ローカル開発向けの値はDashboard経由でのみ登録できる
• 対話モードの Make it sensitive? プロンプトはスキップされ、--debug 出力にポリシー適用が明示される

組織として「Encryptedでの登録経路を完全に塞ぎたい」「Development変数の登録もCLIから禁じたい」という運用にしたい場合に有効化を検討します。

開発環境向けの値はどう管理するか

ローカル開発用の値（Development環境変数）をどこで管理するかは、Sensitive対応とは別軸で方針を決めておくと迷いません。前述のポリシーを有効にしている場合は vercel env add でのDevelopment追加自体が拒否されるため、後述の案Aを採るならDashboardからの登録に絞ることになります。ポリシーが無効であれば、案A・案Bどちらも自由に選べます。

案A: Vercel側でまとめて管理する

Development環境変数もVercelに登録し、各開発者は vercel env pull で取得する運用です。

• Vercelが正本となり、新規メンバーのオンボーディングが vercel env pull 1回で完結する
• 値の更新も「Vercelで更新 → 各自再pull」で完結する
• ただしローカル用の値もVercel側に蓄積される

シードデータ用のDB接続先など「チーム全員が共通で使う値」が中心であれば、この案が運用しやすいです。

案B: 1Passwordなどのシークレットマネージャで配布する

Development環境変数はVercelに登録せず、1PasswordなどのシークレットマネージャにVaultやItemとして登録し、そこから各開発者が手元の .env.local を生成する運用です。

• リポジトリに .env.example（値抜きのテンプレート）をコミットして必要なキーを明示しておく
• 実値はシークレットマネージャ側のVaultに登録し、チームメンバーへ閲覧権限を付与する
• 1Password CLI なら op inject -i .env.tpl -o .env.local のようなコマンドで .env.local を自動生成できる
• 個人ごとに値が違ってよい場合（個人発行のAPIキーなど）にも対応しやすい

「Sensitive扱いにしたい値」と「個人ごとに違ってよい値」が混在するチームや、Vercel以外の用途（ローカルだけで使うCLIツールの認証情報など）も同じ場所にまとめたいチームには、こちらが合います。

個人的には、ハイブリッドが落ち着きます。

• Marketplace連携で自動セットされるDB/Redis等の共通値は、そのままVercel管理（案A相当）
• 個人ごとに異なる値や強い機密値は、.env.local と1Password（案B相当）でローカル管理

リポジトリの .env.example を最新に保ちつつ、Vercel側に登録したキーは vercel env ls で確認できる状態にしておけば、新規メンバーのオンボーディングも迷いません。

既存の変数をSensitiveに変換する

既存のEncrypted変数を後からSensitiveに変えるには、一度削除してから再登録する必要があります。Dashboard上では「Edit」では変換できないので、削除→再追加の流れになる点だけ覚えておきます。

vercel env rm API_TOKEN production --yes
vercel env add API_TOKEN production --sensitive
# 対話プロンプトに新しい値を貼り付け

REST APIによる一括登録

複数の環境変数を一度にまとめて登録したい場合は、Vercel REST API が便利です。

curl -X POST "https://api.vercel.com/v10/projects/${PROJECT_NAME}/env?teamId=${VERCEL_TEAM_ID}&upsert=true" \
  -H "Authorization: Bearer ${VERCEL_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "key": "DATABASE_URL",
      "value": "postgres://prod-db.example.com:5432/mydb",
      "type": "sensitive",
      "target": ["production"]
    },
    {
      "key": "DATABASE_URL",
      "value": "postgres://preview-db.example.com:5432/mydb",
      "type": "sensitive",
      "target": ["preview"]
    }
  ]'

ポイントは以下の3つです。

• upsert=true を付けると、既存キーは上書き、未存在キーは新規作成される
• type には encrypted / sensitive を指定できる
• target に複数環境を指定すれば、同じ値を複数環境にまとめて設定できる

Branchごとに異なる値を設定する

Preview環境変数にはGitブランチを指定できます。特定ブランチのプレビューデプロイだけ別のサービスに繋ぎ替えたい場合に便利です。

# Preview全体のデフォルト値
vercel env add DATABASE_URL preview
# 値: postgres://staging-db/mydb を入力

# feature-a ブランチ専用の値
vercel env add DATABASE_URL preview feature-a
# 値: postgres://feature-a-db/mydb を入力

該当ブランチのデプロイではブランチ指定の値が、それ以外のPreviewデプロイではデフォルトのPreview値が使われます。

Custom Environmentsへの対応（Pro/Enterprise）

Production/Preview/Developmentの3つに加えて、ProとEnterpriseプランではCustom Environmentsという追加の環境を定義できます（参考: Environments 公式ドキュメント）
stagingやqaのような独自の名前で持続的なpre-production環境を持ちたいときに利用します。

環境変数を設定するときの注意

Custom Environmentsの名前（例: staging）はCLIから通常の環境名と同じ書式で指定できます。

vercel env add DATABASE_URL staging
vercel env pull --environment=staging

作成手順はDashboardのProject Settings → Environments → Create Environment、またはREST APIでの POST /v9/projects/{id}/custom-environments です。

curl -X POST "https://api.vercel.com/v9/projects/${PROJECT_NAME}/custom-environments" \
  -H "Authorization: Bearer ${VERCEL_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "staging",
    "description": "Staging environment for QA"
  }'

加えて以下も覚えておくと便利です。

• Custom Environmentsの環境変数も vercel env add でデフォルトSensitive扱いになる（サーバー側設定で許可されている場合）
• 既存環境からの「Import variables」オプションがDashboardにあり、Production/Previewの値をシードして開始できる
• vercel deploy --target=staging でCustom Environment向けにデプロイできる

ユースケース: DB接続先の環境別分離

ここまでの仕組みを使った典型的なユースケースが、DB接続先の環境別分離です。Vercel Marketplaceから提供されているSupabase、Neon、Upstash Redisなどのサービスは、Vercelプロジェクトと連携すると環境変数が自動でセットされる仕組みになっています。

自動設定された値を環境ごとに上書きする

Marketplace Integrationが自動設定する環境変数は、すべての環境に同じ値が入ることがあります。本番用と開発用でインスタンスを分けたい場合は、Preview/Development用の値を上書きします。

# Production用（Marketplaceで自動設定済みの値を使用）
# 何もしなくてOK

# Preview用に開発インスタンスを上書き（対話プロンプトで値を貼り付け）
vercel env add SUPABASE_URL preview --force          # 値: https://xxx-dev.supabase.co
vercel env add SUPABASE_ANON_KEY preview --force     # 値: eyJ-dev-key

# Development用も同じ値で上書き
vercel env add SUPABASE_URL development --force      # 値: https://xxx-dev.supabase.co
vercel env add SUPABASE_ANON_KEY development --force # 値: eyJ-dev-key

Upstash RedisやNeonでも同じ手順で環境分離できます。

特定ブランチ用のDBに切り替える

Branchごとに別のDBへ向けたい場合は、前述のブランチ指定を使います。

vercel env add SUPABASE_URL preview feature-a
# 値: https://xxx-feature-a.supabase.co を入力

これだけで、feature-a ブランチのプレビューデプロイは専用DBを参照する状態になります。

さらに自動化したい場合: Branching機能

PRを作るたびに専用のDB環境がほしくなった段階では、各サービスのBranching機能を検討する手があります。Vercel側の操作はこれまでと同じ環境変数管理で済み、DB側で自動的にブランチが切り替わる構成です。料金プランや上限値は変動するため、最新情報は各サービスの公式ドキュメントを参照してください。

Supabase Branching

PRを開くと自動でPreview用のSupabaseインスタンス（Postgres + Auth + Storage + Realtime + Edge Functions）が作成され、Vercelの環境変数も自動で切り替わります。

• マイグレーションは自動適用されるが、データはコピーされない（スキーマのみ）
• Auth/Storageまで含めて環境分離したい場合に強い
• 料金プランや対応条件は Supabase Branching 公式ドキュメント を参照

Neon Branching

PRを開くとPostgresブランチが瞬時に作成され、Vercelに接続文字列が自動で渡されます。ブランチ作成時にデータ実体をコピーせず、書き換えが発生したページだけを差分として持つ仕組みなので、TBクラスのDBでも数秒でブランチが切れます。

• スキーマだけでなくデータもコピーされる
• 本番データを使ったテストを重視する場合や、コストを抑えてBranching体験を試したい場合に向く
• 料金プランや対応条件は Neon Branching 公式ドキュメント を参照

まとめ

• Vercelの環境変数はProduction/Preview/Developmentの3環境で別々の値を持てる
• 追加・更新・削除・エクスポートはCLIでもREST APIでも操作できる
• Vercel CLI 51.8.0以降、vercel env add はProduction/Preview/Custom EnvironmentsをデフォルトでSensitiveとして登録するため、登録後は値を後から表示できなくなる
• 「Enforce Sensitive Environment Variables」ポリシーをオンにすると、--no-sensitive を付けても無視され、Development環境への vercel env add もエラーになる
• vercel env pull を使えば、Slack DMで .env を共有する運用から抜けられる
• 開発環境向けの値は、Vercelに登録する案と、1Passwordなどのシークレットマネージャから配る案を組み合わせると扱いやすい
• stagingやqaなど独自の環境を持ちたいなら、Pro/EnterpriseのCustom Environmentsを先に作ってから値を入れる
• DB接続先の環境別分離は、Marketplace連携で自動セットされた値を --force で上書きすれば足りる
• PRごとに専用DBが欲しくなったら、Supabase BranchingやNeon Branchingなどを検討する