Next.js 13 的 error.tsx 和 not-found.tsx 并非全局拦截器，而是基于 React 错误边界和路由机制的局部组件；它们无法捕获事件处理器中的同步错误（如按钮点击抛出的异常），需通过状态驱动重渲染或服务端逻辑触发才能生效。
next.js 13 的 `error.tsx` 和 `not-found.tsx` 并非全局拦截器，而是基于 react 错误边界和路由机制的局部组件；它们无法捕获事件处理器中的同步错误（如按钮点击抛出的异常），需通过状态驱动重渲染或服务端逻辑触发才能生效。
在 Next.js 13 的 App Router 中，error.tsx 和 not-found.tsx 是边界敏感（boundary-aware）的特殊页面组件，其行为严格遵循 React 错误边界与 Next.js 路由生命周期规则，而非传统“全局错误处理器”。这意味着：
- ✅ error.tsx 仅在组件树中发生渲染阶段错误时生效（如 useEffect、fetch、SSR 渲染失败），且必须位于错误源的父级布局中（即同级或更高层级的 layout.tsx 或 page.tsx 所属的边界内）；
- ❌ 它不会捕获事件处理器（如 onClick）中抛出的同步错误——这类错误发生在用户交互的微任务中，绕过了 React 渲染流程，因此错误边界无法捕获，Next.js 会降级为开发模式下的右下角错误提示（Overlay）；
- ✅ not-found.tsx 则仅在 notFound() 函数被显式调用（服务端）或 路由匹配完全失败（如访问 /sample/invalid 且无对应动态段或通配符）时触发，不会因客户端 JS 抛错而显示。
正确触发 error.tsx 的两种方式
方式一：服务端错误（推荐，语义清晰）
在 page.tsx 或 layout.tsx 中执行可能失败的服务端逻辑，并主动抛出错误：
// app/sample/page.tsx
export default async function SamplePage() {
// 模拟服务端数据获取失败
const res = await fetch('https://api.example.com/data', { cache: 'no-store' })
if (!res.ok) {
throw new Error(`Failed to fetch: ${res.status}`)
}
const data = await res.json()
return <div>Data: {data?.id}</div>
}此时若请求失败，Next.js 将自动渲染 app/sample/error.tsx（前提是该文件存在于同一目录层级）。
方式二：客户端状态驱动错误边界（兼容交互场景）
将错误抛出移至 useEffect 等可被错误边界捕获的生命周期中：
// app/sample/page.tsx
'use client'
import { useState, useEffect } from 'react'
export default function Sample() {
const [shouldThrow, setShouldThrow] = useState(false)
useEffect(() => {
if (shouldThrow) {
throw new Error(`Client-side error at ${new Date().toISOString()}`)
}
}, [shouldThrow])
return (
<main className="flex flex-col items-center justify-between p-24">
<h1>Sample Page</h1>
<button
onClick={() => setShouldThrow(true)}
className="mt-4 px-4 py-2 bg-red-500 text-white rounded"
>
Trigger Render Error
</button>
</main>
)
}✅ 此时点击按钮会触发 useEffect 抛错，错误边界（即 app/sample/error.tsx）即可正常捕获并渲染。
关于 not-found.tsx 的注意事项
它不响应 throw notFound() 以外的客户端错误；
-
若需在客户端逻辑中触发 404，应使用 notFound()（仅限服务端组件或 generateStaticParams 中）：
// app/sample/[id]/page.tsx —— 服务端组件 import { notFound } from 'next/navigation' export default function Detail({ params }: { params: { id: string } }) { if (params.id === 'invalid') notFound() // ✅ 有效 return <div>ID: {params.id}</div> } 客户端无法直接调用 notFound()；试图在 'use client' 组件中调用会报运行时错误。
最佳实践总结
| 场景 | 推荐方案 | 是否触发自定义页面 |
|---|---|---|
| API 请求失败（服务端） | fetch + if (!res.ok) throw | ✅ error.tsx |
| 动态路由参数无效 | 服务端 notFound() | ✅ not-found.tsx |
| 用户点击触发的意外错误 | 改用 useState + useEffect 抛错 | ✅ error.tsx |
| 纯客户端 onClick 中 throw | ❌ 不支持，改用 Toast / 状态提示 | 否 |
⚠️ 注意：确保 error.tsx 和 not-found.tsx 文件严格位于目标路由的同一目录下（如 app/sample/error.tsx 仅对 /sample/* 下的子路由生效），且 error.tsx 必须标记 'use client'（因其依赖 useEffect 和 reset 函数）；not-found.tsx 可为服务端或客户端组件，但通常无需 'use client'。
通过理解 Next.js 13 的错误处理模型本质——它是声明式、边界化、服务端优先的渲染保障机制，而非命令式错误拦截器——你就能精准控制错误体验，避免陷入“页面不显示”的常见误区。
