Vercel でビルドが失敗してデプロイできない

要約

Vercel の build 失敗は、ローカルでは見えない要因が中心になる。Node メジャー版の差、Build Command / Output Directory のズレ、build-time 環境変数の不足、lockfile 不整合、monorepo の Root Directory 誤り の 5 項目を順に確認すれば、Vercel 側で再現する build エラーの大半は片付く。

解決策

1. ローカルで Vercel と同じビルドを再現する

npx vercel build   # Vercel CLI でローカルに同条件ビルドを実行
node -v            # Vercel 設定の Node メジャー版と一致しているか確認

Troubleshoot a Build 公式ガイド（新しいタブで開く）↗ でも、Vercel にデプロイする前にまず手元でビルドし、コードや依存関係に起因する問題を先に見つけることが推奨されている。

2. Build Command / Output Directory / Node 版を合わせる

Vercel ダッシュボードの Project Settings → General で、フレームワーク既定から外れた上書きが残っていないか確認する。package.json に "engines": { "node": "22.x" } を書いた上で、Node.js Version を 22.x に揃える。engines は Project Settings の指定より優先され、>=20.0.0 のような上限の無い範囲は最新の 24.x に解決される（Supported Node.js versions（新しいタブで開く）↗）。
Node.js 20 は 2026-10-01 に新しいデプロイで選べなくなった（Vercel Changelog（新しいタブで開く）↗）ので、20 系を指定したままのプロジェクトは引き上げる。

3. 環境変数を Production / Preview それぞれに登録する

Project Settings → Environment Variables の追加画面で Production / Preview / Development 各環境のチェックを入れて保存する。
Preview 用の登録漏れで「プルリクの build だけ落ちる」パターンが多い。

4. lockfile を最新化してコミット

rm -rf node_modules package-lock.json
npm install
git add package-lock.json
git commit -m "chore: refresh lockfile"

Package Managers 公式（新しいタブで開く）↗ のとおり、Vercel はコミットされた lockfile を見て package manager とそのバージョンを決める（lockfile が無いと npm が使われる）。

5. monorepo の Root Directory を設定する

Project Settings → General → Root Directory を該当アプリのパス（例 apps/web）に設定する。
複数アプリを持つリポジトリでは Project ごとに Root Directory を分けるのが基本。

よくある原因

1. Node.js バージョン差: ローカル 24 系で書いた構文や API が Vercel 側 22 系に無く落ちる、あるいはその逆。
2. Build Command / Output Directory 違い: フレームワーク自動検出を上書きした設定が残り、next build を呼べていない・出力先がフレームワーク既定と異なる。
3. build-time env 不足: NEXT_PUBLIC_* など build 中に文字列展開される値が Vercel 側に未登録、または Preview 環境にチェックが入っていない。
4. lockfile 不整合: Vercel は lockfile から package manager を判別して npm install / pnpm install などを実行する。
   ビルド環境には CI=1 が入っており、pnpm は CI では --frozen-lockfile が既定のため、lockfile と package.json が食い違うと即失敗する。
5. monorepo の Root Directory: 別アプリのルートをビルドしようとして該当アプリが見つからず失敗する。