跳到主要内容

如何处理错误

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

¥Errors can be divided into two categories: expected errors and uncaught exceptions. This page will walk you through how you can handle these errors in your Next.js application.

处理预期错误​

¥Handling expected errors

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

¥Expected errors are those that can occur during the normal operation of the application, such as those from server-side form validation or failed requests. These errors should be handled explicitly and returned to the client.

服务器操作​

¥Server Actions

你可以使用 useActionState 钩子来管理 服务器函数 的状态并处理预期的错误。避免使用 try/catch 块来处理预期错误。相反，你可以将预期错误建模为返回值，而不是抛出的异常。

¥You can use the useActionState hook to manage the state of Server Functions and handle expected errors. Avoid using try/catch blocks for expected errors. Instead, you can model expected errors as return values, not as thrown exceptions.

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

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

¥Then, you can pass your action to the useActionState hook and use the returned state to display an error message.

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

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

¥When fetching data inside of a Server Component, you can use the response to conditionally render an error message or redirect.

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

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

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

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

  return '...'
}

未找到​

¥Not found

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

¥You can call the notFound function within a route segment and use the not-found.js file to show a 404 UI.

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

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

  if (!post) {
    notFound()
  }

  return <div>{post.title}</div>
}
import { getPostBySlug } from '@/lib/posts'

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

  if (!post) {
    notFound()
  }

  return <div>{post.title}</div>
}
export default function NotFound() {
  return <div>404 - Page Not Found</div>
}
export default function NotFound() {
  return <div>404 - Page Not Found</div>
}

处理未捕获的异常​

¥Handling uncaught exceptions

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

¥Uncaught exceptions are unexpected errors that indicate bugs or issues that should not occur during the normal flow of your application. These should be handled by throwing errors, which will then be caught by error boundaries.

嵌套错误边界​

¥Nested error boundaries

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

¥Next.js uses error boundaries to handle uncaught exceptions. Error boundaries catch errors in their child components and display a fallback UI instead of the component tree that crashed.

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

¥Create an error boundary by adding an error.js file inside a route segment and exporting a React component:

'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(() => {
    // Log the error to an error reporting service
    console.error(error)
  }, [error])

  return (
    <div>
      <h2>Something went wrong!</h2>
      <button
        onClick={
          // Attempt to recover by trying to re-render the segment
          () => reset()
        }
      >
        Try again
      </button>
    </div>
  )
}
'use client' // Error boundaries must be Client Components

import { useEffect } from 'react'

export default function Error({ error, reset }) {
  useEffect(() => {
    // Log the error to an error reporting service
    console.error(error)
  }, [error])

  return (
    <div>
      <h2>Something went wrong!</h2>
      <button
        onClick={
          // Attempt to recover by trying to re-render the segment
          () => reset()
        }
      >
        Try again
      </button>
    </div>
  )
}

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

¥Errors will bubble up to the nearest parent error boundary. This allows for granular error handling by placing error.tsx files at different levels in the route hierarchy.

全局错误​

¥Global errors

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

¥While less common, you can handle errors in the root layout using the global-error.js file, located in the root app directory, even when leveraging internationalization. Global error UI must define its own <html> and <body> tags, since it is replacing the root layout or template when active.

'use client' // Error boundaries must be Client Components

export default function GlobalError({
  error,
  reset,
}: {
  error: Error & { digest?: string }
  reset: () => void
}) {
  return (
    // global-error must include html and body tags
    <html>
      <body>
        <h2>Something went wrong!</h2>
        <button onClick={() => reset()}>Try again</button>
      </body>
    </html>
  )
}
'use client' // Error boundaries must be Client Components

export default function GlobalError({ error, reset }) {
  return (
    // global-error must include html and body tags
    <html>
      <body>
        <h2>Something went wrong!</h2>
        <button onClick={() => reset()}>Try again</button>
      </body>
    </html>
  )
}