error.js
error 文件允许你处理意外的运行时错误并显示后备 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(() => {
// 将错误记录到错误报告服务
console.error(error)
}, [error])
return (
<div>
<h2>Something went wrong!</h2>
<button
onClick={
// 尝试通过重新渲染段来恢复
() => reset()
}
>
Try again
</button>
</div>
)
}error.js 将路由段及其嵌套子级包装在 React Error Boundary 中。当边界内抛出错误时，error 组件会作为后备 UI 显示。
值得注意的是：
- React DevTools 允许你切换错误边界以测试错误状态。
- 如果你希望错误冒泡到父级错误边界，可以在渲染
error组件时throw。
Reference
Props
error
一个转发到 error.js Client Component 的 Error 对象实例。
值得注意的是：在开发环境中，转发到客户端的
Error对象将被序列化，并包含原始错误的message，以便更容易调试。但是，此行为在生产环境中有所不同，以避免将错误中包含的潜在敏感详细信息泄露给客户端。
error.message
- 从 Client Components 转发的错误显示原始的
Error消息。 - 从 Server Components 转发的错误显示带有标识符的通用消息。这是为了防止泄露敏感详细信息。你可以使用
errors.digest下的标识符来匹配相应的服务器端日志。
error.digest
抛出的错误的自动生成哈希值。它可用于匹配服务器端日志中的相应错误。
reset
错误的原因有时可能是暂时的。在这些情况下，再次尝试可能会解决问题。
error 组件可以使用 reset() 函数提示用户尝试从错误中恢复。当执行时，该函数将尝试重新渲染错误边界的内容。如果成功，后备错误组件将被重新渲染的结果替换。
'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>
)
}Examples
Global Error
虽然不太常见，但你可以使用位于根 app 目录中的 global-error.jsx 来处理根布局或模板中的错误，即使在利用国际化时也是如此。Global error UI 必须定义自己的 <html> 和 <body> 标签、全局样式、字体或错误页面所需的其他依赖项。此文件在激活时会替换根布局或模板。
值得注意的是：Error boundaries 必须是 Client Components，这意味着
global-error.jsx不支持metadata和generateMetadata导出。作为替代方案，你可以使用 React<title>组件。
'use client' // Error boundaries must be Client Components
export default function GlobalError({
error,
reset,
}: {
error: Error & { digest?: string }
reset: () => void
}) {
return (
// global-error 必须包含 html 和 body 标签
<html>
<body>
<h2>Something went wrong!</h2>
<button onClick={() => reset()}>Try again</button>
</body>
</html>
)
}Graceful error recovery with a custom error boundary
当在客户端渲染失败时，显示最后已知的服务器渲染 UI 可以提供更好的用户体验。
GracefullyDegradingErrorBoundary 是一个自定义错误边界的示例，它在错误发生之前捕获并保留当前的 HTML。如果发生渲染错误，它会重新渲染捕获的 HTML 并显示一个持久的通知栏来通知用户。
'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 GracefullyDegradingErrorBoundaryVersion History
| Version | Changes |
|---|---|
v15.2.0 | 在开发环境中也显示 global-error。 |
v13.1.0 | 引入 global-error。 |
v13.0.0 | 引入 error。 |