在现代 Web 应用开发中，优雅地处理运行时错误是提升用户体验和系统健壮性的关键。Next.js 在 App Router 架构下引入了基于 React Error Boundary 的错误处理机制，通过特殊的 error.tsx 文件，开发者可以轻松为路由段及其子组件定义降级 UI（fallback UI），并在必要时实现错误恢复。
本文将深入介绍 Next.js App Router 中的错误处理方式，包括局部错误边界、全局错误处理、错误信息传递机制以及错误恢复策略。
1. 局部错误处理：error.tsx
在 App Router 中，你可以在任意路由段（route segment）目录下创建一个 error.tsx（或 error.js）文件。该文件会自动将当前路由及其所有嵌套子路由包裹在一个 React Error Boundary 中。
示例：app/dashboard/error.tsx
tsx
'use client'; // 必须标记为 Client Component
import { useEffect } from 'react';
export default function Error({
error,
reset,
}: {
error: Error & { digest?: string };
reset: () => void;
}) {
useEffect(() => {
// 可选：将错误上报到错误监控服务
console.error(error);
}, [error]);
return (
<div>
<h2>出错了！</h2>
<p>{error.message}</p>
<button onClick={() => reset()}>重试</button>
</div>
);
}⚠️ 注意：
error.tsx必须是 Client Component ，因此需要加上'use client'指令。
当 dashboard 路由或其任何子组件（如 page.tsx、嵌套 layout 等）抛出未捕获的错误时，Next.js 会自动渲染上述 Error 组件，而不是让整个应用崩溃。
2. 错误对象结构
传递给 Error 组件的 error 对象具有以下结构：
message：错误信息。digest（仅限 Server Component 错误）：一个自动生成的错误哈希值，可用于匹配服务端日志。- 在 开发环境 中，
error对象会被序列化并包含原始错误堆栈（stack），便于调试。 - 在 生产环境 中：
- 来自 Client Component 的错误会保留原始
message。 - 来自 Server Component 的错误会被替换为通用消息（如
"An error occurred"），并附带digest，防止敏感信息泄露。
- 来自 Client Component 的错误会保留原始
3. 错误恢复：reset() 函数
Error 组件接收一个 reset: () => void 函数。调用它会尝试重新渲染被错误边界包裹的内容。如果错误是临时性的（如网络波动），重试可能成功恢复页面。
tsx
<button onClick={reset}>点击重试</button>这为用户提供了一种主动恢复的交互方式，极大提升了容错体验。
4. 全局错误处理：global-error.tsx
如果你希望捕获整个应用范围内的错误（包括根布局），可以在 app/ 根目录下创建 global-error.tsx。
示例：app/global-error.tsx
tsx
'use client';
export default function GlobalError({ error, reset }: {
error: Error & { digest?: string };
reset: () => void;
}) {
return (
<html>
<body>
<h1>应用崩溃了！</h1>
<button onClick={reset}>重试</button>
</body>
</html>
);
}⚠️ 全局错误组件 必须自行定义
<html>和<body>标签，因为它会完全替换根布局。
global-error.tsx 是兜底的最后防线，适用于处理根布局或未被局部 error.tsx 捕获的严重错误。
5. 错误边界嵌套与冒泡
Next.js 的错误边界遵循 React 的冒泡机制：
- 如果某个路由没有自己的
error.tsx，错误会向上冒泡到父级路由的错误边界。 - 如果所有层级都没有处理，最终由
global-error.tsx捕获。 - 你也可以在局部
Error组件中不渲染 UI，而是手动抛出错误，让其继续向上冒泡（较少使用）。
6. 最佳实践建议
- 局部化错误处理 ：为关键业务模块（如用户仪表盘、支付页面）单独配置
error.tsx，提供针对性的错误提示。 - 上报错误日志 ：在
useEffect中将错误信息发送到 Sentry、LogRocket 等监控平台。 - 友好提示 + 恢复按钮：不要只显示"出错了"，应说明可能原因并提供"重试"操作。
- 避免敏感信息泄露：生产环境中 Server Component 的错误信息已被脱敏，切勿手动将服务端错误详情传给客户端。
结语
Next.js 的错误处理机制结合了 React Error Boundary 的强大能力与约定优于配置的设计哲学，使得开发者可以轻松构建高可用、用户友好的 Web 应用。合理使用 error.tsx 和 global-error.tsx，不仅能防止页面白屏，还能提供优雅的降级体验和恢复路径。