NextJS中文文档 - Error Handling

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

处理预期错误

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

服务器函数

你可以使用 useActionState hook 来处理服务器函数中的预期错误。

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

'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: '创建文章失败' }
  }
}

'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: '创建文章失败' }
  }
}

你可以将你的操作传递给 useActionState hook，并使用返回的 state 来显示错误消息。

'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">标题</label>
      <input type="text" id="title" name="title" required />
      <label htmlFor="content">内容</label>
      <textarea id="content" name="content" required />
      {state?.message && <p aria-live="polite">{state.message}</p>}
      <button disabled={pending}>创建文章</button>
    </form>
  )
}

'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">标题</label>
      <input type="text" id="title" name="title" required />
      <label htmlFor="content">内容</label>
      <textarea id="content" name="content" required />
      {state?.message && <p aria-live="polite">{state.message}</p>}
      <button disabled={pending}>创建文章</button>
    </form>
  )
}

服务器组件

在服务器组件内部获取数据时，你可以使用响应来有条件地渲染错误消息或重定向。

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

  if (!res.ok) {
    return '发生了错误。'
  }

  return '...'
}

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

  if (!res.ok) {
    return '发生了错误。'
  }

  return '...'
}

未找到

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

import { getPostBySlug } from '@/lib/posts'

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

  if (!post) {
    notFound()
  }

  return <div>{post.title}</div>
}

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>
}

export default function NotFound() {
  return <div>404 - 页面未找到</div>
}

export default function NotFound() {
  return <div>404 - 页面未找到</div>
}

处理未捕获的异常

未捕获的异常是那些表明存在 bug 或在应用程序正常流程中不应该发生的问题的意外错误。这些应该通过抛出错误来处理，然后由错误边界捕获。

嵌套错误边界

Next.js 使用错误边界来处理未捕获的异常。错误边界会捕获其子组件中的错误，并显示一个回退 UI，而不是显示崩溃的组件树。

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

'use client' // 错误边界必须是客户端组件

import { useEffect } from 'react'

export default function Error({
  error,
  reset,
}: {
  error: Error & { digest?: string }
  reset: () => void
}) {
  useEffect(() => {
    // 将错误记录到错误报告服务
    console.error(error)
  }, [error])

  return (
    <div>
      <h2>出错了！</h2>
      <button
        onClick={
          // 尝试通过重新渲染段来恢复
          () => reset()
        }
      >
        重试
      </button>
    </div>
  )
}

'use client' // 错误边界必须是客户端组件

import { useEffect } from 'react'

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

  return (
    <div>
      <h2>出错了！</h2>
      <button onClick={() => reset()}>重试</button>
    </div>
  )
}

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

全局错误

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

'use client' // 错误边界必须是客户端组件

export default function GlobalError({
  error,
  reset,
}: {
  error: Error & { digest?: string }
  reset: () => void
}) {
  return (
    // global-error 必须包含 html 和 body 标签
    <html>
      <body>
        <h2>出错了！</h2>
        <button onClick={() => reset()}>重试</button>
      </body>
    </html>
  )
}

'use client' // 错误边界必须是客户端组件

export default function GlobalError({ error, reset }) {
  return (
    // global-error 必须包含 html 和 body 标签
    <html>
      <body>
        <h2>出错了！</h2>
        <button onClick={() => reset()}>重试</button>
      </body>
    </html>
  )
}