React / 系统课时

创建错误边界

创建错误边界

页面中的未捕获异常不应让整个应用只剩空白或默认报错页。本节用 App Router 的 error.tsx 把故障限制在一个路由段内,并提供错误提示、日志入口和可重试按钮,让用户有明确的恢复路径。

学习目标

  • 在路由段中创建符合要求的 error.tsx 错误边界
  • 区分可被边界捕获的渲染异常与需要业务代码显式处理的预期错误
  • 使用 error 与 reset 提供诊断信息和重新渲染能力

构造一个可复现的渲染错误

先创建一个客户端组件。按钮本身不直接抛异常,而是修改状态,让下一次渲染抛错;这样异常发生在渲染阶段,可以被最近的错误边界捕获。

app/demo-error/risky-panel.tsx:

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:

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:

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>
  )
}

预期结果

text
打开 /demo-error:看到“报表组件运行正常”
点击“触发渲染错误”:当前路由段切换到错误界面
点击“重试”:错误边界重新渲染内容,正常组件再次出现

开发环境中的控制台还会显示模拟异常;生产环境不应把服务器端敏感错误详情直接展示给用户。

看懂捕获与恢复链路

当路由段中的页面或子组件在渲染阶段出现未捕获异常时,最近的 error.tsx 会作为 React Error Boundary 的回退界面。reset() 只是发起一次重新渲染尝试;如果根因仍然存在,例如请求每次都失败,重试后仍可能再次进入错误边界。:contentReference[oaicite:4]{index=4}

error.tsx 的捕获与恢复流程

这条链路适合处理真正的意外异常。表单校验失败、资源不存在、权限不足等可预期情况应由业务逻辑显式返回状态,或使用对应的 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}

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

创建错误边界

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通