Cursorで作ったNext.jsアプリがVercelでデプロイエラーになる原因と対処法5選

CursorなどのAIツールを使って爆速でコーディングしたものの、いざVercelにデプロイしようとするとエラーが出て進まない……という経験はありませんか？ 「ローカルでは動く」のに本番環境では動かない、というのはWeb開発における最大の落とし穴の一つです。

この記事では、AI生成コードでよく遭遇するVercelデプロイエラーの代表的な原因と、その対処法を5つ紹介します。

1. 環境変数の設定漏れ

最も多いのが .env.local の設定漏れです。ローカルでは.env.localファイルにAPIキーなどを記載して動作させますが、Vercel上でも同様にEnvironment Variablesを設定する必要があります。

対処法: Vercelのプロジェクト設定画面 > Settings > Environment Variables から、必要なキーと値をすべて登録してください。特に NEXT_PUBLIC_ プレフィックスの有無には注意が必要です。

2. 大文字・小文字のファイル名不一致

macOSやWindowsのローカル環境ではファイル名の大文字・小文字を区別しないことがありますが、VercelのLinux環境では厳密に区別されます。例えば components/Button.tsx を import Button from './button' と書いていると、ローカルでは動いてもデプロイ時に Module not found エラーになります。

対処法: import文のパスと実際のファイル名が完全に一致しているか、大文字小文字を含めて確認してください。

3. "use client" の記載漏れ

Next.js App Routerでは、Reactフック（useState, useEffectなど）を使用するコンポーネントにはファイルの先頭に "use client" ディレクティブが必要です。AIがこれを忘れることがよくあります。

対処法: エラーログを見て、CreateContext やフック関連のエラーが出ているコンポーネントの先頭に "use client" を追加してください。

4. ビルド時の型エラー（TypeScript）

ローカル開発サーバー（npm run dev）では型エラーがあっても画面は表示されますが、本番ビルド（npm run build）では型チェックが厳密に行われ、エラーがあるとデプロイが中断されます。AIが生成したコードには、any型にしてしまえば動くものの、厳密には型定義が不足しているケースが多々あります。

対処法: まずはローカルで npm run build を実行し、エラー箇所を特定して修正してください。どうしても急ぐ場合は、next.config.js で型チェックを無視する設定も可能ですが、本番品質としては推奨されません。

5. データベース接続のタイムアウト

Supabaseなどの外部DBに接続する場合、VercelのEdge FunctionsやServerless Functionsからの接続がタイムアウトしたり、接続数制限に引っかかったりすることがあります。

対処法: 接続プーリング（SupabaseならTransaction Pooler）を使用するか、接続文字列を適切に設定し直す必要があります。

AIでのコーディングは「書く」スピードを劇的に上げますが、「動かす」環境への適応までは完全にカバーしてくれません。 もしデプロイエラーの解消に時間を取られすぎているなら、プロの手を借りて「最後の仕上げ」だけを行うのも一つの手です。