Skip to main content

error.js

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

¥An error file allows you to handle unexpected runtime errors and display fallback UI.

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

error.js 的工作原理​

¥How error.js Works

error.js 将路由段及其嵌套子项封装在 React 误差边界 中。当边界内出现错误时，error 组件将显示为后备 UI。

¥error.js wraps a route segment and its nested children in a React Error Boundary. When an error throws within the boundary, the error component shows as the fallback UI.

很高兴知道：

¥Good to know:

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

    ¥The React DevTools allow you to toggle error boundaries to test error states.

属性​

¥Props

error​

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

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

很高兴知道：在开发过程中，转发到客户端的 Error 对象将被序列化，并包含原始错误的 message，以便于调试。但是，这种行为在生产中有所不同，以避免将错误中包含的潜在敏感细节泄露给客户端。

¥Good to know: During development, the Error object forwarded to the client will be serialized and include the message of the original error for easier debugging. However, this behavior is different in production to avoid leaking potentially sensitive details included in the error to the client.

error.message​

  • 从客户端组件转发的错误显示原始 Error 消息。

    ¥Errors forwarded from Client Components show the original Error message.

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

    ¥Errors forwarded from Server Components show a generic message with an identifier. This is to prevent leaking sensitive details. You can use the identifier, under errors.digest, to match the corresponding server-side logs.

error.digest​

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

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

reset​

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

¥The cause of an error can sometimes be temporary. In these cases, trying again might resolve the issue.

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

¥An error component can use the reset() function to prompt the user to attempt to recover from the error. 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.

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

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

global-error.js​

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

¥While less common, you can handle errors in the root layout or template using app/global-error.js, located in the root app directory, even when leveraging internationalization. Global error UI must define its own <html> and <body> tags. This file replaces the root layout or template when active.

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

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

很高兴知道：

¥Good to know:

  • global-error.js 仅在生产中启用。在开发过程中，我们的错误叠加将会显示。

    ¥global-error.js is only enabled in production. In development, our error overlay will show instead.

not-found.js​

在路由段内调用 notFound() 函数时，not-found 文件会显示 UI。

¥The not-found file shows UI when calling the notFound() function within a route segment.

版本历史​

¥Version History

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