Skip to main content

error.js

错误文件定义路由段的错误 UI 边界。

¥An error file defines an error UI boundary for a route segment.

它对于捕获服务器组件和客户端组件中发生的意外错误并显示后备 UI 非常有用。

¥It is useful for catching unexpected errors that occur in Server Components and Client Components and displaying a fallback UI.

'use client' // Error components 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>
  )
}
'use client' // Error components must be Client Components

import { useEffect } from 'react'

export default function Error({ error, reset }) {
  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>
  )
}

属性​

¥Props

error​

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

¥An instance of an Error object forwarded to the error.js Client Component.

error.message​

错误消息。

¥The error message.

  • 对于从客户端组件转发的错误，这将是原始错误消息。

    ¥For errors forwarded from Client Components, this will be the original Error's message.

  • 对于从服务器组件转发的错误，这将是通用错误消息，以避免泄露敏感详细信息。errors.digest 可用于匹配服务器端日志中相应的错误。

    ¥For errors forwarded from Server Components, this will be a generic error message to avoid leaking sensitive details. errors.digest can be used to match the corresponding error in server-side logs.

error.digest​

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

¥An automatically generated hash of the error thrown in a Server Component. It can be used to match the corresponding error in server-side logs.

reset​

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

¥A function to reset the error boundary. When executed, the function will try to re-render the Error boundary's contents. If successful, the fallback error component is replaced with the result of the re-render.

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

¥Can be used to prompt the user to attempt to recover from the error.

很高兴知道：

¥Good to know:

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

    ¥error.js boundaries must be Client Components.

  • 在生产版本中，从服务器组件转发的错误将被删除特定的错误详细信息，以避免泄露敏感信息。

    ¥In Production builds, errors forwarded from Server Components will be stripped of specific error details to avoid leaking sensitive information.

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

    ¥An error.js boundary will not handle errors thrown in a layout.js component in the same segment because the error boundary is nested inside that layouts component.

    • 要处理特定布局的错误，请将 error.js 文件放置在布局父段中。

      ¥To handle errors for a specific layout, place an error.js file in the layouts parent segment.

    • 要处理根布局或模板中的错误，请使用 error.js 的变体（称为 app/global-error.js）。

      ¥To handle errors within the root layout or template, use a variation of error.js called app/global-error.js.

global-error.js​

要专门处理根 layout.js 中的错误，请使用位于根 app 目录中的 error.js 变体（称为 app/global-error.js）。

¥To specifically handle errors in root layout.js, use a variation of error.js called app/global-error.js located in the root app directory.

'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>
  )
}
'use client'

export default function GlobalError({ error, reset }) {
  return (
    <html>
      <body>
        <h2>Something went wrong!</h2>
        <button onClick={() => reset()}>Try again</button>
      </body>
    </html>
  )
}

很高兴知道：

¥Good to know:

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

    ¥global-error.js replaces the root layout.js when active and so must define its own <html> and <body> tags.

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

    ¥While designing error UI, you may find it helpful to use the React Developer Tools to manually toggle Error boundaries.

not-found.js​

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

¥The not-found file is used to render UI when the notFound() function is thrown within a route segment.

版本历史​

¥Version History

版本变化
v13.1.0global-error 推出。
v13.0.0error 推出。