Next.js中如何从Layout组件触发自定义error.tsx？

问题原因 #

Next.js App Router的error.tsx是目录级错误边界，仅能捕获当前目录及子目录内组件的错误。你的Header组件属于ClientLayout（父布局），不在页面目录的错误边界覆盖范围内，所以出错时会触发全局默认错误模态框，而非自定义error.tsx。同时，若在父布局上层加error.tsx，会替换整个父布局内容，导致Header和Footer丢失。

解决方案 #

方案一：局部错误边界包裹异步组件 #

将Header中的异步逻辑抽离为单独的服务器组件，再用React错误边界包裹，出错时仅替换动态内容，保留Header外壳、Footer及页面主体结构。

1. 抽离异步逻辑到单独组件
   新建app/components/HeaderContent.tsx（服务器组件）：

import styles from '@/app/styles/Header.module.css';
import Link from 'next/link';
import Image from 'next/image';
import logo from '@/public/logo.png';
import Links from './Links';
import { fetchDepartments } from '@/services/api';

export default async function HeaderContent() {
  const departments = await fetchDepartments(); // 可能抛出错误的异步请求
  return (
    <>
      <Link href="/" className={styles.logo}>
        <Image src={logo} priority={true} alt="logo" />
      </Link>
      {/* <DepartmentsSelectContainer /> */}
      <Links />
      <div className={styles.bookingBtn}>
        <Link className={`btn yellow sm`} href="/contacts">
          Запис на прийом
        </Link>
      </div>
    </>
  );
}

2. 改造Header为客户端组件，添加错误边界
   修改原Header.tsx为客户端组件，用useErrorBoundary包裹异步内容：

'use client';

import styles from '@/app/styles/Header.module.css';
import { useErrorBoundary } from 'react';
import HeaderContent from './HeaderContent';

export default function Header() {
  const { ErrorBoundary } = useErrorBoundary();

  return (
    <header className={styles.navbar}>
      <nav className={`${styles.container} container`}>
        <ErrorBoundary 
          fallback={<div className={styles.errorFallback}>加载失败，请稍后重试</div>}
        >
          <HeaderContent />
        </ErrorBoundary>
      </nav>
    </header>
  );
}

此时HeaderContent出错时，会显示自定义的fallback内容，Header外壳、Footer和页面主体不受影响。

方案二：嵌套布局+目录级error.tsx #

调整目录结构，将包含异步逻辑的部分移到子布局中，子布局目录下放置error.tsx，父布局保留静态不变的Header外壳和Footer。

1. 调整目录结构

app/
├── root-layout.tsx       # 全局布局：包含Header外壳、Footer
├── (dynamic)/
│   ├── layout.tsx        # 动态布局：包含Header异步逻辑、页面主体
│   ├── error.tsx         # 捕获动态布局及页面的错误
│   ├── page.tsx
│   └── ...其他页面

2. 编写全局root-layout.tsx
   保留静态的Header外壳和Footer，动态内容由子布局提供：

import styles from '@/app/styles/Layout.module.css';
import Footer from './components/Footer';
import Link from 'next/link';
import Image from 'next/image';
import logo from '@/public/logo.png';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <>
      <header className={styles.navbar}>
        <nav className={`${styles.container} container`}>
          {/* 静态Logo，不会出错 */}
          <Link href="/" className={styles.logo}>
            <Image src={logo} priority={true} alt="logo" />
          </Link>
          {/* 动态内容由子布局渲染 */}
          {children}
        </nav>
      </header>
      <Footer />
    </>
  );
}

3. 编写动态子布局(dynamic)/layout.tsx
   包含原Header的异步逻辑和页面主体：

import styles from '@/app/styles/Header.module.css';
import Link from 'next/link';
import Links from '../components/Links';
import { fetchDepartments } from '@/services/api';

export default async function DynamicLayout({ children }: { children: React.ReactNode }) {
  const departments = await fetchDepartments(); // 可能抛出错误的异步请求
  return (
    <>
      {/* 原Header的动态部分 */}
      <Links />
      <div className={styles.bookingBtn}>
        <Link className={`btn yellow sm`} href="/contacts">
          Запис на прийом
        </Link>
      </div>
      {/* 页面主体内容 */}
      <main className={styles.main}>{children}</main>
    </>
  );
}

4. 编写自定义error.tsx
   在(dynamic)/error.tsx中定义错误页面，此时出错时会保留root-layout的Header外壳和Footer：

'use client';

export default function Error({ error, reset }: { error: Error; reset: () => void }) {
  return (
    <div className="error-container">
      <h2>Ой, сталася помилка!</h2>
      <p>{error.message}</p>
      <button onClick={() => reset()}>Спробувати знову</button>
    </div>
  );
}

关键注意点 #

• 服务器组件无法直接使用React错误边界，必须将异步逻辑抽离为服务器组件，再由客户端组件包裹错误边界。
• 目录级error.tsx仅对当前目录及子目录生效，父布局中的组件错误需通过局部处理或结构调整来覆盖。

内容的提问来源于stack exchange，提问作者Dmytro