error.js

error 文件用于定义路由片段的错误边界 UI。

它可用于捕获服务端组件 (Server Components) 和客户端组件 (Client Components) 中发生的意外错误，并显示备用 UI。

'use client' // 错误组件必须是客户端组件

import { useEffect } from 'react'

export default function Error({
  error,
  reset,
}: {
  error: Error & { digest?: string }
  reset: () => void
}) {
  useEffect(() => {
    // 将错误记录到错误报告服务
    console.error(error)
  }, [error])

  return (
    <div>
      <h2>Something went wrong!</h2>
      <button
        onClick={
          // 尝试通过重新渲染该片段来恢复
          () => reset()
        }
      >
        Try again
      </button>
    </div>
  )
}

参数

`error`

传递给 error.js 客户端组件的 Error 对象实例。

`error.message`

错误信息。

对于从客户端组件传递的错误，这将显示原始错误信息
对于从服务端组件传递的错误，这将显示通用错误信息以避免泄露敏感细节。可使用 errors.digest 来匹配服务端日志中的对应错误

`error.digest`

服务端组件抛出错误的自动生成哈希值。可用于匹配服务端日志中的对应错误。

`reset`

用于重置错误边界的函数。执行时，该函数会尝试重新渲染错误边界的内容。如果成功，备用错误组件将被重新渲染的结果替换。

可用于提示用户尝试从错误中恢复。

须知:

error.js 边界必须是**客户端组件**

在生产构建中，从服务端组件传递的错误会被移除具体细节以避免泄露敏感信息

error.js 边界不会处理在同一片段的 layout.js 组件中抛出的错误，因为错误边界嵌套在该布局组件内部

要处理特定布局的错误，请在布局的父级片段放置 error.js 文件

要处理根布局或模板内的错误，请使用 error.js 的变体 app/global-error.js

`global-error.js`

要专门处理根 layout.js 中的错误，请在根 app 目录中使用 error.js 的变体 app/global-error.js。

'use client'

export default function GlobalError({
  error,
  reset,
}: {
  error: Error & { digest?: string }
  reset: () => void
}) {
  return (
    <html>
      <body>
        <h2>Something went wrong!</h2>
        <button onClick={() => reset()}>Try again</button>
      </body>
    </html>
  )
}

须知:

global-error.js 激活时会替换根 layout.js，因此必须定义自己的 <html> 和 <body> 标签

在设计错误 UI 时，使用 React 开发者工具手动切换错误边界可能会有所帮助

not-found.js

not-found 文件用于在路由片段中抛出 notFound() 函数时渲染 UI。

版本历史

版本	变更
`v13.1.0`	引入 `global-error` 功能
`v13.0.0`	引入 `error` 功能

On this page