错误处理

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

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

处理预期错误

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

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

使用 useActionState hook (之前称为 useFormState) 来管理服务器操作的状态，包括处理错误。这种方法避免了对预期错误使用 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: "请输入有效的电子邮箱" };
  }
 
  redirect("/dashboard");
}

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");
}

然后，你可以将你的操作传递给 useActionState hook，并使用返回的 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">电子邮箱</label>
      <input type="text" id="email" name="email" required />
      {/* ... */}
      <p aria-live="polite">{state?.message}</p>
      <button>注册</button>
    </form>
  );
}

app/ui/signup.js

"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">电子邮箱</label>
      <input type="text" id="email" name="email" required />
      {/* ... */}
      <p aria-live="polite">{state?.message}</p>
      <button>注册</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 "出现了错误。";
  }
 
  return "...";
}

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.js 处理根布局下的未捕获错误。
可选： 使用嵌套的 error.js 文件处理细粒度的未捕获错误 (例如 app/dashboard/error.js)
不常见： 使用 global-error.js 处理根布局中的未捕获错误。

使用错误边界

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

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

app/dashboard/error.tsx

"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>
  );
}

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.tsx 文件来进行细粒度的错误处理。

处理全局错误

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

app/global-error.tsx

"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>
  );
}

app/global-error.js

"use client"; // 错误边界必须是客户端组件
 
export default function GlobalError({ error, reset }) {
  return (
    // global-error 必须包含 html 和 body 标签
    <html>
      <body>
        <h2>出错了！</h2>
        <button onClick={() => reset()}>重试</button>
      </body>
    </html>
  );
}