本文详解 Next.js 中预期错误与未捕获异常的处理机制。涵盖 Server Actions 中使用 [[wp:a0]] 管理状态、Server Components 的数据获取错误，以及通过 [[wp:a11]] 创建错误边界捕获子组件异常。同时介绍根目录 [[wp:a18]] 处理全局未捕获错误的配置方法，确保应用健壮性。
一、错误的分类
在 Next.js 应用中，错误主要被划分为两类：预期错误（Expected Errors）和未捕获的异常（Uncaught Exceptions）。
- 预期错误：这类错误属于应用正常运行流程中可能出现的部分，例如用户提交了无效数据或网络请求失败。
- 未捕获的异常：这类错误通常代表代码中存在 Bug 或其他非预期的严重问题，不应在正常业务逻辑中发生。
二、处理预期错误
在 Server Component 中获取数据时，开发者可以根据请求的响应结果（如 HTTP 状态码），决定是直接渲染错误消息还是执行页面重定向。
1. 处理来自 Server Actions 的预期错误
当在 Server Actions 中遇到预期错误时，推荐采用 useFormState Hook 来管理这些错误状态并将其返回给客户端，而非使用传统的 try/catch 语句块进行捕获。
示例：创建用户时处理错误
// app/actions.js
'use server'
import { redirect } from 'next/navigation'
export async function createUser(prevState, formData) {
const res = await fetch('https://...')
const json = await res.json()
if (!res.ok) {
return { message: '请输入有效的邮箱' }
}
redirect('/dashboard')
}
在此示例中，如果后端请求失败，createUser 函数将返回包含错误信息的对象，而不是直接抛出异常中断执行。
随后，在客户端组件中，可以通过 useFormState Hook 来接收并处理返回的状态，从而向用户展示具体的错误消息。
// app/ui/signup.js
'use client'
import { useFormState } from 'react'
import { createUser } from '@/app/actions'
const initialState = {
message: '',
}
export function Signup() {
const [state, formAction] = useFormState(createUser, initialState)
return (
<form action={formAction}>
<label htmlFor="email">邮箱</label>
<input type="text" id="email" name="email" required />
<p aria-live="polite">{state?.message}</p>
<button>注册</button>
</form>
)
}
重要提示
- 上述示例中使用的
useFormStateHook 已内置于 Next.js App Router 中。若项目升级至 React 19，请改用useActionState。 useFormStateHook 提供的state状态对象可用于在客户端组件中渲染错误消息，从而提升用户的交互体验。
2. 处理来自 Server Components 的预期错误
在 Server Component 中获取数据时，可根据请求响应结果决定渲染错误消息或执行页面重定向。
// app/page.js
export default async function Page() {
const res = await fetch(`https://...`)
const data = await res.json()
if (!res.ok) {
return '发生了错误。'
}
return '...'
}
三、处理未捕获的异常
未捕获的异常通常指程序中不应发生的错误，往往暗示存在代码 Bug。对于此类异常，最佳实践是使用错误边界（Error Boundaries）进行捕获，并提供备用 UI。
1. 使用错误边界
错误边界允许我们捕获子组件树中抛出的异常，并显示一个备用的降级 UI，从而避免整个组件树崩溃。
在 Next.js 中，可以通过在路由段目录下添加 error.tsx 文件来定义该路由段的错误边界。
// app/dashboard/error.js
'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 组件时主动使用 throw 语句抛出错误。
2. 处理嵌套路由中的错误
错误会向上冒泡至最近的父级错误边界。因此，可以在不同层级的路由段中分别放置 error.tsx 文件，以实现更细粒度的错误处理策略。
// app/dashboard/error.js
// 错误边界组件
四、处理全局错误
虽然这种情况较少见，但我们可以利用位于根 app 目录下的 app/global-error.js 文件来处理根布局中的错误，确保即使在国际化（i18n）场景下也能正确捕获和处理错误。
示例：处理全局错误
// app/global-error.js
'use client'
export default function GlobalError({ error, reset }) {
return (
<html>
<body>
<h2>出现了问题！</h2>
<button onClick={() => reset()}>重试</button>
</body>
</html>
)
}
重要提示
- 全局错误 UI 组件必须包含
<html>和<body>标签，因为该组件在激活时会完全替换根布局或模板。 global-error.js文件提供了全局错误处理的能力，确保在整个应用范围内能够优雅地处理任何未捕获的异常。
到此这篇关于 Next.js 预期错误与未捕获异常的处理方法的文章就介绍到这了，更多相关 Next.js 预期错误与未捕获异常内容请搜索本站以前的文章或继续浏览下面的相关文章希望大家以后多多支持本站！