ローカルでは動くのにデプロイすると失敗する — 直し方 (Vercel・Netlify) | Vibe Coding Rescue

npm run dev では動くのに、Vercel/Netlify にデプロイすると真っ白な画面・Module not found・データが出ない、という症状が出る。本当の5つの原因と具体的な直し方を、非エンジニアにもわかる手順で解説します。

ローカルでは動くのにデプロイすると失敗する — 直し方 (Vercel・Netlify)

ローカルでは動くのにデプロイ後だけ壊れるとき、この5つを順番にチェック — 環境変数、再デプロイ、ファイル名の大文字小文字、localhost のハードコード、そしてビルドコマンド。

症状

npm run dev では自分のマシンで完璧に動くのに、Vercel や Netlify に push した途端、真っ白な画面や「Module not found」というビルドエラー、あるいはいつまでも読み込まれないデータに悩まされる。これは、vibe コーディングで作ったアプリを初めてデプロイするときにもっともよく起きる問題で — 原因はほぼ必ず次の5つのどれかです。

根本的な理由はシンプルです。あなたの PC とデプロイ先のサーバーは、まったく別の「環境」だからです。あなたのコンピュータにしか存在しなかった設定・ファイル・URL は、サーバーにはありません。下の5つのチェックを順番に進めれば、たいていのケースは解決します。

1. デプロイ先のプラットフォームに環境変数を登録していない — 最多

PC 上の .env ファイルは、あなたの PC の中だけに存在します。ふつう git にはコミットしないので、Vercel や Netlify はその存在すら知りません。つまり API キーやデータベース URL といった値が本番では空になり、アプリがクラッシュします。

直し方 — Vercel:

Vercel のダッシュボード → 対象のプロジェクトを開く
上部ナビの Settings → 左サイドバーの Environment Variables
Key(例: VITE_SUPABASE_URL)と Value を入力 → Production・Preview・Development にチェック → Save
Deployments タブへ → 最新デプロイの横の ⋯ → Redeploy

> 重要: Vercel は環境変数の変更を *新しい* デプロイにだけ反映し、既存のデプロイには決して反映しません。値を追加したら、有効にするために必ず再デプロイしてください。

直し方 — Netlify:

Netlify のダッシュボード → 対象のサイトを開く
Site configuration → Environment variables → Add a variable
Key/Value を入力 → Save
Deploys タブ → Trigger deploy → Clear cache and deploy site

注意: ブラウザ側で使う値には決まった接頭辞が必要

フロントエンド(ブラウザ)のコードから読む環境変数は、正しい接頭辞が付いていないとページまで届きません。付いていないと、値は undefined で返ってきます。

フレームワーク	接頭辞	読み方
Next.js	`NEXT_PUBLIC_`	`process.env.NEXT_PUBLIC_XXX`
Vite (React/Vue)	`VITE_`	`import.meta.env.VITE_XXX`
Create React App	`REACT_APP_`	`process.env.REACT_APP_XXX`

これらの接頭辞が付いた値はブラウザのバンドルに露出するので、本物の秘密情報(データベースのパスワードなど)は絶対にこの接頭辞の後ろに置かないでください。

2. 環境変数を変えたのに再デプロイしていない

環境変数の値は ビルド時にコードへ焼き込まれ、そこで固定されます。Next.js・Vite・Create React App はいずれも、ビルド中に値を埋め込みます。だからダッシュボードで値を書き換えても、リビルドするまで古い値のままです。

直し方: 値を変えたら、もう一度 Redeploy(Vercel)/ Trigger deploy(Netlify)を押して、まっさらなビルドを強制してください。

3. ファイル名の大文字小文字が一致していない — 「Module not found」

macOS と Windows は Button.tsx と button.tsx を同じファイルとして扱います(大文字小文字を区別しない)。ところが Vercel と Netlify は Linux 上でビルドし、Linux は大文字小文字を厳密に区別します。だから実際のファイルが Button.tsx なのに import で小文字を使っていると、ローカルでは通っても、デプロイ時に「Module not found」で失敗します。

直し方: import のパスを、実際のファイル名と一字一句・大文字小文字まで完全に一致させてください — フォルダ名も同じです。


// Real file: src/components/Header.tsx

import Header from './components/Header'  // OK
import Header from './components/header'  // FAILS on deploy: Module not found

4. localhost の API URL をハードコードしている

http://localhost:3000 のような URL をコードに直書きすると、ローカルでは自分のサーバーなので動きます。でもデプロイ後のサイトでは、そのアドレスは「訪問者自身のコンピュータ」を指すので、何も返ってきません。

直し方: URL を環境変数に移し、方法1のやり方で本物のデプロイ先アドレスを登録してください。


// Wrong — a local address baked into the code
fetch('http://localhost:3000/api/users')

// Fixed — pull the address from an env var (Vite example)
fetch(`${import.meta.env.VITE_API_URL}/api/users`)

5. ローカルは dev、デプロイは build を実行 — ビルドでしか出ないエラー

npm run dev は開発サーバーで、多くの問題を大目に見てくれます。デプロイでは npm run build(本番ビルド)が走り、こちらは型エラーや import エラーにずっと厳しいです。

直し方: push する前に、まったく同じビルドをローカルで実行して問題を先に洗い出しましょう。


npm run build

ここで表示されたエラーが、デプロイ失敗の原因そのものです。ローカルでそのエラーを消してから push してください。

最終チェックリスト

.env の値をすべて Vercel/Netlify にも登録しましたか?
ブラウザ側で使う変数に NEXT_PUBLIC_ / VITE_ / REACT_APP_ の接頭辞は付いていますか?
値を追加・変更したあとに再デプロイしましたか?
import のパスは、大文字小文字も含めて実際のファイル名と一致していますか?
コード内に localhost の URL をハードコードしていませんか?
npm run build は自分のマシンでエラーなく完了しますか?

この6つをすべてクリアすれば、「ローカルでは動くのにデプロイで壊れる」問題はほぼ必ず解消します。