如何配置Next.js应用以使用自定义404和500错误页面？

Next.js 默认自带基础的 404（未找到）和 500（内部服务器错误）错误页面，但要自定义成和应用风格一致的页面，得分两种路由模式来配置——Pages Router（旧版）和 App Router（Next.js 13+），具体步骤如下：

Pages Router（Next.js 12 及更早版本） #

自定义 404 页面 #

在项目根目录的 pages 文件夹下创建 404.js（或 .tsx）文件，直接编写 React 组件即可，这个页面会自动被 Next.js 识别为全局 404 页面：

import Layout from '../components/Layout';
import styles from '../styles/ErrorPage.module.css';

export default function Custom404() {
  return (
    <Layout>
      <div className={styles.container}>
        <h1>404 - 页面找不到</h1>
        <p>你访问的页面不存在，试试返回首页？</p>
        <button onClick={() => window.location.href='/'}>回到首页</button>
      </div>
    </Layout>
  );
}

这个页面默认是静态生成的，不需要额外配置 getStaticProps，如果需要动态数据（比如加载站点导航），可以在组件里添加该函数。

自定义 500 页面 #

同样在 pages 文件夹下创建 500.js（或 .tsx）文件，编写对应组件：

import Layout from '../components/Layout';
import styles from '../styles/ErrorPage.module.css';

export default function Custom500() {
  return (
    <Layout>
      <div className={styles.container}>
        <h1>500 - 服务器出错了</h1>
        <p>服务器暂时出现问题，请稍后再试。</p>
      </div>
    </Layout>
  );
}

注意：开发模式下 Next.js 会显示详细的错误栈信息，自定义 500 页面仅在生产环境生效。

App Router（Next.js 13+） #

自定义 404 页面 #

在 app 目录下创建 not-found.js（或 .tsx）文件，编写组件：

import Layout from './Layout';
import styles from './error-page.module.css';

export default function NotFound() {
  return (
    <Layout>
      <div className={styles.container}>
        <h1>404 - 页面走丢了</h1>
        <p>抱歉，你访问的页面不存在。</p>
        <a href="/">返回首页</a>
      </div>
    </Layout>
  );
}

如果需要在某个路由分支里主动触发 404，可以在组件里调用 notFound() 函数（需要从 next/navigation 导入）：

import { notFound } from 'next/navigation';

async function ProductPage({ params }) {
  const product = await fetchProduct(params.id);
  if (!product) {
    notFound();
  }
  // 正常渲染产品页面
}

自定义 500 错误边界 #

在 app 目录下创建 error.js（或 .tsx）文件，这个组件作为错误边界，会捕获当前目录及子目录下的所有错误：

'use client'; // 错误边界组件必须是客户端组件

import { useEffect } from 'react';
import Layout from './Layout';
import styles from './error-page.module.css';

export default function Error({ error, reset }) {
  useEffect(() => {
    // 可以在这里上报错误信息到监控系统
    console.error(error);
  }, [error]);

  return (
    <Layout>
      <div className={styles.container}>
        <h1>500 - 服务器出问题了</h1>
        <p>抱歉，当前页面无法正常加载。</p>
        <button onClick={() => reset()}>尝试重新加载</button>
      </div>
    </Layout>
  );
}

如果需要全局的错误边界，直接在 app 根目录下创建 error.js 即可，它会捕获整个应用的错误。

关键注意事项 #

• 样式统一：在自定义错误页面里导入应用的全局样式、通用布局组件，确保和其他页面的视觉风格一致。
• 开发 vs 生产：开发模式下 Next.js 优先显示错误详情，自定义错误页面仅在生产环境完全生效。
• 动态数据：如果错误页面需要动态内容（比如站点导航、用户信息），Pages Router 可以用 getStaticProps/getServerSideProps，App Router 可以直接在组件里用 async/await 异步获取数据。

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