Vercelにおける環境変数の設定とデプロイ時の注意点

私はNext.jsとtailwindcssを使用し、フロントエンド開発を行っている初心者です。第1部で環境変数の基本について説明しましたが、実際にVercelへデプロイする際に、環境変数の設定で予期せぬ問題に直面することが多々ありました。特に、ローカル開発環境と本番環境での設定の違いや、デプロイのタイミングによる影響について、理解を深めるまでに様々な課題に直面しました。今回は、その経験から得られたVercelでの環境変数の設定方法と注意点についてまとめます。

はじめに

Vercelは、Next.jsで作ったWebサイトを簡単にインターネット上に公開できるサービス（ホスティングプラットフォーム）として人気があります。しかし、APIキーなどの非公開にしたい情報（環境変数）の扱いは初心者にとって特に注意が必要な部分です。特に、開発中のパソコン（ローカル環境）と、実際のWebサイト（本番環境）での設定の違いや、公開のタイミングによる影響について、混乱しやすい状況があります。この記事では、Vercelでの環境変数の正しい設定方法と、注意点について、具体例を交えながら説明していきます。

なお、この記事は2部構成の第2部として、Vercelへのデプロイ時の環境変数の設定方法について焦点を当てています。第1部では、環境変数の基本について詳しく解説しています。
環境変数の基本的な概念から学習したい方は、まず第1部をご覧ください。
【保存版】Next.jsの環境変数完全ガイド 📖 envファイルの使い方を基礎から解説

Vercelの3つの環境について

1. Development（開発）環境

これは、自身のパソコン上で開発している時に使う環境です。

使う時
- 新しい機能を作っている時
- コードを書いて試している時
- 変更をすぐに確認したい時

2. Preview（プレビュー）環境

これは、本番環境に反映する前に、変更内容を確認するためのテスト環境です。

使う時
- 他の人に変更内容を確認してもらいたい時
- 本番に反映する前に最終確認したい時
- チームで開発している時

個人開発の場合は、この環境はあまり使いません。パソコン上で確認して、問題なければ直接本番環境にアップロードする方が効率的です。

3. Production（本番）環境

これは、実際のユーザーが見るWebサイトの環境です。

使う時
- 完成したWebサイトを公開する時
- 動作確認が済んだ更新を反映する時

All Environmentsモードについて

Vercel管理画面で環境変数を設定する際、「All Environments」を選択することができます。

All Environmentsの特徴

すべての環境（Production/Preview/Development）で同じ値が使用される
一度の設定で全環境に適用できる
環境に依存しない設定に適している

All Environmentsを使用する際の注意点

機密性の高い情報は避ける
- APIキーなど、環境ごとに異なる値を使用すべき情報は個別に設定する
- テスト用と本番用で分ける必要がある情報には使用しない
上書きのルール
- 特定の環境用に個別設定された値が、All Environmentsの値より優先される
- 同じ変数名で環境別の設定がある場合、環境別の設定が使用される
使用推奨のケース
- Webサイトの基本情報
- 公開しても問題ない設定値
- すべての環境で共通の設定

個人開発での基本的な流れ

パソコン（Development環境）で開発
- コードを書く
- 動作確認をする
- 問題なければGitHubにプッシュする
本番（Production環境）に公開
- GitHubと連携していれば自動的に公開される

環境変数の設定方法

各環境での設定方法は以下の通りです。

パソコン（Development環境）
- プロジェクトの.env.localファイルに記述
本番（Production環境）
- Vercelの管理画面で設定
- Settings → Environment Variables から設定可能

Vercelを使うポイント

GitHubと連携することで、コマンドを使わずに開発できます
最初は「パソコンでの開発環境」と「本番環境」の2つだけを意識すれば十分です
環境変数は、本番環境に公開する前にVercelの管理画面で設定しておくことをお勧めします

Vercelの環境変数設定の基本

Vercel管理画面での設定方法

Vercelのプロジェクトページを開く
Settings へ移動
Environment Variablesへ移動
適用する環境（Production/Preview/Development）を選択
※ デフォルトでは、All Environmentsになっている為、クリックでチェックを外す
Key（変数名）とValue（値）を入力
Add Anotherボタンをクリックし、他の変数を設定
すべて入力が終われば、Saveボタンをクリック

環境変数ファイル（.env）のインポート

Vercelでは、.envファイルを直接インポートして環境変数を一括設定することができます。

インポートの手順

Vercelプロジェクトの管理画面でSettings → Environment Variablesへ移動し、適用する環境を選択
※ Vercel管理画面での設定方法の1～4と同じ
Import .envボタンをクリック
.envファイルを選択してアップロード
インポートする変数を確認してSaveをクリック

インポート機能の特徴と利点

一括設定が可能
- 多数の環境変数を一度に設定できる
- 手動入力の手間を省ける
- 入力ミスを防げる
既存の.envファイルを再利用
- ローカル開発で使用している設定を簡単に本番環境に反映
- チーム内で共有している設定を効率的に適用

インポート時の注意点

セキュリティ
- インポートする前に機密情報が含まれていないか確認
- 開発環境用の認証情報が本番環境に混入しないよう注意
フォーマット
- .envファイルの形式に従っている必要がある
- 1行につき1つの環境変数
- 変数名=値の形式

トラブルシューティング

デプロイ後に環境変数を設定した場合

環境変数はビルド時に読み込まれるため、デプロイ後に設定しても即座には反映されません。以下の手順で再デプロイを行う必要があります。

Deploymentsタブから最新の（適応させたい）デプロイを選択
Visitボタン右の三点リーダーからRedeployボタンをクリック

環境変数が反映されない場合のチェックポイント

変数名の確認
- スペルミスがないか
- NEXT_PUBLIC_プレフィックスが必要な場合は付いているか
適用環境の確認
- 正しい環境（Production/Preview/Development）が選択されているか
キャッシュのクリア
- ブラウザのキャッシュをクリア
- Vercelのキャッシュをクリア

セキュリティ関連の注意点

APIキーの管理
- 本番環境のAPIキーは必ずVercel管理画面で設定
- GitHubには絶対にアップロードしない
環境変数の命名
- 機密情報を含む変数はNEXT_PUBLIC_を付けない
- わかりやすい命名を心がける

発展的な使用方法

環境別の変数管理

開発時と本番環境で異なる設定を使いたい場合があります。例えば、APIのURLは開発時はローカル環境、本番環境では実際のサーバーを使用します。このような場合、環境別に.envファイルを分けることで管理が容易になります。

# .env.development（開発環境用の設定）
NEXT_PUBLIC_API_URL=http://localhost:3000/api

# .env.production（本番環境用の設定）
NEXT_PUBLIC_API_URL=https://api.production.com

TypeScriptでの型安全な環境変数の使用

TypeScriptコードでは、env.d.tsという宣言ファイルを使い、プログラム内で使用する環境変数に型を指定することができます。型を明示することで、開発中に環境変数の名前を間違えたり、不適切なデータ型を扱ってしまうことを防ぎます。これにより、環境変数を使用する際にIDEの補完機能が効くようになり、コードの安全性と信頼性が向上します。

// env.d.ts
declare namespace NodeJS {
  interface ProcessEnv {
    NEXT_PUBLIC_API_URL: string;  // APIのURL
    API_SECRET_KEY: string;       // APIの秘密キー
  }
}

まとめ

Vercelにおける環境変数の設定は、開発フローの重要な部分を占めています。ローカル開発環境では.env.localファイルを使用し、本番環境ではVercel管理画面から設定を行うという基本的な流れを押さえることが重要です。特に、環境変数の命名規則やデプロイのタイミングに注意を払うことで、多くの一般的なトラブルを回避することができます。

第1部では、環境変数の基本的な概念から、.envファイルの種類と使い分け、TypeScriptでの活用方法まで、Next.jsにおける環境変数の基礎を詳しく解説しています。
【保存版】Next.jsの環境変数完全ガイド 📖 envファイルの使い方を基礎から解説

もし記事の内容に間違いがあれば、コメントでご指摘いただけますと幸いです。また、より良い方法や代替手段をご存知の方がいらっしゃいましたら、ぜひ共有していただければと存じます。例えば、CI/CDパイプラインでの環境変数の扱い方や、大規模プロジェクトでの環境変数管理の方法など、実践的な知見をお持ちの方からのフィードバックをお待ちしております。