错误处理
了解如何显示预期错误并处理未捕获的异常。
错误可分为两类:预期错误和未捕获的异常。本页将引导你了解如何在 Next.js 应用程序中处理这些错误。
处理预期错误#
预期错误是指在应用程序正常运行期间可能发生的错误,例如来自服务端表单验证的错误或请求失败。这些错误应被显式处理并返回给客户端。
Server Functions#
你可以使用 useActionState hook 来处理 Server Functions 中的预期错误。
对于这些错误,避免使用 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: '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' }
}
}你可以将你的 action 传给 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">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#
在 Server Component 中获取数据时,你可以根据响应有条件地渲染错误消息或 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 '...'
}未找到#
你可以在路由段中调用 notFound 函数,并使用 not-found.js 文件来显示 404 UI。
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>
}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>
}export default function NotFound() {
return <div>404 - Page Not Found</div>
}export default function NotFound() {
return <div>404 - Page Not Found</div>
}处理未捕获的异常#
未捕获的异常是指意外错误,表示应用程序正常流程中不应出现的 bug 或问题。这些错误应通过抛出错误来处理,随后由错误边界捕获。
嵌套错误边界#
Next.js 使用错误边界来处理未捕获的异常。错误边界会捕获其子组件中的错误,并显示后备 UI(fallback UI),而不是渲染崩溃的组件树。
通过在路由段内添加 error.js 文件并导出一个 React 组件来创建错误边界:
'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>
)
}'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 函数让你可以创建能够包裹组件树任意部分的错误边界:
'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)'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)然后将返回的组件用作任意布局或页面中的包裹组件:
import ErrorBoundary from './custom-error-boundary'
export default function Component({ children }: { children: React.ReactNode }) {
return <ErrorBoundary title="Dashboard Error">{children}</ErrorBoundary>
}import ErrorBoundary from './custom-error-boundary'
export default function Component({ children }) {
return <ErrorBoundary title="Dashboard Error">{children}</ErrorBoundary>
}错误边界不会捕获事件处理程序内部的错误。它们旨在捕获渲染期间的错误,以显示后备 UI,而不是让整个应用崩溃。
通常,事件处理程序或异步代码中的错误不会由错误边界处理,因为它们在渲染之后运行。
要处理这些情况,请手动捕获错误并使用 useState 或 useReducer 存储它,然后更新 UI 以告知用户。
'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 内部未处理的错误会冒泡到最近的错误边界。
'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> 标签,因为它在生效时会替换根布局或模板。
'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>
)
}'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>
)
}