「ローカルでは動くのに、Vercelに上げたら真っ白」が最初の壁
未経験で初めて Next.js + Supabase のアプリを作ると、npm run dev でローカルが動いた瞬間に「できた！」と思います。でも本当の達成感は、自分のURLで誰でもアクセスできる状態にデプロイできたときにやってきます。そしてその一歩手前に、未経験がほぼ全員ハマる定番のつまずきが待っています。
結論から言うと、最初のデプロイでこける原因の多くは**「環境変数」と「Supabaseの本番設定」**に集まります。教材でこの工程を案内していても、相談が来るのはほぼこの2点です。今回はその実例と最小の直し方をまとめます。
つまずき① ローカルは動くのに、本番だけ「supabaseUrl is required」で落ちる
一番多いのがこれです。ローカルには apps/web/.env.local にキーを書いてあるので動きます。でも .gitignore を見ると、その .env.local はコミットされない設定になっています。
# env files（実際の値が入る .env / .env.local 等は無視）
.env*.local
.env
# サンプルファイルは配布するため必ずコミットする
!.env.local.example
つまり .env.local はGitに乗らない＝Vercelに届かない。これは事故ではなく正しい挙動です（キーをGitHubに上げないため）。なので本番では環境変数が空っぽになり、Supabaseクライアントの初期化で落ちます。
直し方: Vercel側に同じ環境変数を手で登録します。Vercel の Project Settings → Environment Variables で、ローカルの .env.local と同じキーを入れます。
NEXT_PUBLIC_SUPABASE_URL=https://xxxxx.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJ...
ポイントは NEXT_PUBLIC_ という接頭辞。これは「ブラウザ側に公開してよい値」という意味で、Next.js はこの接頭辞が無いとクライアントコンポーネントから読めません。登録後は再デプロイしないと反映されないのも見落としがちです（環境変数はビルド時に焼き込まれるため）。
つまずき② Root Directory を間違えてビルドが始まらない
教材リポジトリのように、docs/ や knowledge/ といった教材一式と Web アプリ（apps/web/）が同じリポジトリに同居している構成（モノレポ）だと、Vercel はリポジトリのルートを見て 「Next.js が無い」と判断し、ビルドに失敗します。
直し方: Vercel の Import 時に Root Directory を apps/web に指定するだけです。
Root Directory: apps/web
Framework Preset: Next.js（自動検出）
「リポジトリ全体」ではなく「アプリのフォルダ」を公開対象にする、という発想に切り替えるのがコツです。
つまずき③ 本番だけデータが出てこない（RLS / リダイレクトURL）
ビルドは通ってURLも出たのに、ログインした後の一覧が空っぽ。これも定番です。原因は本番側の設定漏れで、典型は次の2つです。
-
RLS（Row Level Security）: Supabase はテーブルに行レベルのアクセス制御をかけられます。ポリシー未設定だと、
SELECTしても「あなたの権限では見えません」で0件が返ります。ローカルで自分のデータしか触っていないと気づきにくい。 -
リダイレクトURL: メール認証やログイン後の戻り先が
http://localhost:3000のままだと、本番では認証ループになります。Supabase の Authentication → URL Configuration に本番URL（https://あなたのアプリ.vercel.app）を追加します。
「ローカルで動く＝本番でも動く」とは限らず、本番には本番の設定が要る、というのがフェーズが上がった証拠でもあります。
Claude Code にエラーを貼って「切り分け」を任せる
ここで効くのが AI 協働です。supabaseUrl is required のようなエラーは、未経験だと検索ワードすら分かりません。そこで Vercel のデプロイログをまるごとコピーして、こう投げます。
Vercelのデプロイでこのエラーが出た。
ローカルのnpm run devでは動いてる。原因の切り分けを手伝って。
{ビルドログを貼り付け}
すると「ローカルで動いて本番で落ちる＝環境差分。まず環境変数を確認しよう」と切り分けの順番を出してくれます。ここで身につくのは3つのスキルです。
- 指示力: 「動かない」ではなく「ローカルは動く・本番だけ落ちる・このログ」と差分を言語化して渡す力
-
出力レビューの目: AIが「環境変数を全部消して」と提案しても、
.env.localを消すのか Vercel 側を直すのかを自分で判断する力 - 役割分担: 原因の仮説出しはAI、実際にVercelの画面でキーを登録する判断は自分、という分担
この「AIに切り分けさせて、最後の判断は自分がする」流れは、デプロイに限らず実務でずっと使う型です。プログラミングの文法と同時に、AIへの指示力とレビュー力が一緒に鍛えられるのがこの工程の隠れた価値だと思っています。
まとめ：公開まで行って初めて「作れた」になる
最初のデプロイでハマるのは、ほぼこの4点です。
-
.env.localはコミットされない → Vercel に環境変数を手で登録（再デプロイ必須） - モノレポは Root Directory を
apps/webに指定 - 本番だけデータが出ない → RLSポリシーとSupabaseのリダイレクトに本番URLを追加
- エラーは Claude Code にログごと貼って切り分けさせ、判断は自分が下す
ローカルで動かすところまでは、実は通過点です。**自分のURLで世界に見せられて、初めて「アプリを作れた」**になります。まず手元で動かして、そこから公開（デプロイ）まで一度通してみると、つまずきポイントも含めて全体像が一気に腑に落ちますよ。
未経験者向けの講座を運営しています
未経験から Next.js + Supabase + Claude Code で Webアプリを作って公開するまで を、全20セッションで体系化した教材です。Claude Code を学習パートナーにする CLAUDE.md / Skills 設計までセットで含みます。
- 無料体験版（git clone してすぐ動く・最初の数セッション分・⭐ Star もよろしくお願いします）→ https://github.com/ayies128/next-ai-camp-trial
- 教材完全版＋月5,500円のメンタリング（全20セッション＋チャット質問し放題）→ https://menta.work/plan/20251?ref=qiita
- YouTube『AIエンジニア情報局』（AI×開発ニュースを1本5分でキャッチアップできる別運営チャンネル・無料）→ https://www.youtube.com/channel/UC1rXVD9WYsQPQEWZyd-A1KA/?ref=qiita
※ Qiita 読者の方には易しすぎる内容なので、初心者の知り合いへの紹介や社内研修の参考としてどうぞ。