Next.jsで学ぶReact講座 90日コース | Next.js基礎 - Day 44:Error Handling

React Next.jsで学ぶReact講座90日コース
スポンサーリンク
スポンサーリンク

Day 44:Error Handlingで存在しないページと予期しないエラーを安全に処理する

Day 44では、Next.js App RouterのError Handlingを学びます。今日は、error.tsx、notFound()、not-found.tsxを使って、存在しないページをきれいに処理する方法と、予期しないエラーが起きたときに画面を壊さず案内する方法を理解します。Next.jsでは、存在しないデータにはnotFound()を使い、予期しない例外にはerror.tsxによるエラーバウンダリーを使います。error.tsxはClient Componentである必要があります。 (🔗 nextjs.org)

初心者が最初に混乱しやすいのは、404系の「見つからない」と、バグや通信失敗などの「エラー」を同じものだと思ってしまうことです。実際には役割が違います。記事が存在しない場合はnotFound()、コードの不具合や想定外の失敗はthrow new Error()や例外として扱い、error.tsxで受け止めます。 (🔗 nextjs.org)

Day 44で学ぶこと

  • `error.tsx`が何をする特別なファイルかを理解します。
  • `notFound()`が何をする関数かを理解します。
  • `not-found.tsx`が404表示用の特別なファイルだと理解します。
  • 「存在しないページ」と「予期しないエラー」の違いを理解します。
  • ブログ詳細ページで、存在しない記事IDをきれいに処理します。

まず結論を先に理解する

最初に大事なルールを短く整理します。

  • 存在しない記事、存在しない商品、存在しないユーザーは、`notFound()`で処理します。
  • 予期しない例外やバグは、`error.tsx`で受け止めます。
  • `error.tsx`はClient Componentである必要があります。
  • `notFound()`を呼ぶと、そのセグメントの描画を終了し、対応する`not-found.tsx`を表示できます。また、`noindex`も挿入されます。

この4つを理解できると、Day 44の全体像がかなり見えやすくなります。

404とエラーは何が違うのか

この違いはとても重要です。

404系の「見つからない」

たとえば、/blog/999というURLが開かれたとしても、記事ID999が存在しないだけなら、それは「壊れた」わけではありません。単に、そのデータが存在しないだけです。こういう場合に使うのがnotFound()です。 (🔗 nextjs.org)

予期しない「エラー」

一方で、API通信が失敗した、コードの中で想定外の値が来た、何かの処理で例外が起きた、という場合はエラーです。こうした予期しない例外は、Next.jsではエラーバウンダリーで扱います。App Routerでは、ルートセグメント内にerror.tsxを置くと、そのセグメントの子で起きた未捕捉例外を受け止めるUIを作れます。 (🔗 nextjs.org)

notFound()とは

notFound()は、Next.jsが用意している関数です。これを呼ぶと、そのルートセグメントの描画を終了し、対応するnot-found.tsxを表示できます。さらに、検索エンジン向けに<meta name="robots" content="noindex" />も追加されます。 (🔗 nextjs.org)

たとえば、次のように使います。

// notFound関数を読み込みます
import { notFound } from "next/navigation";

// データが見つからなければ404扱いにします
if (!post) {
  notFound();
}
TSX

ここで重要なのは、notFound()は普通のreturn値ではなく、その場で描画を打ち切る特別な動きをすることです。公式ドキュメントでも、return notFound()と書く必要はないと説明されています。 (🔗 nextjs.org)

not-found.tsxとは

not-found.tsxは、404表示用の特別なファイルです。notFound()が呼ばれたときや、ルート単位で404を処理したいときに、このUIが使われます。 (🔗 nextjs.org)

最小例は次の通りです。

// 404用の画面です
export default function NotFound() {
  return <h1>404 - ページが見つかりません</h1>;
}
TSX

error.tsxとは

error.tsxは、予期しないエラーを表示するための特別なファイルです。Next.jsはエラーバウンダリーを使って未捕捉例外を処理します。error.tsxをセグメント内に置くと、その配下で起きた例外を受け止め、通常の画面の代わりにエラーUIを表示できます。 (🔗 nextjs.org)

とても重要なルールとして、error.tsxはClient Componentでなければいけません。そのため、ファイルの先頭に"use client"を書きます。 (🔗 nextjs.org)

今日作る実践の完成イメージ

今回は、ブログ詳細ページを題材にして、次の3つを作ります。

  • 存在しない記事IDなら`notFound()`で404表示する。
  • 404用UIとして`not-found.tsx`を作る。
  • 予期しないエラー用に`error.tsx`を作る。

構成は次のようにします。

src/
├── app/
│   ├── blog/
│   │   ├── [id]/
│   │   │   └── page.tsx
│   │   ├── error.tsx
│   │   ├── not-found.tsx
│   │   └── page.tsx
│   ├── globals.css
│   ├── layout.tsx
│   └── page.tsx
└── data/
    └── posts.ts

この構成にすると、/blog配下で起きる404やエラーを、ブログ機能に合った見た目で処理しやすくなります。エラーは最も近い親のerror.tsxへバブルアップするため、階層ごとに細かくエラー処理を分けられます。 (🔗 nextjs.org)

Step 1:記事データを用意する

まず、存在する記事と存在しない記事を判定するためのデータを用意します。

src/data/posts.ts

// 記事1件分の型です
export type Post = {
  id: string;
  title: string;
  body: string;
};

// 学習用の記事データです
export const posts: Post[] = [
  {
    id: "1",
    title: "Next.jsのError Handling入門",
    body: "エラー処理と404処理を分けて考えることが大切です。",
  },
  {
    id: "2",
    title: "notFoundの使い方",
    body: "存在しないデータはnotFound()で扱います。",
  },
  {
    id: "3",
    title: "error.tsxの役割",
    body: "予期しないエラーはerror.tsxで受け止めます。",
  },
];
TypeScript

Step 2:ブログ一覧ページを作る

次に、詳細ページへ進むための一覧ページを作ります。

src/app/blog/page.tsx

// Next.jsのリンク機能を読み込みます
import Link from "next/link";

// 記事データを読み込みます
import { posts } from "../../data/posts";

// ブログ一覧ページです
export default function BlogPage() {
  return (
    <main>
      <h1>ブログ一覧</h1>
      <p>記事を選ぶと詳細ページへ移動します。</p>

      <ul>
        {posts.map((post) => (
          // 各記事のidをURLに使います
          <li key={post.id}>
            <Link href={`/blog/${post.id}`}>{post.title}</Link>
          </li>
        ))}
      </ul>

      <p>
        {/* 存在しない記事の確認用リンクです */}
        <Link href="/blog/999">存在しない記事を見る</Link>
      </p>
    </main>
  );
}
TSX

Step 3:詳細ページでnotFound()を使う

ここがDay 44の最重要ポイントです。記事が見つからなかったら、自分で「見つかりません」と文字を返すのではなく、notFound()を呼びます。

src/app/blog/[id]/page.tsx

// notFound関数を読み込みます
import { notFound } from "next/navigation";

// 記事データを読み込みます
import { posts } from "../../../data/posts";

// URLパラメータの型です
type BlogDetailPageProps = {
  params: Promise<{
    id: string;
  }>;
};

// ブログ詳細ページです
export default async function BlogDetailPage({
  params,
}: BlogDetailPageProps) {
  // URLからidを取り出します
  const { id } = await params;

  // idに一致する記事を探します
  const post = posts.find((item) => item.id === id);

  // 記事が見つからない場合は404扱いにします
  if (!post) {
    notFound();
  }

  return (
    <article>
      <h1>{post.title}</h1>
      <p>記事ID:{post.id}</p>
      <p>{post.body}</p>
    </article>
  );
}
TSX

notFound()を使うことで、「存在しない記事」という状態をNext.jsに正しく伝えられます。単に文章を返すより、404としての意味を持つUIにしやすく、検索エンジンにも不要なページをインデックスさせにくくできます。 (🔗 nextjs.org)

Step 4:not-found.tsxを作る

次に、404時に表示する画面を作ります。

src/app/blog/not-found.tsx

// ブログ配下の404画面です
export default function NotFound() {
  return (
    <main>
      <h1>記事が見つかりません</h1>
      <p>
        指定された記事は存在しないか、削除された可能性があります。
      </p>
      <p>/blog に戻って別の記事を確認してください。</p>
    </main>
  );
}
TSX

これで、/blog/999のように存在しない記事へアクセスしたとき、この404画面が表示されます。

Step 5:error.tsxを作る

次は、予期しないエラーを受け止めるためのerror.tsxです。これは必ずClient Componentにします。 (🔗 nextjs.org)

src/app/blog/error.tsx

// error.tsxはClient Componentである必要があります
"use client";

// エラー表示後の副作用に使います
import { useEffect } from "react";

// ブログ配下のエラー画面です
export default function Error({
  error,
  reset,
}: {
  // 発生したエラー情報です
  error: Error & { digest?: string };
  // 再試行するための関数です
  reset: () => void;
}) {
  // エラー内容を開発中に確認できるようにします
  useEffect(() => {
    console.error(error);
  }, [error]);

  return (
    <main>
      <h1>問題が発生しました</h1>
      <p>
        ページの表示中に予期しないエラーが発生しました。
      </p>

      <button
        type="button"
        // 同じセグメントの再描画を試みます
        onClick={() => reset()}
      >
        もう一度試す
      </button>
    </main>
  );
}
TSX

公式ドキュメントでは、error.tsxはエラーバウンダリーとして動作し、errorと再試行用の関数を受け取れると説明されています。掲載例ではunstable_retryという名前が使われていますが、実務や教材ではresetとして紹介されることもあります。ここでは一般的な理解しやすさを優先してresetとして説明しています。エラー時には、同じセグメントを再描画させる再試行ボタンを置くのが分かりやすいです。 (🔗 nextjs.org)

Step 6:意図的にエラーを起こして確認する

404ではなく、error.tsxが動くかも確認したい場合があります。学習用として、一時的に次のようなコードを入れると確認しやすいです。

src/app/blog/[id]/page.tsx の確認用例

// notFound関数を読み込みます
import { notFound } from "next/navigation";

// 記事データを読み込みます
import { posts } from "../../../data/posts";

type BlogDetailPageProps = {
  params: Promise<{
    id: string;
  }>;
};

export default async function BlogDetailPage({
  params,
}: BlogDetailPageProps) {
  const { id } = await params;

  // 学習用に、特定のIDで強制エラーを発生させます
  if (id === "500") {
    throw new Error("学習用の強制エラーです。");
  }

  const post = posts.find((item) => item.id === id);

  if (!post) {
    notFound();
  }

  return (
    <article>
      <h1>{post.title}</h1>
      <p>{post.body}</p>
    </article>
  );
}
TSX

この状態で/blog/500へアクセスすると、今度は404ではなくerror.tsxの画面が表示されます。こうして、404とエラーの違いを自分の目で確認できます。

Step 7:notFound()とerror.tsxの違いを深く理解する

ここは特に大事です。

  • `notFound()`:存在しないデータや存在しないページを表します。これは想定内の分岐です。
  • `error.tsx`:予期しない失敗、例外、バグを表します。これは想定外の異常です。

たとえば、次のように考えます。

  • IDは正しい形式だが、その記事がない → `notFound()`です。
  • APIが落ちた、JSONが壊れた、コードが例外を投げた → `error.tsx`です。

この区別ができるようになると、画面設計も説明文も非常に自然になります。

Step 8:存在しないURLそのものも処理する考え方

Day 44の実践テーマは「存在しないページを処理する」です。その中には、動的ページで存在しないデータを処理する場合だけでなく、URL自体が存在しない場合も含まれます。

Next.jsではnot-found.tsxを使って404 UIを整えられます。さらに、より広い404処理の仕組みもあります。公式ドキュメントでは、通常のnot-foundに加えて、アプリ全体を通常レンダリングの外で404処理できるglobal-not-foundの仕組みも案内されています。これは通常のレイアウトを通らない特別な404画面です。 (🔗 nextjs.org)

ただし、Day 44ではまず動的ページでnotFound()を使って404を出せることを確実に理解すれば十分です。

Step 9:セキュリティと情報漏えいの注意

エラー画面は便利ですが、見せ方を間違えると危険です。特に本番環境では、エラー内容をそのまま利用者へ見せないように注意します。

  • データベース名、SQL文、APIキー、内部パスなどを画面に直接表示しないでください。
  • 利用者向け画面には「問題が発生しました」程度の説明にとどめます。
  • 詳細なエラー情報は、開発用のコンソールや監視サービスへ送る設計が基本です。

error.tsx内でconsole.error(error)しているのは、開発中に確認しやすくするためです。本番では監視サービスへ送る設計が一般的です。公式でも、エラー報告サービスへのログ送信例が示されています。 (🔗 nextjs.org)

Step 10:イベントハンドラのエラーは別扱い

これも初心者が混乱しやすい点です。エラーバウンダリーは、イベントハンドラの中の例外を自動で捕まえるためのものではありません。公式ドキュメントでも、イベントハンドラやレンダー後の非同期コードのエラーは、通常のエラーバウンダリーでは処理されないと説明されています。 (🔗 nextjs.org)

つまり、ボタンのonClick内で起きたエラーは、必要に応じてtry...catchし、Stateで表示を切り替えるなどの別対応が必要です。Day 44ではまず、ルートセグメントの描画中に起きる例外をerror.tsxで処理するところを押さえてください。 (🔗 nextjs.org)

Step 11:初心者向けテンプレート

最小テンプレートも載せておきます。

notFound() の最小テンプレート

// notFound関数を読み込みます
import { notFound } from "next/navigation";

// 動的ページです
export default async function Page({
  params,
}: {
  params: Promise<{ id: string }>;
}) {
  // URLからidを取得します
  const { id } = await params;

  // 学習用に、存在しない場合を仮定します
  const item = null;

  // 見つからなければ404扱いにします
  if (!item) {
    notFound();
  }

  return <div>{id}</div>;
}
TSX

not-found.tsx の最小テンプレート

// 404用画面です
export default function NotFound() {
  return <h1>ページが見つかりません</h1>;
}
TSX

error.tsx の最小テンプレート

// error.tsxはClient Componentです
"use client";

// エラー発生時の画面です
export default function Error({
  error,
  reset,
}: {
  error: Error & { digest?: string };
  reset: () => void;
}) {
  return (
    <div>
      <h1>エラーが発生しました</h1>
      <button type="button" onClick={() => reset()}>
        再試行
      </button>
    </div>
  );
}
TSX

Step 12:Day 44で特に大事な判断基準

最後に、初心者が迷いやすい判断を整理します。

  • 「そのデータは最初から存在しないかもしれない」と分かっているなら、まず`notFound()`を考えます。
  • 「本来起きるべきではない失敗」なら、`error.tsx`を考えます。
  • 404は利用者向けの案内、エラーは障害時の保護と回復、という役割の違いを意識します。

この考え方が身につくと、画面を作るときに「どの失敗をどこで扱うべきか」を整理しやすくなります。

Day 44のチェックリスト

  • `notFound()`が存在しないデータを404扱いにする関数だと説明できます。
  • `not-found.tsx`が404表示用の特別ファイルだと説明できます。
  • `error.tsx`が予期しない例外を表示するための特別ファイルだと説明できます。
  • `error.tsx`はClient Componentである必要があると理解しています。
  • 存在しない記事IDでは`notFound()`を使えるようになっています。
  • 予期しないエラーと404を別物として設計できます。
  • 利用者に内部エラー詳細を見せすぎない注意点を理解しています。

まとめ

Day 44では、Next.js App RouterのError Handlingとして、error.tsx、notFound()、not-found.tsxを学びました。存在しないデータはnotFound()で404として扱い、予期しない例外はerror.tsxで受け止める、という役割分担が最も大切です。 (🔗 nextjs.org)

実践では、ブログ詳細ページで記事が見つからないときにnotFound()を呼び、not-found.tsxで404画面を表示し、さらにerror.tsxで予期しない障害時の画面も用意しました。ここまでできれば、単にページを表示するだけでなく、失敗したときにどう見せるかまで考えられるNext.jsアプリへ一歩進めます。

タイトルとURLをコピーしました