Vercelのデプロイが失敗するときの原因と対処手順｜Build Logs の読み方からモノレポ設定まで

Vercel に push したらビルドが失敗した ローカルでは動くのに本番だけ壊れる ある日突然デプロイできなくなった ── Vercel を使っていると、こうした事故は遅かれ早かれ経験します。

Vercel のデプロイは、git push から自動で起動するため楽な反面、失敗の原因がコード側にあるのか、Vercel 側の設定にあるのか、依存パッケージにあるのか の切り分けが必要になります。 適当に何度もデプロイし直して ガチャ するのではなく、Build Logs を上から順に読んで、最初に赤くなった行を特定 するのが、結局いちばん速い解決方法です。

この記事では、Vercel デプロイで起きやすい失敗パターンを分類し、それぞれの典型エラーメッセージと対処手順、ロールバックや再発防止の運用まで整理します。

まず最初に見るのは Build Logs

Vercel Dashboard → Deployments → 失敗したデプロイ → Building のログ、ここに 原因の9割以上が書いてあります。

どこを直していいかわからない 状態のまま再デプロイを繰り返すと、Vercel 側のキャッシュも汚れていきます。 まず Build Logs を読む、原因を1行で言語化する、それから直す の順を守るだけで、トラブル解決の速度はかなり変わります。

デプロイ失敗の主な6パターン

具体的に Vercel で頻出する失敗パターンを整理すると、次のように分類できます。

ここからは1つずつ、エラー例と対処手順を見ていきます。

① 依存関係エラー

最も多いパターン です。ローカルでは動くのに Vercel では動かない の原因の半分以上はこれと言っていい範囲です。

代表的なエラー:

• npm ERR! ERESOLVE could not resolve
• Module not found: Can't resolve 'xxx'
• Cannot find module '/vercel/path0/...'

主な原因は次の3つ:

1. lockfile が古い、もしくは存在しない — package-lock.json や pnpm-lock.yaml を git に入れ忘れている
2. peer dependency 不一致 — React のメジャーバージョン違いなどで --legacy-peer-deps が必要
3. private パッケージへのアクセス権なし — npmrc の認証トークンが Vercel に渡っていない

対処:

② 環境変数の欠落

ローカルの .env.local にだけ書いて、Vercel に登録し忘れているケースは想像以上に多いです。

代表的な症状:

• ビルドは通るが、本番アクセス時に 500 Internal Server Error
• API ルートで process.env.DATABASE_URL is undefined
• 認証系で Missing OAUTH_CLIENT_ID

対処:

③ ビルドコマンド・出力先の設定ミス

Vercel は通常フレームワークを自動検出しますが、モノレポ構成・カスタムビルド・複数フレームワーク混在 のケースでは検出を外しがちです。

代表的な症状:

• command not found: next
• 自動検出された Framework Preset が想定と違う
• ビルドは成功するが、Output Directory が空でデプロイ後 404

対処は Project Settings → Build & Development Settings で次を明示:

• Framework Preset: 実際に使っているフレームワーク
• Build Command: 例 npm run build
• Output Directory: 例 .next、Vite なら dist
• Install Command: 例 npm ci や pnpm install --frozen-lockfile

設定後は Override のチェックを入れて、Vercel の自動検出を上書きすると安定します。

④ タイムアウト / メモリ不足

ビルドが 45分 を超えると Vercel 側で打ち切られます(プランによって異なる)。 また、Node.js のヒープが デフォルト4GB を超えると JavaScript heap out of memory で落ちます。

対処:

⑤ モノレポ・Root Directory の設定ミス

apps/web packages/ui のような構成だと、Vercel がリポジトリのルートを見てしまって そもそも Next.js プロジェクトが見つからない ことがあります。

代表的なエラー:

• No Next.js project detected in this directory
• ルートに package.json はあるが、ビルド対象は apps/web

対処:

• Project Settings → General → Root Directory を apps/web に変更
• モノレポマネージャ(Turborepo / pnpm workspaces)を使っているなら、Build Command を turbo run build --filter=web のように絞る
• 共有パッケージは transpilePackages(Next.js)や Vite の optimizeDeps で取り込めるよう設定

⑥ ビルドキャッシュ不整合

依存を大幅に変更した後など、古い .next/cache や node_modules が悪さをする ケースがあります。

対処:

• Deployments タブの該当行 → Redeploy → Use existing build cache のチェックを外す
• それでも直らなければ Project Settings → Data Cache などの個別キャッシュもクリア
• 普段は基本的にキャッシュ ON のままで OK。再現困難な不整合のときだけクリアを試す

本番が止まったときの応急処置

エラーを直す前に、ユーザーから見える本番サイトを止めない のが最優先です。

Vercel の Promote to Production は、本番運用で最も使う安全弁 です。 存在を知らない人が意外と多いですが、これがあるからこそ Vercel は 気軽にデプロイしてもいい基盤 として成立しています。

再発を防ぐ運用

事後対応より、事前に失敗を見つける運用 の方が圧倒的にコストが安いです。

特に engines でバージョンを固定する のは、昨日まで動いていたのに、Vercel が裏で Node を上げて壊れた といった事故を防げる、地味だが効く対策です。

AI 時代のデプロイ事故とどう向き合うか

AI 時代のフロントエンド基盤として Vercel が選ばれる理由 の通り、Vercel は AI とコード生成の文脈で人気を集めています。 一方で、AI が出してきたコードをよく確認せずに push する運用が増える ほど、依存関係や型エラーで Vercel ビルドが失敗するケースは増えていきます。

AI が書いたコードがローカルで動いたから本番に上げる を直行ルートにすると、上で挙げた失敗パターンに次々ぶつかります。 ローカル build → Preview Deployment → 本番 のステップを省かないこと、AI が依存を勝手に変えていないか を package.json の diff で確認すること、この2つが AI 時代の Vercel 運用では特に大切になります。

ビルド失敗の話とコストの話はつながっているので、合わせて Vercel の請求が高くなる原因と対策 も読んでおくと、再デプロイを連発した結果、関数実行時間や帯域でも請求が膨らむ という二次被害を避けやすくなります。

Vercelデプロイ失敗の対処に関するよくある質問

Q. Build Logs が長すぎて読みきれません。どこから見ればいいですか？

A. ログ下部にある赤字の Error: を最初に探し、その直前 10〜20 行を読むのが最短ルートです。Cloning repository → Installing dependencies → Building の section ごとに折りたためるので、エラーが出た section だけ展開して見るのが効率的です。

Q. ローカルでは動くのに Vercel だけ失敗します。何が違うのですか？

A. Node.js バージョン、パッケージマネージャ、環境変数の3つが最頻原因です。package.json の engines.node や .nvmrc で Node を固定し、Vercel 側の Environment Variables を確認します。それでも違えば、依存パッケージのインストール状態の差(node_modules キャッシュ汚染など)を疑います。

Q. Use existing build cache をオフにしても改善しません。

A. Vercel のキャッシュ以外に、Next.js の .next/cache や Turbo の .turbo といった内側のキャッシュもあります。Project Settings → Data Cache のクリア、もしくは依存を一度完全に削除した別ブランチで再デプロイして切り分けてみるのが有効です。

Q. デプロイは成功するのに、本番だけ 404 / 500 になります。

A. 環境変数の Production スコープ漏れ、もしくは Build Output が想定と違うケースが多いです。Function ログを Vercel Dashboard で開き、ランタイムエラーが出ていないか確認します。Build と Runtime のログは別タブなので、見落とさないようにします。

Q. Hobby プランでビルドが頻繁にタイムアウトします。

A. Hobby のビルド時間・メモリ・関数サイズの上限は Pro より厳しめです。ビルド時静的生成を ISR / dynamic に置き換える、画像処理をビルドから外す、などで縮められない場合は Pro 移行が現実的な選択肢です。詳細は 料金の境界 でも触れています。

Q. モノレポでルート以外をデプロイしたい場合は？

A. Project Settings → Root Directory をビルド対象のディレクトリに変更します。Turborepo を使っている場合は Build Command を turbo run build --filter=web のように絞ると、関係ないパッケージのビルドをスキップできて時間も短くなります。

Q. デプロイ失敗時に自動でロールバックする仕組みはありますか？

A. Vercel 自身がリリース失敗時に自動ロールバックする機能は標準では持っていません(失敗デプロイは本番に昇格しないため、現本番は維持されます)。本番が動作中に問題が判明した場合は、手動で Promote to Production から過去の成功デプロイへ切り戻す運用が基本です。

参考リンク

• Vercel Docs: Troubleshooting Build Errors
• Vercel Docs: Build and Development Settings
• Vercel Docs: Environment Variables
• Vercel Docs: Monorepos
• Vercel Docs: Promote to Production
• Next.js: Deploying