NNext.js 中文网 GitHub

error.js

error.js 特殊文件的 API 参考。

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

app/dashboard/error.tsx
'use client' // 错误边界必须是 Client Component

import { useEffect } from 'react'

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

  return (
    <div>
      <h2>Something went wrong!</h2>
      <button
        onClick={
          // 通过重新获取和重新渲染该段来尝试恢复
          () => retry()
        }
      >
        Try again
      </button>
    </div>
  )
}
app/dashboard/error.js
'use client' // 错误边界必须是 Client Component

import { useEffect } from 'react'

export default function Error({ error, retry }) {
  useEffect(() => {
    // 将错误记录到错误报告服务
    console.error(error)
  }, [error])

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

error.js 使用 React Error Boundary 包裹路由段及其嵌套子组件。当边界内抛出错误时,error 组件将显示为回退 UI。

小知识:

  • React DevTools 允许你切换错误边界以测试错误状态。
  • 如果你希望错误冒泡到父错误边界,可以在渲染 error 组件时 throw。
  • 对于不与路由段绑定的组件级错误恢复(如 error.js),请使用 catchError 函数。

在组件层次结构中,error.js 使用 React 错误边界包裹 loading.js、not-found.js、page.js 和嵌套的 layout.js 文件。它不会包裹同一段中位于其上方的 layout.js 或 template.js。要处理根布局中的错误,请使用 global-error.js。

参考#

属性#

error#

被抛出的值,会转发给 error.js Client Component。来自 Server Component 的错误以 Error 实例的形式到达,而在 Client Component 中抛出的值会原样传递,可能不是 Error。在读取 message 或 digest 等属性之前,请先缩小其类型,例如使用 instanceof Error。

小知识: 在开发过程中,转发给客户端的 Error 对象会被序列化,并包含原始错误的 message 以便于调试。但是,生产环境中的行为有所不同,以避免将错误中包含的潜在敏感细节泄露给客户端。

error.message#

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

error.digest#

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

retry#

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

错误组件可以使用 retry() 函数提示用户尝试从错误中恢复。执行时,该函数将尝试重新获取并重新渲染错误边界的子组件。如果成功,回退错误组件将被重新渲染的结果替换。

app/dashboard/error.tsx
'use client' // 错误边界必须是 Client Component

export default function Error({
  error,
  retry,
}: {
  error: unknown
  retry: () => void
}) {
  return (
    <div>
      <h2>Something went wrong!</h2>
      <button onClick={() => retry()}>Try again</button>
    </div>
  )
}
app/dashboard/error.js
'use client' // 错误边界必须是 Client Component

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

reset#

在大多数情况下,你应该改用 retry()。但是,如果你有特定理由要清除错误状态并重新渲染错误边界的子组件而不重新获取内容,可以使用 reset() 函数。

示例#

全局错误#

虽然不太常见,但你可以使用位于根 app 目录中的 global-error.jsx 处理根布局或模板中的错误,即使在使用国际化时也是如此。全局错误 UI 必须定义自己的 <html> 和 <body> 标签,以及错误页面所需的全局样式、字体或其他依赖项。此文件在激活时会替换根布局或模板。

小知识:global-error 和内置的 500 页面会渲染自己的文档,不包含你的全局样式,因此应用级主题切换(class 或 data-theme 属性)不会影响它们。默认 UI 遵循操作系统配色方案;要匹配应用的主题,请在自己的 global-error 组件中应用它。

小知识:错误边界必须是 Client Component,这意味着 global-error.jsx 中不支持 metadata 和 generateMetadata 导出。作为替代方案,你可以使用 React <title> 组件。

app/global-error.tsx
'use client' // 错误边界必须是 Client Component

export default function GlobalError({
  error,
  retry,
}: {
  error: unknown
  retry: () => void
}) {
  return (
    // global-error 必须包含 html 和 body 标签
    <html>
      <body>
        <h2>Something went wrong!</h2>
        <button onClick={() => retry()}>Try again</button>
      </body>
    </html>
  )
}
app/global-error.js
'use client' // 错误边界必须是 Client Component

export default function GlobalError({ error, retry }) {
  return (
    // global-error 必须包含 html 和 body 标签
    <html>
      <body>
        <h2>Something went wrong!</h2>
        <button onClick={() => retry()}>Try again</button>
      </body>
    </html>
  )
}

使用自定义错误边界实现优雅的错误恢复#

当客户端渲染失败时,显示最后一次已知的服务器渲染 UI 可能有助于提供更好的用户体验。

GracefullyDegradingErrorBoundary 是一个自定义错误边界的示例,它会在错误发生前捕获并保留当前的 HTML。如果发生渲染错误,它会重新渲染捕获的 HTML,并显示一个持续的通知栏来告知用户。

app/dashboard/error.tsx
'use client'

import React, { Component, ErrorInfo, ReactNode } from 'react'

interface ErrorBoundaryProps {
  children: ReactNode
  onError?: (error: Error, errorInfo: ErrorInfo) => void
}

interface ErrorBoundaryState {
  hasError: boolean
}

export class GracefullyDegradingErrorBoundary extends Component<
  ErrorBoundaryProps,
  ErrorBoundaryState
> {
  private contentRef: React.RefObject<HTMLDivElement | null>

  constructor(props: ErrorBoundaryProps) {
    super(props)
    this.state = { hasError: false }
    this.contentRef = React.createRef()
  }

  static getDerivedStateFromError(_: Error): ErrorBoundaryState {
    return { hasError: true }
  }

  componentDidCatch(error: Error, errorInfo: ErrorInfo) {
    if (this.props.onError) {
      this.props.onError(error, errorInfo)
    }
  }

  render() {
    if (this.state.hasError) {
      // 在不进行 hydration 的情况下渲染当前 HTML 内容
      return (
        <>
          <div
            ref={this.contentRef}
            suppressHydrationWarning
            dangerouslySetInnerHTML={{
              __html: this.contentRef.current?.innerHTML || '',
            }}
          />
          <div className="fixed bottom-0 left-0 right-0 bg-red-600 text-white py-4 px-6 text-center">
            <p className="font-semibold">
              An error occurred during page rendering
            </p>
          </div>
        </>
      )
    }

    return <div ref={this.contentRef}>{this.props.children}</div>
  }
}

export default GracefullyDegradingErrorBoundary
app/dashboard/error.js
'use client'

import React, { Component, createRef } from 'react'

class GracefullyDegradingErrorBoundary extends Component {
  constructor(props) {
    super(props)
    this.state = { hasError: false }
    this.contentRef = createRef()
  }

  static getDerivedStateFromError(_) {
    return { hasError: true }
  }

  componentDidCatch(error, errorInfo) {
    if (this.props.onError) {
      this.props.onError(error, errorInfo)
    }
  }

  render() {
    if (this.state.hasError) {
      // 在不进行 hydration 的情况下渲染当前 HTML 内容
      return (
        <>
          <div
            ref={this.contentRef}
            suppressHydrationWarning
            dangerouslySetInnerHTML={{
              __html: this.contentRef.current?.innerHTML || '',
            }}
          />
          <div className="fixed bottom-0 left-0 right-0 bg-red-600 text-white py-4 px-6 text-center">
            <p className="font-semibold">
              An error occurred during page rendering
            </p>
          </div>
        </>
      )
    }

    return <div ref={this.contentRef}>{this.props.children}</div>
  }
}

export default GracefullyDegradingErrorBoundary

版本历史#

版本变更
v16.3.0retry 属性已稳定。
v16.2.0添加了 unstable_retry 属性。
v15.2.0在开发环境中也显示 global-error。
v13.1.0引入了 global-error。
v13.0.0引入了 error。
Next.js 中文网