catchError
catchError 函数的 API 参考。
catchError 函数创建一个组件,将其子组件包裹在错误边界中。它提供了 error.js 文件约定的编程式替代方案,使你能在组件树中的任何位置实现组件级错误恢复。
与自定义的 React 错误边界相比,catchError 旨在与 Next.js 开箱即用地协同工作:
- 内置错误恢复 ——
retry()会在 Transition 中重新渲染页面,保留错误边界之外的 Client Components 状态。 - 感知框架的集成 ——
redirect()和notFound()等 API 在底层通过抛出特殊错误来工作。catchError会无缝处理这些错误,因此它们不会被你的错误边界意外捕获。 - 客户端导航处理 —— 当你客户端导航到其他路由时,错误状态会自动清除。
catchError 可以从 Client Components 中调用。
'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)'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()会重新渲染错误边界的子组件,让用户无需整页重载即可从错误中恢复。 - 客户端导航处理 —— 当你客户端导航到其他路由时,错误状态会自动清除。
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)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 接受一个参数:
const ErrorWrapper = catchError(fallback)fallback#
在捕获错误时渲染错误 UI 的函数。它接收两个参数:
props—— 传递给包装组件的 props(不包括children)。errorInfo—— 包含错误信息的对象:
| 属性 | 类型 | 描述 |
|---|---|---|
error | unknown | 抛出的值。在读取 message 等属性之前,请先缩小其类型,例如使用 instanceof Error。 |
retry | () => void | 重新获取并重新渲染错误边界的子组件。如果成功,后备 UI 会被重新渲染的结果替换。 |
reset | () => void | 重置错误状态并重新渲染,但不重新获取。大多数情况下请使用 retry()。 |
fallback 函数必须是 Client Component(或在 'use client' 模块中定义)。
| 属性 | 类型 | 描述 |
|---|---|---|
error | unknown | 抛出的值。在读取 message 等属性之前,请先缩小其类型,例如使用 instanceof Error。 |
reset | () => void | 重置错误状态并重新渲染错误边界的子组件。 |
返回值#
catchError 返回一个 React 组件,该组件:
- 接受与 fallback 第一个参数相同的 props,外加
children。 - 将
children包裹在错误边界中。 - 当
children中捕获到错误时渲染fallback。
示例#
基本用法#
定义一个 fallback,并使用返回的组件包裹 UI 的部分内容:
import ErrorWrapper from '../custom-error-boundary'
export default function Component({ children }: { children: React.ReactNode }) {
return <ErrorWrapper title="Dashboard Error">{children}</ErrorWrapper>
}import ErrorWrapper from '../custom-error-boundary'
export default function Component({ children }) {
return <ErrorWrapper title="Dashboard Error">{children}</ErrorWrapper>
}import ErrorWrapper from './custom-error-boundary'
export default function Component({ children }: { children: React.ReactNode }) {
return <ErrorWrapper title="Dashboard Error">{children}</ErrorWrapper>
}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 错误中恢复。
'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)'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() 提示用户从错误中恢复。调用时,该函数会清除错误状态并重新渲染错误边界的子组件。
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)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 就足够了。
'use client'
import { catchError, type ErrorInfo } from 'next/error'
function ErrorFallback(
props: { fallback: React.ReactNode },
errorInfo: ErrorInfo
) {
return props.fallback
}
export default catchError(ErrorFallback)'use client'
import { catchError } from 'next/error'
function ErrorFallback(props, errorInfo) {
return props.fallback
}
export default catchError(ErrorFallback)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>
}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.0 | catchError 已稳定。 |
v16.2.0 | 引入 unstable_catchError。 |