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

要約

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

よくある原因

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

解決策

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

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

Troubleshoot a Build 公式ガイド でも、最初の確認手順としてバージョン整合と env のチェックが挙げられている。

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

Vercel ダッシュボードの Project Settings → General で、フレームワーク既定から外れた上書きが残っていないか確認する。package.json に "engines": { "node": ">=20.0.0" } を書いた上で、Node.js Version を 20.x に揃える。

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"

Project Configuration 公式 でも、Vercel が lockfile を厳格に扱うため lockfile のコミットが必須と明記されている。

5. monorepo の Root Directory を設定する

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