NNext.js 中文网 GitHub

catchError

catchError 函数的 API 参考。

catchError 函数创建一个组件,将其子组件包裹在错误边界中。它提供了 error.js 文件约定的编程式替代方案,使你能在组件树中的任何位置实现组件级错误恢复。

与自定义的 React 错误边界相比,catchError 旨在与 Next.js 开箱即用地协同工作:

  • 内置错误恢复 —— retry() 会在 Transition 中重新渲染页面,保留错误边界之外的 Client Components 状态。
  • 感知框架的集成 —— redirect() 和 notFound() 等 API 在底层通过抛出特殊错误来工作。catchError 会无缝处理这些错误,因此它们不会被你的错误边界意外捕获。
  • 客户端导航处理 —— 当你客户端导航到其他路由时,错误状态会自动清除。

catchError 可以从 Client Components 中调用。

app/custom-error-boundary.tsx
'use client'

import { catchError, type ErrorInfo } from 'next/error'

function ErrorFallback(props: { title: string }, { error, retry }: ErrorInfo) {
  const message = error instanceof Error ? error.message : String(error)

  return (
    <div>
      <h2>{props.title}</h2>
      <p>{message}</p>
      <button onClick={() => retry()}>Try again</button>
    </div>
  )
}

export default catchError(ErrorFallback)
app/custom-error-boundary.js
'use client'

import { catchError } from 'next/error'

function ErrorFallback(props, { error, retry }) {
  const message = error instanceof Error ? error.message : String(error)

  return (
    <div>
      <h2>{props.title}</h2>
      <p>{message}</p>
      <button onClick={() => retry()}>Try again</button>
    </div>
  )
}

export default catchError(ErrorFallback)

catchError 函数创建一个组件,将其子组件包裹在错误边界中。它提供了编写自定义 React 错误边界类的编程式替代方案,使你能在组件树中的任何位置实现组件级错误恢复。

与自定义的 React 错误边界相比,catchError 旨在与 Next.js 开箱即用地协同工作:

  • 内置错误恢复 —— reset() 会重新渲染错误边界的子组件,让用户无需整页重载即可从错误中恢复。
  • 客户端导航处理 —— 当你客户端导航到其他路由时,错误状态会自动清除。
components/custom-error-boundary.tsx
import { catchError, type ErrorInfo } from 'next/error'

function ErrorFallback(props: { title: string }, { error, reset }: ErrorInfo) {
  const message = error instanceof Error ? error.message : String(error)

  return (
    <div>
      <h2>{props.title}</h2>
      <p>{message}</p>
      <button onClick={() => reset()}>Try again</button>
    </div>
  )
}

export default catchError(ErrorFallback)
components/custom-error-boundary.js
import { catchError } from 'next/error'

function ErrorFallback(props, { error, reset }) {
  const message = error instanceof Error ? error.message : String(error)

  return (
    <div>
      <h2>{props.title}</h2>
      <p>{message}</p>
      <button onClick={() => reset()}>Try again</button>
    </div>
  )
}

export default catchError(ErrorFallback)

参考#

参数#

catchError 接受一个参数:

ts
const ErrorWrapper = catchError(fallback)

fallback#

在捕获错误时渲染错误 UI 的函数。它接收两个参数:

  • props —— 传递给包装组件的 props(不包括 children)。
  • errorInfo —— 包含错误信息的对象:
属性类型描述
errorunknown抛出的值。在读取 message 等属性之前,请先缩小其类型,例如使用 instanceof Error。
retry() => void重新获取并重新渲染错误边界的子组件。如果成功,后备 UI 会被重新渲染的结果替换。
reset() => void重置错误状态并重新渲染,但不重新获取。大多数情况下请使用 retry()。

fallback 函数必须是 Client Component(或在 'use client' 模块中定义)。

属性类型描述
errorunknown抛出的值。在读取 message 等属性之前,请先缩小其类型,例如使用 instanceof Error。
reset() => void重置错误状态并重新渲染错误边界的子组件。

返回值#

catchError 返回一个 React 组件,该组件:

  • 接受与 fallback 第一个参数相同的 props,外加 children。
  • 将 children 包裹在错误边界中。
  • 当 children 中捕获到错误时渲染 fallback。

示例#

基本用法#

定义一个 fallback,并使用返回的组件包裹 UI 的部分内容:

app/some-component.tsx
import ErrorWrapper from '../custom-error-boundary'

export default function Component({ children }: { children: React.ReactNode }) {
  return <ErrorWrapper title="Dashboard Error">{children}</ErrorWrapper>
}
app/some-component.js
import ErrorWrapper from '../custom-error-boundary'

export default function Component({ children }) {
  return <ErrorWrapper title="Dashboard Error">{children}</ErrorWrapper>
}
components/some-component.tsx
import ErrorWrapper from './custom-error-boundary'

export default function Component({ children }: { children: React.ReactNode }) {
  return <ErrorWrapper title="Dashboard Error">{children}</ErrorWrapper>
}
components/some-component.js
import ErrorWrapper from './custom-error-boundary'

export default function Component({ children }) {
  return <ErrorWrapper title="Dashboard Error">{children}</ErrorWrapper>
}

从错误中恢复#

使用 retry() 提示用户从错误中恢复。调用时,该函数会重新获取并重新渲染错误边界的子组件。如果成功,后备 UI 会被重新渲染的结果替换。

大多数情况下,请使用 retry() 而不是 reset()。reset() 函数仅清除错误状态并重新渲染,而不重新获取,这意味着它无法从 Server Component 错误中恢复。

app/custom-error-boundary.tsx
'use client'

import { catchError, type ErrorInfo } from 'next/error'

function ErrorFallback(props: {}, { error, retry, reset }: ErrorInfo) {
  const message = error instanceof Error ? error.message : String(error)

  return (
    <div>
      <p>{message}</p>
      <button onClick={() => retry()}>Try again</button>
      <button onClick={() => reset()}>Reset</button>
    </div>
  )
}

export default catchError(ErrorFallback)
app/custom-error-boundary.js
'use client'

import { catchError } from 'next/error'

function ErrorFallback(props, { error, retry, reset }) {
  const message = error instanceof Error ? error.message : String(error)

  return (
    <div>
      <p>{message}</p>
      <button onClick={() => retry()}>Try again</button>
      <button onClick={() => reset()}>Reset</button>
    </div>
  )
}

export default catchError(ErrorFallback)

使用 reset() 提示用户从错误中恢复。调用时,该函数会清除错误状态并重新渲染错误边界的子组件。

components/custom-error-boundary.tsx
import { catchError, type ErrorInfo } from 'next/error'

function ErrorFallback(props: {}, { error, reset }: ErrorInfo) {
  const message = error instanceof Error ? error.message : String(error)

  return (
    <div>
      <p>{message}</p>
      <button onClick={() => reset()}>Try again</button>
    </div>
  )
}

export default catchError(ErrorFallback)
components/custom-error-boundary.js
import { catchError } from 'next/error'

function ErrorFallback(props, { error, reset }) {
  const message = error instanceof Error ? error.message : String(error)

  return (
    <div>
      <p>{message}</p>
      <button onClick={() => reset()}>Try again</button>
    </div>
  )
}

export default catchError(ErrorFallback)

服务端渲染的错误后备 UI#

你可以将服务端渲染的内容作为 prop 传递,以显示数据驱动的后备 UI。其原理是将 Server Component 作为 React.ReactNode prop 渲染,在捕获错误时由 fallback 显示。

小知识:此模式会在每次页面渲染时急切地渲染后备 UI,即使没有发生错误。对于大多数用例,更简单的客户端后备 UI 就足够了。

app/error-boundary.tsx
'use client'

import { catchError, type ErrorInfo } from 'next/error'

function ErrorFallback(
  props: { fallback: React.ReactNode },
  errorInfo: ErrorInfo
) {
  return props.fallback
}

export default catchError(ErrorFallback)
app/error-boundary.js
'use client'

import { catchError } from 'next/error'

function ErrorFallback(props, errorInfo) {
  return props.fallback
}

export default catchError(ErrorFallback)
app/some-component.tsx
import ErrorBoundary from '../error-boundary'

async function ErrorFallback() {
  const data = await getData()
  return <div>{data.message}</div>
}

export default function Component({ children }: { children: React.ReactNode }) {
  return <ErrorBoundary fallback={<ErrorFallback />}>{children}</ErrorBoundary>
}
app/some-component.js
import ErrorBoundary from '../error-boundary'

async function ErrorFallback() {
  const data = await getData()
  return <div>{data.message}</div>
}

export default function Component({ children }) {
  return <ErrorBoundary fallback={<ErrorFallback />}>{children}</ErrorBoundary>
}

小知识:

  • 与作用于路由段的 error.js 文件约定不同,catchError 可用于包裹组件树的任何部分,实现组件级错误恢复。
  • 传递给包装组件的 props 会转发给 fallback 函数,便于创建具有不同配置的可复用错误 UI。
  • 无需用 catchError 包裹 error.js 的默认导出。error.js 文件约定本身已经在 Next.js 提供的内置错误边界中渲染。

小知识:传递给包装组件的 props 会转发给 fallback 函数,便于创建具有不同配置的可复用错误 UI。

版本历史#

版本变更
v16.3.0catchError 已稳定。
v16.2.0引入 unstable_catchError。
Next.js 中文网