Next.js の dev server が起動できない

要約

next dev が起動できないときは ポート競合 → Node バージョン → .next キャッシュ の順で切り分ける。
多くの場合、占有プロセスを止めるか .next を消すだけで復旧する。next.config.js を最小構成に戻して問題を二分するのも有効。

よくある原因

1. ポート 3000 が既に使われている: 別ターミナルの next dev が残っている、または Vite / Docker / 別アプリが占有している
2. Node.js バージョンが対応外: Next.js は公式ドキュメントで対応 Node を明記している。
   範囲外は起動失敗の原因
3. .next キャッシュ破損: ブランチ切替直後や依存更新後にビルドキャッシュが矛盾する
4. 依存破損: node_modules の不整合、lockfile と package.json の不一致
5. next.config.js の問題: 文法エラーや、削除された旧オプション（swcMinify など）の残置

解決策

1. ポート競合を確認する

lsof -i :3000                  # macOS / Linux
netstat -ano | findstr :3000   # Windows

該当プロセスを終了するか、別ポートで起動する。

npx next dev -p 3001

2. Node.js バージョンを確認する

node -v

Next.js の CLI ドキュメント で必要バージョンを確認し、nvm や volta で切替える。

nvm use 20

3. キャッシュと依存を作り直す

rm -rf .next node_modules package-lock.json
npm install
npm run dev

.next 削除だけで直ることも多い。
まず .next を試し、ダメなら node_modules まで広げる。

4. next.config.js を切り分ける

最小構成にして起動を試す。

/** @type {import('next').NextConfig} */
const nextConfig = {};
module.exports = nextConfig;

起動できれば、削った設定を 1 つずつ戻して原因オプションを特定する。
各オプションのサポート状況は公式の設定リファレンスで確認する。