error.js

error 文件允许你处理意外的运行时错误并显示回退 UI。

app/dashboard/error.tsx

'use client' // Error boundaries must be Client Components
 
import { useEffect } from 'react'
 
export default function Error({
  error,
  reset,
}: {
  error: Error & { digest?: string }
  reset: () => void
}) {
  useEffect(() => {
    // Log the error to an error reporting service
    console.error(error)
  }, [error])
 
  return (
    <div>
      <h2>Something went wrong!</h2>
      <button
        onClick={
          // Attempt to recover by trying to re-render the segment
          () => reset()
        }
      >
        Try again
      </button>
    </div>
  )
}

error.js 将路由段及其嵌套的子项包裹在 React 错误边界中。当边界内抛出错误时，error 组件将显示为回退 UI。

须知:

React DevTools 允许你切换错误边界以测试错误状态。

如果你希望错误冒泡到父级错误边界，可以在渲染 error 组件时 throw。

参考

属性

`error`

一个 Error 对象的实例，被转发到 error.js 客户端组件。

须知： 在开发过程中，转发到客户端的 Error 对象将被序列化，并包含原始错误的 message，以便于调试。然而，这种行为在生产环境中是不同的，以避免向客户端泄露错误中可能包含的敏感细节。

`error.message`

从客户端组件转发的错误显示原始的 Error 消息。
从服务器组件转发的错误显示一个带有标识符的通用消息。这是为了防止泄露敏感细节。你可以使用标识符（在 errors.digest 下）来匹配相应的服务器端日志。

`error.digest`

错误抛出的自动生成的哈希值。它可以用于匹配服务器端日志中相应的错误。

`reset`

错误的原因有时可能是暂时的。在这种情况下，再次尝试可能会解决问题。

错误组件可以使用 reset() 函数来提示用户尝试从错误中恢复。当执行时，该函数将尝试重新渲染错误边界的内容。如果成功，回退错误组件将被重新渲染的结果替换。

app/dashboard/error.tsx

'use client' // Error boundaries must be Client Components
 
export default function Error({
  error,
  reset,
}: {
  error: Error & { digest?: string }
  reset: () => void
}) {
  return (
    <div>
      <h2>Something went wrong!</h2>
      <button onClick={() => reset()}>Try again</button>
    </div>
  )
}

示例

全局错误

虽然不太常见，但即使在使用国际化时，你也可以使用位于根 app 目录中的 global-error.js 来处理根布局或模板中的错误。全局错误 UI 必须定义自己的 <html> 和 <body> 标签。此文件在激活时会替换根布局或模板。

app/global-error.tsx

'use client' // Error boundaries must be Client Components
 
export default function GlobalError({
  error,
  reset,
}: {
  error: Error & { digest?: string }
  reset: () => void
}) {
  return (
    // global-error must include html and body tags
    <html>
      <body>
        <h2>Something went wrong!</h2>
        <button onClick={() => reset()}>Try again</button>
      </body>
    </html>
  )
}

须知: global-error.js 始终显示。在开发环境中，将显示错误覆盖层。

版本历史

版本	变更
`v15.2.0`	在开发环境中也显示 `global-error`。
`v13.1.0`	引入 `global-error`。
`v13.0.0`	引入 `error`。