React / 系统课时
创建错误边界
创建错误边界
页面中的未捕获异常不应让整个应用只剩空白或默认报错页。本节用 App Router 的 error.tsx 把故障限制在一个路由段内,并提供错误提示、日志入口和可重试按钮,让用户有明确的恢复路径。
学习目标
- 在路由段中创建符合要求的
error.tsx错误边界 - 区分可被边界捕获的渲染异常与需要业务代码显式处理的预期错误
- 使用
error与reset提供诊断信息和重新渲染能力
构造一个可复现的渲染错误
先创建一个客户端组件。按钮本身不直接抛异常,而是修改状态,让下一次渲染抛错;这样异常发生在渲染阶段,可以被最近的错误边界捕获。
app/demo-error/risky-panel.tsx:
'use client'
import { useState } from 'react'
export default function RiskyPanel() {
const [broken, setBroken] = useState(false)
if (broken) {
throw new Error('模拟报表组件渲染失败')
}
return (
<section>
<h2>报表组件运行正常</h2>
<button onClick={() => setBroken(true)}>触发渲染错误</button>
</section>
)
}页面只负责渲染这个组件。
app/demo-error/page.tsx:
import RiskyPanel from './risky-panel'
export default function DemoErrorPage() {
return (
<main>
<h1>错误边界演示</h1>
<RiskyPanel />
</main>
)
}创建 error.tsx
error.tsx 必须是 Client Component,因为它需要接收错误对象、响应按钮点击并调用恢复函数。当前 Next.js API 文档中,reset() 会尝试重新渲染该错误边界包裹的内容;如果重渲染成功,错误界面就会被正常内容替换。:contentReference[oaicite:3]{index=3}
app/demo-error/error.tsx:
'use client'
import { useEffect } from 'react'
export default function ErrorView({
error,
reset,
}: {
error: Error & { digest?: string }
reset: () => void
}) {
useEffect(() => {
// 真实项目应在这里接入错误监控,而不只依赖浏览器控制台。
console.error(error)
}, [error])
return (
<main>
<h1>这个页面暂时无法显示</h1>
<p>可以重试一次;如果问题持续出现,请稍后再操作。</p>
<button onClick={() => reset()}>重试</button>
</main>
)
}预期结果
打开 /demo-error:看到“报表组件运行正常”
点击“触发渲染错误”:当前路由段切换到错误界面
点击“重试”:错误边界重新渲染内容,正常组件再次出现开发环境中的控制台还会显示模拟异常;生产环境不应把服务器端敏感错误详情直接展示给用户。
看懂捕获与恢复链路
当路由段中的页面或子组件在渲染阶段出现未捕获异常时,最近的 error.tsx 会作为 React Error Boundary 的回退界面。reset() 只是发起一次重新渲染尝试;如果根因仍然存在,例如请求每次都失败,重试后仍可能再次进入错误边界。:contentReference[oaicite:4]{index=4}

这条链路适合处理真正的意外异常。表单校验失败、资源不存在、权限不足等可预期情况应由业务逻辑显式返回状态,或使用对应的 notFound() 等机制,而不是把所有分支都写成 throw new Error()。当前 Next.js 错误处理指南也把预期错误与未捕获异常分开处理。:contentReference[oaicite:5]{index=5}
记住错误边界的边界
同一路由段的 error.tsx 位于该段 layout.tsx 的内部,因此不能捕获这个 layout.tsx 自身抛出的错误;如果需要保护布局,应把错误边界放到父路由段。根布局或根模板的异常则使用 app/global-error.tsx 处理。:contentReference[oaicite:6]{index=6}
服务器组件错误在生产环境会隐藏具体敏感详情,并可通过 digest 与服务端日志对应;因此用户界面应显示稳定、可理解的提示,诊断细节留在日志和监控系统中。这样既保留恢复入口,也不会把内部实现暴露给终端用户。:contentReference[oaicite:7]{index=7}