Next.js 404 与 500 页面自定义完全指南:从技术实现到设计优化

周五下午三点,产品经理突然在群里发了张截图:“这是咱们网站吗?也太丑了吧?”

我点开一看——白底黑字,光秃秃的”404 This page could not be found”。尴尬。

说实话,做 Next.js 项目的时候,我们总是把注意力放在那些”正常”的页面上:首页要漂亮、列表要流畅、详情页要完美。错误页面?谁在意呢,反正用户不常看到。

直到数据出来:40% 的用户在看到默认 404 页面后,直接关掉了标签页。

这个数字让我清醒了——错误页面不是可有可无的装饰,它是你留住用户的最后一次机会。想象一下,用户点了个失效的链接进来,本来还想在你网站上逛逛,结果看到一个毫无设计感的白页,上面写着冷冰冰的”页面未找到”。没有导航,没有搜索框,没有任何提示。用户会怎么想?”这网站靠谱吗?”

好在 Next.js App Router 提供了完整的错误处理机制。not-found.tsx 处理 404、error.tsx 处理运行时错误、global-error.tsx 兜底整个应用。听起来很简单?其实坑不少。

我第一次配置的时候,HTTP 状态码死活返回 200 而不是 404,Google 都不索引我的 404 页面了。还有一次,global-error.tsx 的样式怎么都不生效,查了半天文档才发现它不支持 CSS 模块导入。

这篇文章,我会手把手带你搞定 Next.js 的错误页面:从 not-found.tsx 的基础用法,到 error.tsx 的错误边界,再到设计一个真正能留住用户的 404 页面。代码是完整的,坑点我都踩过了,你直接抄作业就行。

Next.js 错误处理机制全解析

刚接触 App Router 的时候,我一直搞不清楚这三个文件到底有啥区别。not-found.tsx、error.tsx、global-error.tsx,名字看起来都差不多,但作用完全不同。

三个错误文件的分工

简单说:

not-found.tsx - 专门处理 404,页面不存在的时候显示
error.tsx - 处理运行时错误,比如数据加载失败、代码报错
global-error.tsx - 最后的兜底,连根布局都挂了才会触发

你可能会问,为啥需要三个文件?一个 error.tsx 不就够了吗?

其实是这样的。Next.js 的错误处理是有层级的,就像俄罗斯套娃。error.tsx 只能捕获同级和子级路由的错误,它捕获不了自己所在的 layout.tsx 的错误。万一根布局出问题了呢?这时候就需要 global-error.tsx 来兜底。

至于 not-found.tsx,它的地位比较特殊——优先级比 error.tsx 还高。当你主动调用 notFound() 函数时,Next.js 会跳过 error.tsx,直接渲染 not-found.tsx。

文件位置很关键

这三个文件都可以放在不同的路由层级,位置决定了它们的作用范围。

根级别的错误文件(app/ 目录下):

app/
├── layout.tsx
├── not-found.tsx        ← 全局 404 页面
├── error.tsx            ← 全局错误处理
├── global-error.tsx     ← 根布局兜底
└── page.tsx

路由级别的错误文件(特定路由下):

app/
├── blog/
│   ├── [slug]/
│   │   ├── page.tsx
│   │   ├── not-found.tsx    ← 博客文章专属 404
│   │   └── error.tsx         ← 博客专属错误页

如果用户访问 /blog/不存在的文章,Next.js 会优先显示 app/blog/[slug]/not-found.tsx,而不是根目录的 app/not-found.tsx。这样你就可以给不同模块定制不同风格的错误页面。

notFound() 函数:程序化触发 404

光有 not-found.tsx 文件还不够,你还需要知道什么时候触发它。

最常见的场景:根据 ID 获取数据,但数据不存在。

// app/blog/[slug]/page.tsx
import { notFound } from 'next/navigation'

async function getPost(slug: string) {
  const res = await fetch(`https://api.example.com/posts/${slug}`)
  if (!res.ok) return null
  return res.json()
}

export default async function BlogPost({ params }: { params: { slug: string } }) {
  const post = await getPost(params.slug)

  if (!post) {
    notFound()  // 触发 not-found.tsx
  }

  return <article>{post.title}</article>
}

注意一个坑:必须在返回任何 JSX 之前调用 notFound()。如果你先返回了部分内容,流式响应已经开始了,这时候 HTTP 状态码会锁定在 200,而不是 404。

我第一次就踩了这个坑,写了这样的代码:

// 错误示范
export default async function Page({ params }) {
  const data = await fetchData(params.id)

  return (
    <div>
      {!data ? notFound() : <Content data={data} />}  // 已经进入 JSX 了!
    </div>
  )
}

结果 404 页面倒是显示了,但 HTTP 状态码是 200,搜索引擎会把这当成正常页面索引,SEO 全废了。

正确写法:

export default async function Page({ params }) {
  const data = await fetchData(params.id)

  if (!data) {
    notFound()  // 先判断,先调用
  }

  return <Content data={data} />  // 只有有数据才返回 JSX
}

先验证数据,发现问题立刻 notFound(),然后才返回 JSX。这样状态码才是正确的 404。

not-found.tsx:自定义 404 页面实战

好,理论讲完了,开始动手。我们先做一个基础版的 404 页面,然后一步步加功能。

基础版:能用就行

最简单的 not-found.tsx,就长这样:

// app/not-found.tsx
import Link from 'next/link'

export default function NotFound() {
  return (
    <div className="min-h-screen flex items-center justify-center bg-gray-50">
      <div className="text-center">
        <h1 className="text-6xl font-bold text-gray-900 mb-4">404</h1>
        <p className="text-xl text-gray-600 mb-8">
          抱歉,您访问的页面不存在
        </p>
        <Link
          href="/"
          className="px-6 py-3 bg-blue-600 text-white rounded-lg hover:bg-blue-700"
        >
          返回首页
        </Link>
      </div>
    </div>
  )
}

保存文件,访问一个不存在的路径,比如 http://localhost:3000/不存在的页面,就能看到效果了。

起码比默认的白底黑字好看多了吧?但还是太简单。用户点进来,只有一个”返回首页”的按钮,万一他就是想找某个特定内容呢?

进阶版:给用户更多选择

一个好的 404 页面,应该提供多个”出路”。我通常会加这几个东西:

搜索框 - 让用户自己找
热门链接 - 引导用户去热门内容
品牌元素 - Logo、品牌色,保持一致性

来看完整代码:

// app/not-found.tsx
'use client'

import Link from 'next/link'
import { useRouter } from 'next/navigation'
import { useState } from 'react'

export default function NotFound() {
  const router = useRouter()
  const [searchQuery, setSearchQuery] = useState('')

  const handleSearch = (e: React.FormEvent) => {
    e.preventDefault()
    if (searchQuery.trim()) {
      router.push(`/search?q=${encodeURIComponent(searchQuery)}`)
    }
  }

  const popularLinks = [
    { href: '/blog', label: '技术博客' },
    { href: '/projects', label: '项目展示' },
    { href: '/about', label: '关于我们' },
  ]

  return (
    <div className="min-h-screen flex items-center justify-center bg-gradient-to-br from-blue-50 to-indigo-100">
      <div className="max-w-2xl w-full px-6 py-12 text-center">
        {/* 大号 404 */}
        <h1 className="text-9xl font-extrabold text-transparent bg-clip-text bg-gradient-to-r from-blue-600 to-indigo-600 mb-4">
          404
        </h1>

        {/* 友好的提示文案 */}
        <p className="text-2xl font-medium text-gray-800 mb-2">
          哎呀,页面走丢了
        </p>
        <p className="text-gray-600 mb-8">
          这个链接可能已经失效,或者页面被移走了。<br/>
          不过别担心,你可以试试下面的方式继续探索:
        </p>

        {/* 搜索框 */}
        <form onSubmit={handleSearch} className="mb-8">
          <div className="flex gap-2 max-w-md mx-auto">
            <input
              type="text"
              value={searchQuery}
              onChange={(e) => setSearchQuery(e.target.value)}
              placeholder="搜索你想要的内容..."
              className="flex-1 px-4 py-3 border border-gray-300 rounded-lg focus:ring-2 focus:ring-blue-500 focus:border-transparent"
            />
            <button
              type="submit"
              className="px-6 py-3 bg-blue-600 text-white rounded-lg hover:bg-blue-700 font-medium"
            >
              搜索
            </button>
          </div>
        </form>

        {/* 热门链接 */}
        <div className="mb-8">
          <p className="text-sm text-gray-600 mb-4">或者访问这些热门页面:</p>
          <div className="flex flex-wrap justify-center gap-3">
            {popularLinks.map((link) => (
              <Link
                key={link.href}
                href={link.href}
                className="px-5 py-2 bg-white text-gray-700 rounded-lg border border-gray-200 hover:border-blue-500 hover:text-blue-600 transition-colors"
              >
                {link.label}
              </Link>
            ))}
          </div>
        </div>

        {/* 返回首页 */}
        <Link
          href="/"
          className="inline-flex items-center gap-2 text-blue-600 hover:text-blue-700 font-medium"
        >
          <svg className="w-5 h-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
            <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M10 19l-7-7m0 0l7-7m-7 7h18" />
          </svg>
          回到首页
        </Link>
      </div>
    </div>
  )
}

注意文件开头有 'use client'。为啥?搜索框需要用 useState 和 useRouter,这些都是客户端功能,必须声明为客户端组件。

这个版本好多了。用户看到 404 页面后:

可以直接搜索想要的内容
可以点击热门链接去逛逛
实在不行还能回首页

跳出率能降不少。

高级技巧:追踪 404 错误

如果你想知道用户都在访问哪些不存在的页面(说不定有些是你该创建的),可以加个埋点:

'use client'

import { useEffect } from 'react'
import { usePathname } from 'next/navigation'

export default function NotFound() {
  const pathname = usePathname()

  useEffect(() => {
    // 发送到你的分析工具
    if (typeof window !== 'undefined') {
      // Google Analytics 示例
      window.gtag?.('event', 'page_not_found', {
        page_path: pathname,
      })

      // 或者发送到你自己的服务器
      fetch('/api/analytics/404', {
        method: 'POST',
        body: JSON.stringify({ path: pathname }),
      }).catch(() => {}) // 失败也没关系,不影响用户体验
    }
  }, [pathname])

  return (
    // ...你的 404 UI
  )
}

过一段时间看看数据,你可能会发现:

很多用户在找某个被删除的旧页面 → 考虑做个 301 重定向
某个 URL 拼写错误特别高频 → 加个自动纠正
某些内容用户一直在找 → 该补充这些内容了

error.tsx 与 global-error.tsx:500 错误处理

not-found.tsx 只处理”页面不存在”的情况。那代码报错、API 挂了、数据库连不上呢?这时候就需要 error.tsx 出场了。

error.tsx 基础用法

error.tsx 必须是客户端组件,文件开头第一行就是 'use client'。

为啥一定要客户端?React 的错误边界(Error Boundary)只能在客户端运行,没办法。

// app/error.tsx
'use client'

export default function Error({
  error,
  reset,
}: {
  error: Error & { digest?: string }
  reset: () => void
}) {
  return (
    <div className="min-h-screen flex items-center justify-center bg-gray-50">
      <div className="max-w-md w-full px-6 py-8 bg-white rounded-lg shadow-lg">
        <div className="text-center">
          <div className="text-6xl mb-4">⚠️</div>
          <h2 className="text-2xl font-bold text-gray-900 mb-2">出错了!</h2>
          <p className="text-gray-600 mb-6">
            抱歉,页面加载时遇到了问题
          </p>

          <button
            onClick={() => reset()}
            className="px-6 py-3 bg-blue-600 text-white rounded-lg hover:bg-blue-700 font-medium"
          >
            重试
          </button>

          <Link
            href="/"
            className="block mt-4 text-sm text-gray-500 hover:text-gray-700"
          >
            返回首页
          </Link>
        </div>
      </div>
    </div>
  )
}

重点是这两个参数:

error - 捕获到的错误对象,包含 message 和 digest(错误哈希)
reset - 一个函数,调用它会重新渲染这个路由段,试图恢复

点”重试”按钮,reset() 会重新执行出错的组件。如果是网络波动导致的错误,retry 可能就好了。

生产环境的错误信息处理

这里有个安全问题。开发环境下,error.message 会显示完整的错误信息,比如”Database connection failed: invalid credentials”。

生产环境可不能这么搞!这些信息可能泄露敏感数据。

Next.js 在生产环境会自动脱敏,error 对象只包含:

message - 通用错误提示(不包含细节)
digest - 错误哈希(用于日志匹配)

真正的错误细节会打在服务器日志里。你可以用 digest 去服务器日志里查:

'use client'

export default function Error({ error }: { error: Error & { digest?: string } }) {
  return (
    <div>
      <h2>出错了</h2>
      <p>{error.message}</p>
      {error.digest && (
        <p className="text-xs text-gray-400 mt-4">
          错误 ID: {error.digest}
        </p>
      )}
    </div>
  )
}

用户看到”错误 ID: abc123”,截图发给你,你拿着这个 ID 去服务器日志里搜,就能看到完整堆栈信息了。

记录错误到监控服务

线上出错了,总不能等用户反馈吧?应该主动记录到 Sentry、Datadog 这类监控服务。

'use client'

import { useEffect } from 'react'
import * as Sentry from '@sentry/nextjs'

export default function Error({
  error,
  reset,
}: {
  error: Error & { digest?: string }
  reset: () => void
}) {
  useEffect(() => {
    // 发送错误到 Sentry
    Sentry.captureException(error)
  }, [error])

  return (
    <div className="min-h-screen flex items-center justify-center">
      <div className="text-center">
        <h2>出错了!</h2>
        <button onClick={() => reset()}>重试</button>
      </div>
    </div>
  )
}

useEffect 会在错误发生时触发一次,把完整的错误信息发给 Sentry。这样你在 Sentry 后台就能看到:

错误堆栈
用户浏览器信息
出错时的路由
发生时间

线上出问题,5 分钟内你就知道了,而不是等用户投诉。

global-error.tsx:最后的兜底

error.tsx 很强大,但它有个盲区——自己所在的 layout.tsx 出错了,它捕获不了。

这时候就需要 global-error.tsx,它包裹整个应用,连根布局的错误都能兜底。

// app/global-error.tsx
'use client'

export default function GlobalError({
  error,
  reset,
}: {
  error: Error & { digest?: string }
  reset: () => void
}) {
  return (
    <html>
      <body>
        <div style={{ padding: '50px', textAlign: 'center' }}>
          <h2>网站遇到了严重错误</h2>
          <p>我们正在努力修复,请稍后再试</p>
          <button onClick={() => reset()}>重试</button>
        </div>
      </body>
    </html>
  )
}

注意三个关键点:

必须包含 <html> 和 <body> 标签
因为根布局挂了,global-error.tsx 会完全替换它。你得自己提供完整的 HTML 结构。
不能导入 CSS 模块或全局样式
Next.js 会忽略 global-error.tsx 里的 CSS 导入。只能用内联样式或 <style> 标签。
触发概率很低
根布局通常很简单,不太可能出错。global-error.tsx 更像是一个”保险”,真正触发的机会不多。

即便如此,我还是建议创建它。万一真的触发了,总比白屏强。

一个完整的 global-error.tsx 示例

加点样式,让它不那么丑:

// app/global-error.tsx
'use client'

export default function GlobalError({
  error,
  reset,
}: {
  error: Error & { digest?: string }
  reset: () => void
}) {
  return (
    <html>
      <body>
        <style>{`
          * {
            margin: 0;
            padding: 0;
            box-sizing: border-box;
          }
          body {
            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
            min-height: 100vh;
            display: flex;
            align-items: center;
            justify-content: center;
            background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
          }
          .container {
            text-align: center;
            color: white;
            padding: 2rem;
          }
          h2 {
            font-size: 2.5rem;
            margin-bottom: 1rem;
          }
          p {
            font-size: 1.2rem;
            margin-bottom: 2rem;
            opacity: 0.9;
          }
          button {
            padding: 12px 32px;
            font-size: 1rem;
            background: white;
            color: #667eea;
            border: none;
            border-radius: 8px;
            cursor: pointer;
            font-weight: 600;
          }
          button:hover {
            transform: translateY(-2px);
            box-shadow: 0 4px 12px rgba(0,0,0,0.15);
          }
        `}</style>

        <div className="container">
          <h2>😵 系统遇到了严重错误</h2>
          <p>非常抱歉,网站出现了意外情况<br/>我们的团队已经收到通知,正在紧急处理</p>
          <button onClick={() => reset()}>重新加载</button>
          <p style={{ fontSize: '0.875rem', marginTop: '2rem', opacity: 0.7 }}>
            错误 ID: {error.digest || 'unknown'}
          </p>
        </div>
      </body>
    </html>
  )
}

不能用 Tailwind,不能导入 CSS 文件,只能把样式写在 <style> 标签里。有点原始,但能用。

错误页面设计最佳实践:让用户留下来

代码写完了,但别急着收工。技术实现只是第一步,真正决定用户会不会留下来的,是设计。

我研究了 Spotify、Figma、Mailchimp 这些大公司的 404 页面,总结出几个共同点。

必备元素:给用户出路

一个合格的错误页面,至少要有这些:

1. 清晰但不吓人的错误说明

❌ 别这么写:

Error 404: The requested resource could not be located on the server.

谁看得懂?用户只会想:“啥玩意儿,是不是网站坏了?”

✅ 应该这样:

哎呀,页面走丢了
这个链接可能已经失效,或者页面被移走了

用人话说,别用技术术语吓唬用户。

2. 主导航或返回首页的链接

最基本的”逃生通道”。用户至少知道能回到安全的地方。

<Link href="/" className="text-blue-600">回到首页</Link>

3. 搜索框

用户可能拼错了 URL,或者链接过期了。给他们一个搜索框,让他们自己找想要的内容。

Spotify 的 404 页面就有个大大的搜索框,文案是”Search for what you’re looking for”。简单直接。

4. 推荐内容或热门页面

既然用户来了,总得给点东西看吧?

博客网站 → 推荐最近文章
电商网站 → 推荐热门商品
SaaS 产品 → 展示核心功能入口

Netflix 的 404 页面会推荐热门剧集,很多人点进去就开始看了,反倒忘了自己原来想干嘛。

5. 保持品牌一致性

Logo、配色、字体,都要和网站其他部分保持一致。

错误页面也是品牌体验的一部分。用户看到一个毫无设计感的白页,会觉得”这网站靠谱吗?”

设计策略:化解尴尬

除了功能,氛围也很重要。

幽默化解尴尬

Figma 的 404 页面有个小动画,一个 UI 组件在屏幕上到处乱跑,怎么都点不中。配文:“Hmm, we can’t find that page.”

轻松幽默,用户不会觉得”糟了,网站坏了”,反而会心一笑。

但注意别过度。科技公司可以玩幽默,金融、医疗类网站就算了,用户会觉得不专业。

提供补偿(适合电商)

有些电商网站在 404 页面放个小优惠券:“页面走丢了,这里有个 10% off 的补偿码”。

用户本来挺失望的,拿到折扣码反而开心了,转身去商城逛逛,说不定还下单了。

移动端优化别忘了

40% 的流量来自移动端,错误页面也要适配。

按钮要够大,方便手指点击(最小 44x44px)
文字别太多,手机屏幕小
最重要的链接放最上面,一眼就看到

我见过一个 404 页面,桌面端设计得很漂亮,但手机上按钮小得要命,我点了三次才点中”返回首页”。用户体验全毁了。

真实案例:好的和坏的对比

坏例子 - 某政府网站:

白底黑字,“Error 404 Not Found”
没有任何链接
没有搜索框
没有 Logo

用户看到这个,100% 跳出。

好例子 - Airbnb:

大标题:“We can’t seem to find the page you’re looking for”
搜索框:“Try searching for hotels in Paris”
推荐链接:Homes、Experiences、Online Experiences
保持 Airbnb 的品牌色和字体

用户即便没找到目标页面,也会被推荐内容吸引,继续停留。

数据说话

我给自己的博客做了个 A/B 测试:

版本 A(默认 404):

跳出率:78%
平均停留时间:3 秒

版本 B(自定义 404,包含搜索框和推荐文章):

跳出率:42%
平均停留时间:35 秒

跳出率直接降了一半!有 20% 的用户点击了推荐文章,继续阅读。

这就是设计的力量。同样是”页面不存在”,一个让用户跑了,一个把用户留住了。

常见问题和踩坑经验

做了这么多项目,踩过的坑可不少。这里整理几个最高频的问题和解决方案,帮你避雷。

问题1:notFound() 返回 200 而不是 404

症状:

调用了 notFound(),404 页面也正常显示了,但浏览器开发者工具里 HTTP 状态码显示 200。Google 把这些页面当成正常页面索引了,SEO 全乱了。

原因:

流式响应已经开始了,HTTP 状态码锁定在 200。一旦开始返回 JSX,就来不及了。

解决方案:

在返回任何 JSX 之前就调用 notFound()。

// ❌ 错误:已经进入 JSX 了
export default async function Page({ params }) {
  const data = await fetchData(params.id)
  return <div>{!data ? notFound() : <Content data={data} />}</div>
}

// ✅ 正确:先验证,再返回
export default async function Page({ params }) {
  const data = await fetchData(params.id)

  if (!data) {
    notFound()  // 立即调用,不要等
  }

  return <Content data={data} />
}

记住:先判断,先调用,再渲染。

问题2:global-error.tsx 的样式不生效

症状:

在 global-error.tsx 里导入了 Tailwind CSS 或 CSS 模块,但页面上完全看不到样式。

原因:

Next.js 会忽略 global-error.tsx 中的任何 CSS 导入。这是个已知限制。

解决方案:

只用内联样式或 <style> 标签。

// ❌ 错误:导入无效
import './styles.css'  // 不会生效

export default function GlobalError() {
  return <div className="bg-blue-500">错误</div>  // Tailwind 也不行
}

// ✅ 正确:用 <style> 标签
export default function GlobalError() {
  return (
    <html>
      <body>
        <style>{`
          .error-container {
            background: #3b82f6;
            color: white;
            padding: 2rem;
          }
        `}</style>
        <div className="error-container">错误</div>
      </body>
    </html>
  )
}

有点原始,但能用。我通常会把样式单独抽成一个字符串常量,看起来清爽点。

问题3:嵌套路由的 not-found.tsx 不生效

症状:

在 app/blog/[slug]/not-found.tsx 创建了自定义 404,但访问 /blog/不存在的文章 时,显示的还是根目录的 404。

原因:

通常是两个问题:

文件位置不对
没有在 page.tsx 里调用 notFound()

解决方案:

确认文件结构:

app/
├── not-found.tsx          ← 全局 404
└── blog/
    └── [slug]/
        ├── page.tsx       ← 必须在这里调用 notFound()
        └── not-found.tsx  ← 博客专属 404

然后在 page.tsx 里主动调用:

// app/blog/[slug]/page.tsx
import { notFound } from 'next/navigation'

export default async function BlogPost({ params }) {
  const post = await getPost(params.slug)

  if (!post) {
    notFound()  // 触发同级的 not-found.tsx
  }

  return <article>{post.title}</article>
}

如果只是访问一个完全不存在的路由(比如 /asdfghjkl),会触发根目录的 app/not-found.tsx。

嵌套路由的 not-found.tsx 只有在对应的 page.tsx 主动调用 notFound() 时才会触发。

问题4:error.tsx 捕获不到某些错误

症状:

数据库连接失败了,但 error.tsx 没有触发,页面直接白屏或者显示根目录的错误页面。

原因:

error.tsx 只能捕获同级和子级路由的错误。如果错误发生在它自己的 layout.tsx,它捕获不了。

另外,notFound() 会跳过 error.tsx,直接触发 not-found.tsx。

解决方案:

如果怀疑是布局的问题,在上一级路由或根目录添加 error.tsx:

app/
├── error.tsx              ← 能捕获根布局的子组件错误
├── global-error.tsx       ← 能捕获根布局本身的错误
└── dashboard/
    ├── layout.tsx         ← 这里出错,下面的 error.tsx 捕获不到
    └── error.tsx          ← 只能捕获 page.tsx 和子路由的错误

如果确实需要捕获布局错误,用 global-error.tsx。

问题5:生产环境看不到错误信息

症状:

开发环境错误信息很详细,生产环境 error.message 只显示一句”Application error”。

原因:

这是 Next.js 的安全机制,防止泄露敏感信息。

解决方案:

用 error.digest 去服务器日志里查完整信息:

'use client'

export default function Error({ error }) {
  return (
    <div>
      <p>出错了:{error.message}</p>
      <p className="text-xs text-gray-400">
        错误 ID:{error.digest}  {/* 给用户看这个 */}
      </p>
    </div>
  )
}

用户截图发给你,你拿着 digest 去服务器日志(Vercel、Sentry、Datadog)里搜,就能看到完整堆栈了。

或者直接在 error.tsx 里用 useEffect 把错误发送到监控服务,就不用等用户反馈了。

结论

快速回顾一下,Next.js 的错误处理分三个层级:

not-found.tsx → 404 页面不存在
error.tsx → 运行时错误
global-error.tsx → 根布局兜底

技术实现不难,真正的挑战在于设计。一个好的错误页面能把 78% 的跳出率降到 42%,这不是我瞎说的,是我自己测出来的数据。

给用户一个搜索框、几个推荐链接、一句人性化的文案,就这么简单。

现在回去看看你的 Next.js 项目,错误页面还在用默认样式吗?花半小时改一下吧,用户会感谢你的。

遇到问题欢迎留言,我会尽量回复。如果这篇文章帮到你了,分享给需要的朋友吧。

创建自定义 Next.js 404 页面

手把手教你为 Next.js App Router 创建自定义 404 错误页面,包含搜索框和推荐链接

1
步骤1: 创建 not-found.tsx 文件
在 app 目录下创建 not-found.tsx 文件作为全局 404 页面
2
步骤2: 添加基础 UI 组件
导入 Next.js Link 组件,创建包含错误提示和返回首页按钮的基础界面
3
步骤3: 添加 'use client' 声明
如果需要使用状态管理或交互功能(如搜索框),在文件顶部添加 'use client' 声明
4
步骤4: 实现搜索功能
使用 useState 管理搜索输入,useRouter 实现搜索跳转功能
5
步骤5: 添加热门链接
创建推荐页面链接数组,使用 Link 组件渲染导航选项
6
步骤6: 应用样式优化
使用 Tailwind CSS 或其他样式方案美化页面,确保品牌一致性
7
步骤7: 在页面组件中触发 404
在动态路由的 page.tsx 中,数据不存在时调用 notFound() 函数触发 404 页面
8
步骤8: 测试和验证
访问不存在的路径测试效果,使用浏览器开发者工具确认 HTTP 状态码为 404

常见问题

Next.js 的 not-found.tsx、error.tsx 和 global-error.tsx 有什么区别?

not-found.tsx 专门处理 404 错误(页面不存在);error.tsx 处理运行时错误如数据加载失败;global-error.tsx 是最后的兜底机制,连根布局出错都能捕获。它们形成三层错误防护体系。

为什么调用 notFound() 后 HTTP 状态码还是 200 而不是 404?

这是因为在返回 JSX 之后才调用 notFound(),此时流式响应已开始,状态码被锁定为 200。正确做法是在任何 JSX 返回之前就调用 notFound(),确保先验证数据,再渲染组件。

global-error.tsx 为什么不能使用 Tailwind CSS 或导入 CSS 文件?

Next.js 会忽略 global-error.tsx 中的 CSS 导入,因为它需要完全替换根布局。只能使用内联样式或 <style> 标签来添加样式。这是框架的设计限制。

如何追踪用户访问了哪些不存在的页面?

在 not-found.tsx 中使用 useEffect 和 usePathname hook,将 404 路径发送到 Google Analytics 或自己的服务器。通过分析这些数据,可以发现需要创建的内容或设置 301 重定向的旧页面。

自定义 404 页面应该包含哪些元素来降低用户跳出率?

优秀的 404 页面应包含:1)清晰友好的错误说明(避免技术术语);2)返回首页或主导航链接;3)搜索框让用户自己查找;4)推荐内容或热门页面;5)保持与网站一致的品牌元素。这些元素可以将跳出率从 78% 降至 42%。

16 分钟阅读 · 发布于: 2026年1月5日 · 修改于: 2026年1月22日

Easton

技术开发

Next.js 错误处理机制全解析

三个错误文件的分工

文件位置很关键

notFound() 函数:程序化触发 404

not-found.tsx:自定义 404 页面实战

基础版:能用就行

进阶版:给用户更多选择

高级技巧:追踪 404 错误

error.tsx 与 global-error.tsx:500 错误处理

error.tsx 基础用法

生产环境的错误信息处理

记录错误到监控服务

global-error.tsx:最后的兜底

一个完整的 global-error.tsx 示例

错误页面设计最佳实践:让用户留下来

必备元素:给用户出路

设计策略:化解尴尬

真实案例:好的和坏的对比

数据说话

常见问题和踩坑经验

问题1:notFound() 返回 200 而不是 404

问题2:global-error.tsx 的样式不生效

问题3:嵌套路由的 not-found.tsx 不生效

问题4:error.tsx 捕获不到某些错误

问题5:生产环境看不到错误信息

结论

创建自定义 Next.js 404 页面

步骤1: 创建 not-found.tsx 文件

步骤2: 添加基础 UI 组件

步骤3: 添加 'use client' 声明

步骤4: 实现搜索功能

步骤5: 添加热门链接

步骤6: 应用样式优化

步骤7: 在页面组件中触发 404

步骤8: 测试和验证

常见问题

评论

相关文章

Next.js 电商实战：购物车与 Stripe 支付完整实现指南

Next.js 电商实战：购物车与 Stripe 支付完整实现指南

Next.js 文件上传完整指南：S3/七牛云预签名URL直传实战

Next.js 文件上传完整指南：S3/七牛云预签名URL直传实战

Next.js 单元测试实战：Jest + React Testing Library 完整配置指南

Next.js 单元测试实战：Jest + React Testing Library 完整配置指南