Next.js 開発で遭遇したエラー集とその対処法まとめ
はじめに
Next.js を使っていると、公式ドキュメントに載っていない「なんでこれで怒られるの？」というエラーに出会うことがあります。この記事では、実際に開発中に遭遇したエラーと、その原因・解決方法を整理しました。未来の自分や、同じエラーで悩んでいる人の助けになれば幸いです。
1. useSearchParams の suspense エラー
エラーメッセージ
Error: useSearchParams() is missing a suspense boundary.
原因
- App Router で
useSearchParamsを使うと、<Suspense>で囲わないとエラーになる。
解決方法
import { Suspense } from "react";
import DummySearchComponent from "./DummySearchComponent";
export default function DummyPage() {
return (
<Suspense>
<DummySearchComponent />
</Suspense>
);
}
2. params 型エラー (default export が無効)
エラーメッセージ
Type error: Page "app/(group)/(feature)/dummy/page.tsx"
has an invalid "default" export: Type "DummyParams" is not valid.
原因
-
export defaultに「型」や「オブジェクト」を出してしまった。 -
page.tsxは必ず React コンポーネントを default export する必要がある。 - 動的セグメントと型のキー名が不一致なケースも多い。
解決方法
type DummyPageProps = { params: { itemId: string } };
export default function DummyPage({ params }: DummyPageProps) {
return <div>{params.itemId}</div>;
}
3. yarn.lock を Git 管理するか問題
問題点
- チーム開発で
yarn.lockをコミットするかどうかが分かれて混乱。 - ビルド時の依存バージョン差異が原因でエラーが出ることも。
ベストプラクティス
- 必ず管理する。
- チームで lockfile の扱いを統一することで、CI/CD のビルドが安定する。
4. Docker × Next.js のポート割り当てエラー
エラーメッセージ
Error response from daemon: ports are not available:
exposing port TCP 127.0.16.31:9000 -> 127.0.0.1:0: listen tcp4 ...: bind: can't assign requested address
原因
-
docker-compose.yml内でポート競合が起きている。 -
127.0.16.xxのエイリアスを Mac 環境で正しく登録できていない。
解決方法
- Mac 用の
lo0エイリアス追加スクリプトを修正。 - 競合しているポートを
docker ps/lsof -iで確認して解放。 - 無難に
0.0.0.0:9000:9000と書き換えて動作確認。
まとめ
Next.js は便利だけど、型と App Router 特有のルールに振り回されることが多いです。
「default export は必ず React コンポーネント」「動的セグメントと params のキーは一致」などの鉄則を押さえておくと、エラーを潰すのがかなり楽になります。
同じように詰まった人がこの記事に辿り着いて「あ、それ俺もやったやつだ！」と笑いながら修正できれば最高です。
タグ候補
#Next.js #TypeScript #React #Docker #フロントエンド #エラー対処