Vercel：Gitに.envを含めない場合の環境変数設定

このガイドは、すでにVercelでホストされているプロジェクトを対象としています。プロジェクトの設定にアクセスでき、アプリケーションがどの変数を読み取るかを理解している必要があります。以下の例はNext.jsに適用されます。別のフレームワークの変数名をそのまま使えるとは限りません。このガイドは公式ドキュメントに基づいており、実際のアカウントではテストされていません。

Ailootの実用的な利用情報はドキュメントで確認できます。

.envをGitに追加する必要がない理由#

環境変数とは、アプリケーションがソースコードとは別に受け取る、名前と値を持つ設定です。たとえば、SERVICE_API_KEYという名前を使うと、プログラムは外部サービスのキーの値にアクセスできます。キーそのものをガイドやエージェントとの会話、リポジトリに記載しないでください。

Next.jsは、ローカルの.env*ファイルから変数を読み込めます。ただし、ローカルファイルとVercelのプロジェクト設定は別々の場所です。ファイルをリポジトリにプッシュしない場合は、ホスティングプラットフォームにも別途値を設定してください。標準のcreate-next-appテンプレートでは、.envファイルが.gitignoreに追加されます。Next.jsのドキュメントも、それらをリポジトリにプッシュすることはほとんどの場合避けるべきだと警告しています。

ソースファイルに何を保存できるかまだ不明な場合は、AIで構築したプロジェクトのセキュリティチェックから始めてください。ここでは、特定のVercelデプロイメントの設定をどこに登録するかという、より限定された質問を扱います。

まず、アプリケーションが変数を読み取る場所を確認する#

値を入力する前に、秘密情報そのものを含めず、名前の一覧を作成してください。各名前について、どの環境で使うか、変数を読み取るコードがどこで実行されるか、値がいつ必要になるかの3点を確認します。

Development環境はローカル開発用です。Previewはプレビュー用デプロイメント、Productionは公開中のメインバージョン用です。Previewでは、特定のGitブランチ向けに設定できます。同じ名前の一般的なPreview設定は、そのブランチ固有の設定で上書きされます。

Next.jsプロジェクトでは、NEXT_PUBLIC_が付いていない変数は、デフォルトでサーバーから利用できます。NEXT_PUBLIC_プレフィックスを付けると、その値をブラウザーに配信するJavaScriptに埋め込めます。秘密ではないバージョンラベルなど、明示的に公開する設定には適していますが、秘密のAPIキーには使えません。このプレフィックスがなくても、アプリケーションコードから秘密情報を手動でクライアントに返してはいけません。

フレームワークがまだ特定できていない場合は、プロジェクトファイルを確認して特定するようエージェントに依頼してください。AstroとNext.jsの比較は違いを理解する助けになります。NEXT_PUBLIC_のルールをすべてのReactアプリケーションに適用できるわけではありません。

ホスティングの設定は、AIエージェントを使ったアプリケーション開発に含まれる作業の一つです。

Vercelプロジェクトに変数を追加する方法#

公式ダッシュボードで、手順を自分で行ってください。フォームに入力させるために、実際のキーをエージェントに渡さないでください。値が見えるスクリーンショットも添付しないでください。

1. Vercelダッシュボードを開き、正しいプロジェクトを選択します。リポジトリ名が一致することだけに頼らず、開く予定のアプリケーションを設定していることを確認してください。
2. プロジェクト設定のサイドバーでEnvironment Variablesを開きます。
3. Nameに、アプリケーションが読み取る名前を入力します（例：SERVICE_API_KEY）。これは名前の例です。コードが別の名前を想定している場合は、その名前を正確に入力してください。
4. Valueに、認証情報の保管場所から値を入力します。ソースコード、チャット、確認ログには記載しないでください。
5. この設定が必要な環境を選択します。プレビュー版の確認にはPreview、メインバージョンにはProductionを使います。一つの秘密情報をすべての環境に自動的に割り当てないでください。
6. Previewの設定が特定のブランチに適用される場合は、選択したブランチと、同じ名前の上書き設定を確認します。
7. Saveをクリックします。

Vercelは、ビルド時とサーバー側でVercel Functionsを実行するときの両方で、プロジェクト変数を利用可能にします。ただし、Vercel内で利用できるからといって、ブラウザーに送信してよいとは限りません。それはアプリケーションコードとフレームワークのルールによって決まります。

Saveの後に新しいデプロイメントが必要な理由#

変数を保存しても、既存のデプロイメントは変更されません。Vercelのドキュメントでは、新しい設定を使用中のバージョンに反映するには、プロジェクトを再デプロイする必要があるとされています。

Gitを使っている場合、Production Branchで指定されたブランチにコミットをプッシュすると、新しいProductionデプロイメントを作成できます。別のブランチにプッシュすれば、Previewデプロイメントを作成できます。メインブランチが常にmainだとは限りません。プロジェクトの設定を確認してください。これは通常の合意済みプロジェクトリリースとして行い、秘密ファイルをコミットに追加しないでください。

デプロイメントを開始したら、ビルドが完了するまで待ち、新しいデプロイメントのURLを開きます。URL、環境、ブランチを記録してください。個別の古いデプロイメントのURLを確認しても、新しい設定は反映されません。

Next.jsには、もう一つ条件があります。process.env.NEXT_PUBLIC_RELEASE_LABELのような参照は、next buildの実行時に値へ置き換えられます。値はビルド後に固定されます。新しいビルドを行わずに設定を変更しても、すでに配信済みのクライアント側JavaScriptは書き換わりません。

キーを公開せずに結果を確認する方法#

まず、NEXT_PUBLIC_RELEASE_LABELという名前で、preview-checkという値を持つ、明示的に秘密ではないラベルを例として使います。これらは名前とテキストの例であり、キーでも、ここで実施したテストでもありません。Next.jsアプリケーションがこの変数をprocess.env.NEXT_PUBLIC_RELEASE_LABELで直接読み取る場合、新しいビルドの後、意図したインターフェースの場所にラベルを表示できます。この確認で分かるのは、公開設定が渡されたことだけです。

秘密鍵は別の方法で確認します。その値、一部、長さ、process.env全体を出力しないでください。変数の内容を返す公開URLも作成しないでください。まずサーバー上で設定が「存在／不在」かだけを確認し、その後、サービスを使うアプリケーション関数を別途確認します。設定が存在しても、キーが有効で、必要な権限を持っているとは限りません。

秘密情報を含めずに、次の結果を記録できます。

• プロジェクト、環境、ブランチが、設定時に選択したものと一致している。
• 変数を保存した後に作成された、新しいデプロイメントのURLを確認している。
• ビルドが完了し、必要なアプリケーション関数が安全なテストデータで実行された。
• 秘密情報がブラウザー、APIレスポンス、ログ、会話に露出していない。

関数が決済、メッセージ送信、または結果を伴うその他の処理を行う場合は、サービス指定のテストモードを使用してください。設定を確認しても、それだけで実際の処理が許可されるわけではありません。

値がまだundefinedの場合に確認すること#

undefinedは、そのアクセス箇所で値が取得できなかったことを意味します。すべての設定を一度に変更せず、名前、環境、バージョンの順に確認してください。

名前、環境、新しいバージョンを確認しても関数でエラーが出る場合、変数が原因だとは限りません。秘密情報を含む診断データを公開せず、サーバー側コードの具体的なエラーを調査してください。このガイドは、あらゆるHTTP 500レスポンスの解決を保証するものではありません。

自分のサーバーへの移行には別の手順が必要です。Coolifyを使ったプロジェクトのデプロイガイドを参照してください。Vercelのボタン名や設定手順は適用されません。

Ailootに移動。