NNext.js 中文网 GitHub

错误处理

处理 Next.js 应用中的错误。

本文档介绍如何处理开发、服务端和客户端错误。

处理开发环境中的错误#

当 Next.js 应用程序在开发阶段出现运行时错误时,你会遇到一个遮罩层。它是一个覆盖网页的模态框。它仅在使用 pnpm dev、npm run dev、yarn dev 或 bun dev 通过 next dev 运行开发服务器时可见,不会在生产环境中显示。修复错误后,遮罩层会自动消失。

处理服务端错误#

Next.js 默认提供一个静态的 500 页面来处理应用程序中发生的服务端错误。你也可以通过创建 pages/500.js 文件来自定义此页面。

应用程序中有 500 页面并不会向应用用户显示具体的错误。

你还可以使用 404 页面来处理特定的运行时错误,例如 file not found。

处理客户端错误#

React 错误边界是一种优雅的方式,用于在客户端处理 JavaScript 错误,使应用程序的其他部分继续工作。除了防止页面崩溃之外,它还允许你提供自定义的回退组件,甚至记录错误信息。

要在 Next.js 应用程序中使用错误边界,你必须创建一个类组件 ErrorBoundary,并在 pages/_app.js 文件中包裹 Component prop。该组件将负责:

  • 在抛出错误后渲染回退 UI
  • 提供重置应用程序状态的方法
  • 记录错误信息

你可以通过继承 React.Component 来创建 ErrorBoundary 类组件。例如:

jsx
class ErrorBoundary extends React.Component {
  constructor(props) {
    super(props)

    // 定义一个状态变量,用于跟踪是否发生错误
    this.state = { hasError: false }
  }
  static getDerivedStateFromError(error) {
    // 更新状态,以便下一次渲染显示回退 UI

    return { hasError: true }
  }
  componentDidCatch(error, errorInfo) {
    // 你可以在这里使用自己的错误日志记录服务
    console.log({ error, errorInfo })
  }
  render() {
    // 检查是否抛出了错误
    if (this.state.hasError) {
      // 你可以渲染任何自定义的回退 UI
      return (
        <div>
          <h2>Oops, there is an error!</h2>
          <button
            type="button"
            onClick={() => this.setState({ hasError: false })}
          >
            Try again?
          </button>
        </div>
      )
    }

    // 在没有错误的情况下返回子组件

    return this.props.children
  }
}

export default ErrorBoundary

ErrorBoundary 组件会跟踪 hasError 状态。该状态变量的值是一个布尔值。当 hasError 的值为 true 时,ErrorBoundary 组件将渲染回退 UI;否则,它将渲染子组件。

创建 ErrorBoundary 组件后,在 pages/_app.js 文件中导入它,以包裹 Next.js 应用程序中的 Component prop。

jsx
// 导入 ErrorBoundary 组件
import ErrorBoundary from '../components/ErrorBoundary'

function MyApp({ Component, pageProps }) {
  return (
    // 使用 ErrorBoundary 组件包裹 Component prop
    <ErrorBoundary>
      <Component {...pageProps} />
    </ErrorBoundary>
  )
}

export default MyApp

你可以在 React 文档中了解更多关于错误边界的信息。

报告错误#

要监控客户端错误,可以使用 Sentry、Bugsnag 或 Datadog 等服务。

Next.js 中文网