未経験がNext.jsアプリを初めてVercelにデプロイして踏んだエラーと対処 — AIへのエラーログの渡し方

この記事について

「ローカルでは npm run dev で動くのに、いざ公開しようとすると詰まる」——未経験が初めてのデプロイで踏むエラーは、実はかなりパターンが決まっています。

この記事では、Next.js（App Router）アプリを初めて GitHub → Vercel で公開するときに実際に踏みやすいエラーと、その対処を、**「AIにエラーをどう渡すと解決が速いか」**という観点でまとめます。

前提

• ローカルで npm run dev は動いている
• git はまだ、または一度も触っていない
• GitHub アカウントはある

1. 初コミット時：node_modules を丸ごと上げてしまう

一番最初の事故がこれです。.gitignore を用意せずに git add . すると、node_modules まで追跡対象に入ってしまいます。

# やりがちな流れ
git init
git add .        # ← node_modules も .next も全部入る
git commit -m "first commit"

Next.js は create-next-app で作れば .gitignore が自動生成されますが、手動で作り始めた場合は無いことがあります。最低限これだけ入れておきます。

node_modules
.next
.env*.local

すでに commit してしまった後なら、追跡から外します。

git rm -r --cached node_modules
git commit -m "remove node_modules from tracking"

2. push 時：Support for password authentication was removed

GitHub に HTTPS で push しようとすると、パスワード認証が使えず弾かれます。

remote: Support for password authentication was removed on August 13, 2021.
fatal: Authentication failed for 'https://github.com/...'

対処は Personal Access Token（PAT）を発行してパスワード代わりに使うか、SSH 接続に切り替えるかの2択です。未経験の段階では、GitHub CLI（gh）を使うのが一番つまずきません。

gh auth login   # ブラウザ認証で完結する
git push -u origin main

3. Vercel デプロイ時：ローカルで動くのにビルドが落ちる

Vercel に GitHub リポジトリを繋ぐと自動でビルドが走りますが、ここで 「ローカルでは動くのに Vercel では失敗する」 が頻発します。原因の大半は次の2つです。

3-1. 環境変数が Vercel 側に無い

.env.local は .gitignore で除外している（すべきです）ため、Vercel には値が渡っていません。Supabase を使っている場合、たとえばこんなエラーになることがあります。

Error: supabaseUrl is required.

Vercel の Project → Settings → Environment Variables に、ローカルと同じキーを登録して再デプロイします。NEXT_PUBLIC_ 付きの変数はビルド時に埋め込まれるので、登録後に必ず再ビルドが必要です。

3-2. 型エラー・ESLint エラーでビルドが止まる

ローカルの npm run dev は型エラーがあっても動きますが、next build は止まります。

Type error: 'user' is possibly 'null'.

next.config.js で typescript.ignoreBuildErrors を有効にすれば無理やり通せますが、これは公開後にバグを埋め込むだけなのでおすすめしません。ここは握りつぶさず、user が null の可能性をちゃんと分岐する（if (!user) return ...）のが本筋です。型エラーは「デプロイ前にバグを見つけてくれている」と捉えると、直す価値が分かります。

エラーは「そのまま貼る」のが最速

ここまでのエラーに共通する対処のコツは、エラーログを一字一句そのまま AI に貼ることです。

❌ 「デプロイが失敗しました。どうすればいい？」
✅ 「Vercel でビルドが失敗した。原因と直し方を初心者に分かる言葉で。ログはこれ:
（Vercel の Build Logs をそのまま貼る）」

要約して渡すと情報が落ちて的外れな回答になります。生ログには失敗した行・ファイル・環境変数名まで含まれているので、そのまま渡すと原因の特定がかなり速くなります。「初心者に分かる言葉で」を添えると、専門用語の壁も同時に越えられます。

まとめ

初デプロイで踏むエラーは、.gitignore 漏れ・認証・環境変数・ビルド時型エラーにほぼ集約されます。どれも「初めてだから」踏むだけで、一度通れば次から怖くなくなります。詰まったらログをそのまま AI に渡す、これだけ覚えておけば公開まで到達できます。

---

※ Qiita 読者の方には易しすぎる内容なので、プログラミング未経験の知り合いへの紹介や、社内研修・後輩育成の参考としてどうぞ。

未経験から Next.js + Supabase + Claude Code で Webアプリを作って公開するまでを体系化した教材があります。

• まず無料で試す（教材体験版・最初の数セッションを無料で試せます）→ 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