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