NNext.js 中文网 GitHub

错误处理

了解如何显示预期错误并处理未捕获的异常。

错误可分为两类:预期错误和未捕获的异常。本页将引导你了解如何在 Next.js 应用程序中处理这些错误。

处理预期错误#

预期错误是指在应用程序正常运行期间可能发生的错误,例如来自服务端表单验证的错误或请求失败。这些错误应被显式处理并返回给客户端。

Server Functions#

你可以使用 useActionState hook 来处理 Server Functions 中的预期错误。

对于这些错误,避免使用 try/catch 块并抛出错误。相反,应将预期错误建模为返回值。

app/actions.ts
'use server'

export async function createPost(prevState: any, formData: FormData) {
  const title = formData.get('title')
  const content = formData.get('content')

  const res = await fetch('https://api.vercel.app/posts', {
    method: 'POST',
    body: { title, content },
  })
  const json = await res.json()

  if (!res.ok) {
    return { message: 'Failed to create post' }
  }
}
app/actions.js
'use server'

export async function createPost(prevState, formData) {
  const title = formData.get('title')
  const content = formData.get('content')

  const res = await fetch('https://api.vercel.app/posts', {
    method: 'POST',
    body: { title, content },
  })
  const json = await res.json()

  if (!res.ok) {
    return { message: 'Failed to create post' }
  }
}

你可以将你的 action 传给 useActionState hook,并使用返回的 state 来显示错误消息。

app/ui/form.tsx
'use client'

import { useActionState } from 'react'
import { createPost } from '@/app/actions'

const initialState = {
  message: '',
}

export function Form() {
  const [state, formAction, pending] = useActionState(createPost, initialState)

  return (
    <form action={formAction}>
      <label htmlFor="title">Title</label>
      <input type="text" id="title" name="title" required />
      <label htmlFor="content">Content</label>
      <textarea id="content" name="content" required />
      {state?.message && <p aria-live="polite">{state.message}</p>}
      <button disabled={pending}>Create Post</button>
    </form>
  )
}
app/ui/form.js
'use client'

import { useActionState } from 'react'
import { createPost } from '@/app/actions'

const initialState = {
  message: '',
}

export function Form() {
  const [state, formAction, pending] = useActionState(createPost, initialState)

  return (
    <form action={formAction}>
      <label htmlFor="title">Title</label>
      <input type="text" id="title" name="title" required />
      <label htmlFor="content">Content</label>
      <textarea id="content" name="content" required />
      {state?.message && <p aria-live="polite">{state.message}</p>}
      <button disabled={pending}>Create Post</button>
    </form>
  )
}

Server Components#

在 Server Component 中获取数据时,你可以根据响应有条件地渲染错误消息或 redirect。

app/page.tsx
export default async function Page() {
  const res = await fetch(`https://...`)
  const data = await res.json()

  if (!res.ok) {
    return 'There was an error.'
  }

  return '...'
}
app/page.js
export default async function Page() {
  const res = await fetch(`https://...`)
  const data = await res.json()

  if (!res.ok) {
    return 'There was an error.'
  }

  return '...'
}

未找到#

你可以在路由段中调用 notFound 函数,并使用 not-found.js 文件来显示 404 UI。

app/blog/[slug]/page.tsx
import { notFound } from 'next/navigation'
import { getPostBySlug } from '@/lib/posts'

export default async function Page({
  params,
}: {
  params: Promise<{ slug: string }>
}) {
  const { slug } = await params
  const post = getPostBySlug(slug)

  if (!post) {
    notFound()
  }

  return <div>{post.title}</div>
}
app/blog/[slug]/page.js
import { notFound } from 'next/navigation'
import { getPostBySlug } from '@/lib/posts'

export default async function Page({ params }) {
  const { slug } = await params
  const post = getPostBySlug(slug)

  if (!post) {
    notFound()
  }

  return <div>{post.title}</div>
}
app/blog/[slug]/not-found.tsx
export default function NotFound() {
  return <div>404 - Page Not Found</div>
}
app/blog/[slug]/not-found.js
export default function NotFound() {
  return <div>404 - Page Not Found</div>
}

处理未捕获的异常#

未捕获的异常是指意外错误,表示应用程序正常流程中不应出现的 bug 或问题。这些错误应通过抛出错误来处理,随后由错误边界捕获。

嵌套错误边界#

Next.js 使用错误边界来处理未捕获的异常。错误边界会捕获其子组件中的错误,并显示后备 UI(fallback UI),而不是渲染崩溃的组件树。

通过在路由段内添加 error.js 文件并导出一个 React 组件来创建错误边界:

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

import { useEffect } from 'react'

export default function ErrorPage({
  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 Components

import { useEffect } from 'react'

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

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

错误会冒泡到最近的父级错误边界。这允许你通过在路由层级的不同层级放置 error.tsx 文件来进行细粒度的错误处理。

对于组件级别的错误恢复,catchError 函数让你可以创建能够包裹组件树任意部分的错误边界:

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)

然后将返回的组件用作任意布局或页面中的包裹组件:

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

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

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

错误边界不会捕获事件处理程序内部的错误。它们旨在捕获渲染期间的错误,以显示后备 UI,而不是让整个应用崩溃。

通常,事件处理程序或异步代码中的错误不会由错误边界处理,因为它们在渲染之后运行。

要处理这些情况,请手动捕获错误并使用 useState 或 useReducer 存储它,然后更新 UI 以告知用户。

tsx
'use client'

import { useState } from 'react'

export function Button() {
  const [error, setError] = useState(null)

  const handleClick = () => {
    try {
      // 执行一些可能失败的工作
      throw new Error('Exception')
    } catch (reason) {
      setError(reason)
    }
  }

  if (error) {
    /* 渲染后备 UI */
  }

  return (
    <button type="button" onClick={handleClick}>
      Click me
    </button>
  )
}

请注意,useTransition 中 startTransition 内部未处理的错误会冒泡到最近的错误边界。

tsx
'use client'

import { useTransition } from 'react'

export function Button() {
  const [pending, startTransition] = useTransition()

  const handleClick = () =>
    startTransition(() => {
      throw new Error('Exception')
    })

  return (
    <button type="button" onClick={handleClick}>
      Click me
    </button>
  )
}

全局错误#

虽然不太常见,但你可以在根布局中使用 global-error.js 文件来处理错误,该文件位于根 app 目录中,即使使用国际化也是如此。全局错误 UI 必须定义自己的 <html> 和 <body> 标签,因为它在生效时会替换根布局或模板。

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

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 Components

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>
  )
}
Next.js 中文网