Vercel で Next.js をデプロイしていると、「ビルドが途中で止まる」「デプロイが失敗する」といった現象が起きることがあります。今回のケースでは、環境変数を vercel.json に直接記述していたことが原因でした。一見すると便利そうに見えますが、この書き方は Vercel では非推奨であり、シークレット管理と衝突してビルドエラーを引き起こします。本記事では、このエラーが発生する仕組みと、正しい環境変数設定方法を整理して紹介します。
エラーの原因：vercel.json に環境変数を書くと Vercel の管理方式と衝突する
問題となる例は次のような記述です。
{
"env": {
"API_KEY_NAME": "your-key-here"
}
}
Vercel は、環境変数を設定ファイルに直接書くことを許可していません。
理由は、セキュリティ・管理・ビルド処理の観点で、この方式が Vercel の仕組みと一致しないためです。
そのため、vercel.json に env ブロックが存在すると、
- デプロイが停止する
- CLI がエラーを返す
- Secret 機能と衝突する
といったトラブルが発生します。
Vercel がこの方式を禁止している理由
Vercel が環境変数を CLI・管理画面で管理する方式に統一している背景には、次のような理由があります。
- API キーなどの秘密情報が Git に混入するリスクを防ぐため
- Production・Preview・Development の値を安全に切り替えるため
- キーの更新や削除を UI/CLI で一元管理できるため
- Vercel のセキュアストレージと整合性を保つため
つまり、vercel.json に書いてはいけないのではなく、Vercel が “書いてほしくない構造” を作っているためにエラーが出るというわけです。
正しい環境変数の設定手順
デプロイを安定させるには、Vercel が推奨する方法で環境変数を登録する必要があります。
① 初回デプロイ（プロジェクトを登録する）
vercel
② CLI で環境変数を追加する
以下は例です（API 名は任意）：
vercel env add API_KEY_NAME
値を入力し、
- Production
- Preview
- Development
すべてに適用します。
③ 環境変数を反映した状態でデプロイ
vercel --prod
これでビルドが正しく通るようになり、API キーも安全に管理された状態でデプロイされます。
この問題が起きやすい場面
今回のようなエラーは、次のような状況で発生しがちです。
- 他サービスの設定ファイルにならって env を書いた場合
- 古いチュートリアルを参照した場合
- ローカルのみで動作していた設定をそのまま Vercel に持ち込んだ場合
- リポジトリを複製して再デプロイした場合
根本的には「設定ファイルとシークレット管理の衝突」が原因のため、env 記述を削除するだけで解消されるケースが多いです。
まとめ
今回のデプロイ失敗は、コードの問題ではなく、環境変数の置き場所が不適切だったことによって発生していました。Vercel の環境変数は、必ず CLI または UI から設定する必要があります。この方式に統一することで、再発を防ぎ、安定した運用が可能になります。
参考 URL
- Vercel Documentation – Environment Variables
https://vercel.com/docs/projects/environment-variables - Configuration (
vercel.json)
https://vercel.com/docs/projects/project-configuration - Vercel CLI – Managing Variables
https://vercel.com/docs/cli/env
