Next.js開発で「dev起動中にnext buildを実行すると全ルートが500エラーになる」原因と復旧手順

ローカル開発環境で npm run dev(開発サーバー)を起動したまま、別のターミナルで本番用ビルドの確認のために npm run build を実行。その後、開発サーバーでブラウザを更新すると、全ページが500内部エラーになり、プレビューができなくなります。

原因と落とし穴

Next.jsの開発サーバーとビルドプロセスは、同じ .next フォルダ(キャッシュおよび成果物)を使用します。ビルドが走ることで開発サーバー用のキャッシュが上書き・破壊され、古いプロセスが整合性の取れない中間ファイルを読み込もうとしてクラッシュすることが原因です。

切り分け・対処手順

プロセスの停止: まずは起動しているすべての開発サーバー(dev)プロセスを終了させます。

キャッシュの完全物理削除: プロジェクトルートにある .next フォルダを手動で完全に削除します(rm -rf .next)。

サーバーの再起動: 再度 npm run dev を実行し、キャッシュがクリーンな状態で再生成されることを確認します。

まとめ

Next.jsでは開発環境とビルド環境の並行実行はキャッシュの競合を招きます。「ビルドの前にはdevを止める、エラーが出たら迷わず.nextを消す」が、フロントエンド開発における鉄則です。