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