Remix 错误处理完全指南：ErrorBoundary 体系实战

Remix 自动捕获 loader、action 与组件渲染中抛出的错误，渲染最近的 ErrorBoundary 导出——每个路由模块可导出自己的边界实现"局部出错不拖垮整页"。预期内错误用 throw data(...) 携带状态码抛出，边界内用 useRouteError + isRouteErrorResponse 区分处理。

Remix 错误处理的范式优势

传统 SPA 里数据获取错误要手动 try/catch 再 setState；Remix 把这条路自动化：loader 抛错 → 路由的 ErrorBoundary 渲染，URL、导航状态、页面其余部分全部保持正常。错误处理从命令式琐事变成声明式约定，这是 Remix 设计中最被低估的亮点。

基本模式：抛出与捕获

// app/routes/users.$id.tsx
export async function loader({ params }: LoaderFunctionArgs) {
  const user = await db.user.find(params.id);
  if (!user) {
    throw data({ message: '用户不存在' }, { status: 404 });
  }
  return { user };
}

export function ErrorBoundary() {
  const error = useRouteError();

  if (isRouteErrorResponse(error)) {
    // throw data() 抛出的预期内错误
    return <div>{error.status}：{error.data.message}</div>;
  }

  // 未预期的程序错误
  return <div>页面出错了，请稍后重试</div>;
}

两类错误的分界清晰：throw data() 是你主动抛的业务错误（带状态码）；其他异常是 bug，统一兜底。

action 与表单错误

export async function action({ request }: ActionFunctionArgs) {
  const formData = await request.formData();
  const result = schema.safeParse(Object.fromEntries(formData));
  if (!result.success) {
    return { errors: result.error.flatten().fieldErrors };  // 校验错误 return（不抛）
  }
  try {
    await createUser(result.data);
    return redirect('/users');
  } catch (e) {
    throw data({ message: '创建失败' }, { status: 500 });   // 系统错误 throw
  }
}

惯例：表单校验错误 return 给 useActionData 渲染字段提示，系统错误 throw 给 ErrorBoundary——一个进表单，一个进边界，用户看到各自的界面。

嵌套边界：错误隔离的粒度

Remix 路由的嵌套天然形成错误隔离层级：

routes/
├── _app.tsx                  ← 全局边界（导航栏保持可用）
├── _app.users.tsx            ← users 段边界
├── _app.users.$id.tsx        ← 详情页边界

详情页 loader 抛错只影响主内容区，布局与导航完好；根级错误冒泡到 root 边界。设计原则：边界粒度跟着"哪些部分可以独立失败"走。

生产环境脱敏

生产环境必须防止堆栈泄露给客户端。在入口（entry.server）的 handleError 中统一记录日志；ErrorBoundary 中对非 RouteErrorResponse 只展示通用文案 + 错误 ID，错误 ID 关联服务端日志便于排查。never 把 err.message 直接渲染——数据库连接串泄露的事故就是这么来的。

区分用户输入错误与服务端故障

Remix 的表单校验失败通常属于预期行为，应与 loader/action 的运行时异常分开统计。观测云 RUM 适合观察页面操作和前端错误，服务端日志与 APM 则用于检查失败请求及其下游调用。SSR 项目只在浏览器入口初始化 RUM，Node.js 探针在服务器侧加载；错误内容上报前要剔除表单中的凭据和个人数据。

接入文档：Web RUM 接入 · 日志采集 · Node.js APM 接入。

常见问题（FAQ）

Q：ErrorBoundary 捕获不到哪些错误？

事件处理器（onClick）内的错误、setTimeout 回调、以及边界组件自身抛出的错误。事件错误用 try/catch 本地处理；边界自身错误冒泡到上一级边界。

Q：loader 里 fetch 下游 API 失败怎么优雅处理？

预期内失败（404/超时）catch 后 throw data() 转业务错误，或返回降级数据让页面部分渲染；下游抖动频繁时在 fetch 层加 retry 与超时控制（AbortController），别让用户等一个挂起的连接。

Q：CatchBoundary 和 ErrorBoundary 还有区别吗？

Remix v2 起两者合并为 ErrorBoundary（isRouteErrorResponse 区分捕获类型）；v1 的 CatchBoundary 已废弃，升级项目记得合并两个导出。

---

参考文档

• Remix v2 文档

本文依据公开文档整理，示例需按项目依赖版本验证；不将文档中的性能描述视为本项目实测结果。

延伸阅读

• Next.js 错误处理完全指南（Pages 与 App Router）
• esbuild 的六大替代方案