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

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

根本的な原因はシンプルです。AIはあなたのローカル環境で動くコードを生成しますが、Vercelの本番環境との差異を考慮していないのです。ローカルでは存在する .env.local ファイル、大文字小文字を区別しないmacOSのファイルシステム、長めの起動時間——これらがVercel上では全く違う条件になります。

よく出るエラーメッセージと対処法

1. 環境変数の設定漏れ

Vercelのビルドログに出るエラー例：

Error: Missing required environment variable: OPENAI_API_KEY
TypeError: Cannot read properties of undefined (reading 'split')

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

対処法： Vercelのプロジェクト設定画面「Settings > Environment Variables」から、必要なキーと値をすべて登録してください。特に NEXT_PUBLIC_ プレフィックスの有無には注意が必要です。NEXT_PUBLIC_ がついた変数はブラウザ側から読めますが、ついていない変数はサーバー側でしか読めません。AIが生成するコードでは、このプレフィックスが間違っていることがよくあります。

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

Vercelのビルドログに出るエラー例：

Module not found: Can't resolve './button'
Error: Cannot find module '../components/Header'

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

対処法： import文のパスと実際のファイル名が完全に一致しているか、大文字小文字を含めて確認してください。AIは既存ファイル名を正確に把握せずにimport文を書くことがあるため、ファイル名とimportパスの一致確認は毎回の習慣にしてください。

3. "use client" の記載漏れ

Vercelのビルドログに出るエラー例：

Error: useState is not allowed in Server Components.
You're importing a component that needs useEffect. It only works in a Client Component but none of its parents are marked with "use client".

Next.js App Routerでは、Reactフック（useState、useEffectなど）やブラウザAPIを使用するコンポーネントには、ファイルの先頭に "use client" ディレクティブが必要です。AIがこれを忘れることが頻繁にあります。特に、既存のコンポーネントにフックを追加するような編集をAIに依頼した際に発生しやすい。

対処法： エラーメッセージに記載されているコンポーネントのファイルを開き、先頭に "use client" を追加します。ただし、闇雲にすべてのファイルに追加するのは避けてください。サーバーコンポーネントの利点（パフォーマンス、セキュリティ）が失われます。

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

Vercelのビルドログに出るエラー例：

Type error: Argument of type 'string | undefined' is not assignable to parameter of type 'string'.
Type error: Property 'user' does not exist on type '{}'

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

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

// next.config.js（緊急回避用、本番では使わないこと）
const nextConfig = {
  typescript: {
    ignoreBuildErrors: true, // 本当に緊急時のみ
  },
}

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

Vercelのビルドログ・ランタイムエラー例：

Error: connect ETIMEDOUT
PrismaClientInitializationError: Can't reach database server

Supabaseなどの外部DBに接続する場合、Vercelのサーバーレス環境からの接続には特有の問題があります。サーバーレス関数は毎回新しい接続を張ろうとするため、接続数制限に引っかかったり、接続確立に時間がかかりタイムアウトしたりします。

対処法： Supabaseなら「Transaction Pooler」の接続文字列（ポート6543）を使用してください。直接接続（ポート5432）ではなく、コネクションプーラー経由の接続に切り替えることで解決することがほとんどです。

さらに遭遇しやすい3つのエラー

6. ServerコンポーネントでブラウザAPIを使っている

エラー例：

ReferenceError: window is not defined
ReferenceError: localStorage is not defined

window、document、localStorage はブラウザ環境にしか存在しません。App Routerのサーバーコンポーネントでこれらを使おうとすると、Vercelのサーバー環境（Node.js）で実行されるためエラーになります。AIはこの区別を間違えることがあります。

対処法： 該当コンポーネントに "use client" を追加するか、typeof window !== 'undefined' のガードを追加してください。

7. パッケージのバージョン非互換

エラー例：

Error [ERR_REQUIRE_ESM]: require() of ES Module not supported
Cannot find module 'xxx' from 'node_modules/yyy'

ローカルのNode.jsバージョンがVercelのデプロイ環境のバージョンと異なる場合に発生します。AIは最新バージョンのパッケージを使うコードを生成することがありますが、Vercelのデフォルトのランタイムバージョンが古いと非互換が生じます。

対処法： package.json に engines フィールドを追加して、Node.jsのバージョンを明示してください。

{
  "engines": {
    "node": ">=20.0.0"
  }
}

Vercelのプロジェクト設定「Settings > General > Node.js Version」からも変更できます。

8. Static generationの失敗

エラー例：

Error occurred prerendering page "/blog/[slug]"
Error: No fallback specified for dynamic route

generateStaticParams でダイナミックルートを静的生成する際、APIやDBが到達できない、またはデータが0件の場合に失敗します。ビルド時にAPIを叩いてデータを取得する設計になっていると、ビルド環境からそのAPIに到達できないと失敗します。

対処法： dynamicParams = true を設定するか、フォールバックの処理を追加してください。

デプロイ前の必須ルーティン

Vercelにプッシュする前に、ローカルで本番ビルドを実行する習慣をつけてください。これだけで上記のエラーの大半は事前に発見できます。

npm run build
# エラーがなければ
npm run start

npm run dev で動いても npm run build が通らないコードは本番で動きません。AIはdevモードで動くコードを生成しがちで、buildモードでの動作までは保証してくれません。

Vercelのビルドログの読み方

「Build failed」と表示されたら、Vercelダッシュボードの「Deployments」タブで対象のデプロイをクリック→「Build Logs」を開いてください。重要なのはログの末尾です。エラーメッセージは最後の方に集中しています。

エラーメッセージをそのままコピーしてAIや検索エンジンに貼り付けると、解決策が見つかることがほとんどです。「Build failed」だけ見て詰まるのではなく、必ずログの中の具体的なエラーメッセージを確認してください。

1つのエラーに2時間以上詰まるようであれば、自力解決の費用対効果を考えましょう。デプロイまわりのエラーはプロのエンジニアなら30分で解決できることが多く、時間を浪費するより依頼した方が結果的に安上がりです。