Vercelへのデプロイが失敗したら、最初のビルドエラーを確認

プロジェクトがローカルでは動くのにVercelへのデプロイで失敗する場合は、ビルドログの最初のエラーが最終行よりも重要です。

プロジェクトをVercelダッシュボードで開き、Deploymentsに移動し、失敗したデプロイを選択します。Deployment DetailsにあるBuildingを展開します。末尾のexited with 1のような行は結果を示しているだけです。上へスクロールし、最初のErrorを見つけてください。このメッセージがどのコードや設定を確認するかを示します。

プロダクションビルドをローカルで再現

プロジェクトディレクトリから以下のコマンドを実行してください：

npm run build

同じエラーが表示される場合、原因はVercel固有の設定ではなく、コードや依存関係にある可能性が高いです。本番向けビルドでは、開発サーバーが見逃していた型エラーや構文エラーを検出することがあります。最初のエラーを修正し、再びビルドを実行し、変更をプッシュしてください。

.env.localの値がVercelにない

.env.localは通常Gitから除外されるため、Vercelはローカルの環境変数を自動的に取得しません。デプロイに必要な値のみをSettings > Environment Variablesの下に追加し、正しい環境を選択してください。

環境変数の変更は既存のデプロイには効きません。値を追加または更新した後、再デプロイしてください。ブラウザに公開しても安全な値だけにNEXT_PUBLIC_プレフィックスを付けてください。これらの値はビルド時にクライアントバンドルに埋め込まれるため、APIシークレットやサーバートークンにはこのプレフィックスを使用しないでください。

ローカルとVercelのNode.jsバージョンが異なります

依存パッケージが、あるNode.jsバージョンでは動いても、別のバージョンでは失敗することがあります。Vercelは現在、20.x、22.x、24.xをサポートしており、新しいプロジェクトはデフォルトで24.xを使用します。

ローカルでnode -vを実行し、それをSettings > Build and Deployment > Node.js Versionと比較してください。package.jsonで宣言されたメジャーバージョンはダッシュボードの設定よりも優先されます：

{"engines":{"node":"22.x"}}

Module not foundならファイル名の大文字・小文字を確認

macOSの標準ファイルシステムは大文字・小文字を区別しませんが、Vercelはそれらを区別するLinux上でビルドします。ファイル名がButton.tsxであっても、コードが./buttonをインポートしている場合、ローカルでは動作するがデプロイで失敗する可能性があります。エラーのパスと実際のファイル名のすべての文字を比較してください。

Cannot find module 'xxx'のxxx部分がパッケージ名なら、package.jsonを確認してください。ローカルのnode_modulesにのみ存在し、依存関係に宣言されていないパッケージはVercelのクリーンインストールで見つからない可能性があります。npm install package-nameを実行し、更新したpackage-lock.jsonもコミットしてください。

アプリがリポジトリのサブディレクトリにある

アプリがfrontend/のようなサブディレクトリにあり、Vercelがリポジトリのルートからビルドしている場合は、package.jsonやNext.jsを見つけることができないかもしれません。ログにNo Next.js version detectedのようなメッセージがある場合、Settings > Build and Deployment > Root Directoryをアプリケーションディレクトリに設定してください。この変更は次のデプロイに適用されます。

デプロイは成功するが、リクエストが504になる

FUNCTION_INVOCATION_TIMEOUTはビルド失敗ではありません。関数が実行時間の上限を超えたことを示す504レスポンスです。Fluidコンピュートでは、現在のデフォルト実行時間は300秒で、300秒はHobbyプランの最大値でもあります。

Settings > Functionsを開き、Fluidコンピュートが有効になっているか、Max Durationがデフォルトより短く設定されていないか確認してください。古いプロジェクトでFluidが無効になっている場合、デフォルトははるかに短くなります。

標準のProおよびEnterpriseプランでは最大800秒です。Next.js App Routerのルートファイルでは、以下のように宣言できます：

export const maxDuration = 800;

Node.jsとPythonの関数では、上限を800秒から1,800秒へ延長するベータ機能を利用できます。Next.js App Routerのルートも同様にexport const maxDuration = 1800;を設定できますが、他のランタイムやフレームワークではvercel.jsonが必要になる場合があります。Hobbyワークロードで300秒を超える必要がある場合、制限を上げても解決できません。そのため、ワークフロー、キュー、または類似の設計で非同期処理に分割してください。

設定エラーによってビルド開始前にデプロイが止まり、Buildingログが作られないこともあります。その場合、ダッシュボードのメッセージ自体を読みましょう。たとえば、vercel.jsonの検証エラーなどです。助けを求める際には、最初のError、package.json、リポジトリレイアウトを含めてください。そうすれば、誰かがローカルとVercelの環境を比較できます。