Next.js 中文文档

外观

错误处理

耶和博

1336字约4分钟

2024-08-10

错误处理

错误可以分为两类:预期错误和未捕获异常:

  • 将预期错误建模为返回值:在服务器操作(Server Actions)中避免使用try/catch处理预期错误。使用useActionState来管理这些错误并将它们返回给客户端。
  • 使用错误边界处理意外错误:使用error.tsx和global-error.tsx文件实现错误边界，以处理意外错误并提供备用UI。

提示

这些示例使用了React的useActionState钩子，该钩子在React 19 RC版本中可用。如果你使用的是早期版本的React，请使用useFormState代替。更多信息请参阅React文档。

处理预期错误

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

处理来自服务器操作的预期错误

使用useActionState钩子来管理服务器操作的状态，包括处理错误。这种方法避免了对预期错误使用try/catch块，这些错误应该被建模为返回值而不是抛出的异常。

app/actions.ts
'use server'
 
import { redirect } from 'next/navigation'
 
export async function createUser(prevState: any， formData: FormData) {
  const res = await fetch('https://...')
  const json = await res.json()
 
  if (!res.ok) {
    return { message: 'Please enter a valid email' }
  }
 
  redirect('/dashboard')
}

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

app/ui/signup.tsx
'use client'
 
import { useActionState } from 'react'
import { createUser } from '@/app/actions'
 
const initialState = {
  message: '',
}
 
export function Signup() {
  const [state, formAction] = useActionState(createUser, initialState)
 
  return (
    <form action={formAction}>
      <label htmlFor="email">Email</label>
      <input type="text" id="email" name="email" required />
      {/* ... */}
      <p aria-live="polite">{state?.message}</p>
      <button>Sign up</button>
    </form>
  )
}

你也可以使用返回的状态在客户端组件中显示一个提示消息。

处理来自服务器组件的预期错误

当在服务器组件内部获取数据时，你可以使用响应来有条件地渲染错误消息或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 '...'
}

未捕获异常

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

  • 常见: 使用error.js处理根布局下的未捕获错误。
  • 可选: 使用嵌套的error.js文件处理粒度更细的未捕获错误(例如 app/dashboard/error.js)
  • 不常见: 使用global-error.js处理根布局中的未捕获错误。

使用错误边界

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

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

app/dashboard/error.tsx
'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>
  )
}

如果你希望错误冒泡到父级错误边界，你可以在渲染error组件时throw。

处理嵌套路由中的错误

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

嵌套错误组件层次结构

处理全局错误

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

app/global-error.tsx
'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>
  )
}