フレームワーク
Next.js
Vercel が開発する React ベースのフルスタック Web フレームワーク。App Router・Server Components・SSR / SSG / ISR をひとつのランタイムで扱い、ファイルベースルーティングや Image / Font 最適化など本番向けの機能を標準搭載する。
バージョン移行
メジャーバージョンを上げたときに動かなくなることを、旧版と新版で同じコマンドを打ち比べて確かめた。
Next.js 15 → 16・変更点 8 つ
Next.js を 15 から 16 に上げると動かなくなること
問題一覧(15)
Next.js App Router で page.tsx を置いても 404 になる
page.tsx を置いても 404 になるときは、ファイル名・app/ 配下・default export の 3 点を直せば表示される。多くは名前違いか、pages/ への置き間違いだ。
更新: 2026-11-05、タグ: app-router、not-found、routing
Next.js の dev server が起動できない
Next.js の next dev が起動できないときは、ポート競合・Node.js バージョン・.next キャッシュ破損の 3 点を順に切り分ける。占有プロセス確認・対応 Node 確認・キャッシュ削除で大半は復旧する。
更新: 2026-11-07、タグ: dev、port、cache
Next.js App Router でサーバーコンポーネントから dynamic ssr:false が使えない
App Router のサーバーコンポーネント内で next/dynamic に ssr: false を渡すとビルドエラーになる。ssr: false はクライアントコンポーネントの中でのみ指定でき、用途が SSR off ならクライアントラッパ、遅延ロードだけなら Suspense で分離する。
更新: 2026-11-08、タグ: dynamic-import、ssr、app-router
Next.js で環境変数 (process.env) が読み込めない
Next.js の環境変数はビルド時にインライン化される。ブラウザに露出する値は NEXT_PUBLIC_ プレフィックスが必須で、.env ファイルの優先順位とビルドの再実行も意識する必要がある。
更新: 2026-11-08、タグ: env、process.env、NEXT_PUBLIC
Next.js の next/image で画像が表示できない
next/image は外部ドメイン画像に images.remotePatterns の許可が必須で、width / height の指定も要る。ローカル画像は /public 配下に置き絶対パスで参照する。
更新: 2026-10-13、タグ: image、remotePatterns、hostname
Next.js App Router で metadata(title / description)が反映されない
metadata が反映されないときは、server component の page.tsx か layout.tsx から export すれば直る。'use client' のファイルへの記述や next/head との二重指定が典型的な原因だ。
更新: 2026-11-09、タグ: metadata、app-router、seo
Next.js の middleware が実行されない
middleware.ts はプロジェクトルートに 1 ファイル限定で、matcher の設定と Edge runtime 制約に従う必要がある。配置と matcher がずれると静かにスキップされ、export 名を間違えるとリクエストがすべて 500 になる。
更新: 2026-11-10、タグ: middleware、matcher、edge
Next.js「Module not found: Can't resolve 'fs'」の原因と直し方
Can't resolve 'fs' は、fs を使う処理を Server Component や Route Handler へ移せば直る。Node のコアモジュールをクライアント側のコードで import すると出る。
更新: 2026-11-10、タグ: module-not-found、fs、use-client
Next.js App Router の not-found.tsx が呼ばれない
App Router の not-found.tsx は notFound() が throw されるか、ルートに該当パスが存在しない時のみレンダリングされる。動的セグメントで notFound() を明示的に呼ぶか、dynamicParams = false を付ける必要がある。
更新: 2026-11-10、タグ: app-router、not-found、notfound
Next.js の revalidatePath / revalidateTag が効かず古いデータが残る
revalidatePath / revalidateTag が効かないときは、fetch にタグを付け 'use server' 関数から呼べば直る。クライアント側の Router Cache は router.refresh() で更新する。
更新: 2026-10-20、タグ: revalidate、cache、app-router
Next.js の Route Handler で CORS エラーが出て呼び出せない
Route Handler の CORS エラーは、Access-Control-Allow-Origin を返し OPTIONS ハンドラを書けば直る。Route Handler には自動の CORS が無いためだ。
更新: 2026-10-06、タグ: cors、route-handler、api
Next.js の Server Action が実行できない
Server Action が実行できないときは、use server を先頭に書いた別ファイルへ関数を移し、form の action に渡せば動く。App Router 専用で、Pages Router では使えない。
更新: 2026-10-13、タグ: server-action、app-router、form
Next.js App Router で useState などのフックが使えない
useState などのフックが使えないときは、ファイル先頭(import より上)に use client を書けば直る。App Router は既定でサーバーコンポーネントのため、書き忘れや位置ミスが主な原因だ。
更新: 2026-11-11、タグ: app-router、use-client、server-component
Next.js「useSearchParams() should be wrapped in a suspense boundary」の原因と直し方
useSearchParams() should be wrapped in a suspense boundary は、呼ぶ部分を <Suspense> で包めば直る。Suspense 境界なしで使うと、ビルド時にこのエラーで失敗する。
更新: 2026-11-11、タグ: app-router、useSearchParams、suspense
Next.js「ReferenceError: window is not defined」の原因と直し方
window is not defined は、ブラウザ専用コードを useEffect 内へ移すか、ssr: false の next/dynamic で読めば直る。SSR やビルド時のプリレンダで window を参照すると出る。
更新: 2026-11-12、タグ: ssr、window、app-router