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