bulletproof-react 前端错误处理实战：API 拦截器、多层 ErrorBoundary 与生产级错误追踪

本文基于 bulletproof-react 仓库的官方错误处理文档（docs/error-handling.md），系统讲解该架构的三层错误处理策略：用 Axios 拦截器统一收敛 API 错误（toast 提示、401 登出、token 刷新扩展点）、用多个局部 ErrorBoundary 隔离应用内渲染错误、用 Sentry 等工具追踪生产环境异常。读完后你能完整复现仓库中三套应用（react-vite / nextjs-app / nextjs-pages）共用的错误处理实现，并理解其背后的设计取舍。

三层防线：错误处理的完整脉络

bulletproof-react 将错误处理拆分为三个相互独立、职责清晰的层面，官方文档 docs/error-handling.md 中明确列出了这套分层思路：

1. API Errors：通过拦截器统一接管所有 HTTP 请求的错误，触发通知 toast 告知用户、登出未授权用户、或发起 token 刷新请求，以维持安全且无缝的应用运行；
2. In App Errors：使用 React 的 Error Boundary 处理特定局部区域的渲染错误，而不是只放一个覆盖整个应用的 boundary——错误可以被局部包含和管理，不会破坏整个应用的功能；
3. Error Tracking：生产环境的错误必须被追踪，推荐使用 Sentry 这类工具上报所有导致应用崩溃的问题，并能查看错误发生在哪个平台、哪个浏览器，同时务必上传 source map 以便定位到源码具体位置。

这三层分别对应"网络层"、"渲染层"和"可观测层"，下面逐层结合仓库源码展开。

API 层：Axios 拦截器统一收敛请求错误

官方文档给出的示例实现位于 apps/react-vite/src/lib/api-client.ts，这是整个项目所有 API 调用的唯一出口（所有 features/*/api/ 下的请求函数都基于这个实例）。完整实现如下：

import Axios, { InternalAxiosRequestConfig } from 'axios';

import { useNotifications } from '@/components/ui/notifications';
import { env } from '@/config/env';
import { paths } from '@/config/paths';

function authRequestInterceptor(config: InternalAxiosRequestConfig) {
  if (config.headers) {
    config.headers.Accept = 'application/json';
  }

  config.withCredentials = true;
  return config;
}

export const api = Axios.create({
  baseURL: env.API_URL,
});

api.interceptors.request.use(authRequestInterceptor);
api.interceptors.response.use(
  (response) => {
    return response.data;
  },
  (error) => {
    const message = error.response?.data?.message || error.message;
    useNotifications.getState().addNotification({
      type: 'error',
      title: 'Error',
      message,
    });

    if (error.response?.status === 401) {
      const searchParams = new URLSearchParams();
      const redirectTo =
        searchParams.get('redirectTo') || window.location.pathname;
      window.location.href = paths.auth.login.getHref(redirectTo);
    }

    return Promise.reject(error);
  },
);

这段实现里包含四个值得拆解的设计点：

请求拦截器：统一的会话与响应约定

authRequestInterceptor 对每个出站请求做两件事：

• 设置 Accept: application/json，强制服务端返回 JSON，让错误响应的结构可预期；
• 设置 withCredentials: true，让浏览器随请求携带 session cookie，这是基于 cookie 会话认证的传输层约定。

值得注意的是 baseURL 取自 apps/react-vite/src/config/env.ts 暴露的 env.API_URL，即 API 地址由环境配置注入，拦截器本身不关心部署目标。

响应拦截器：把"错误处理"从业务代码中剥离

响应成功的分支只有一行：return response.data。这意味着所有 api.get/post/... 的返回值自动解包为 response.data，业务侧（如 get-discussions.ts 等 API 函数）无需重复写 res.data。

错误分支则是官方文档所说的"集中管理点"，按顺序完成三件事：

1. 提取错误消息：优先取 error.response?.data?.message（服务端返回的结构化错误信息），取不到再降级到 error.message（如网络断开时的 "Network Error"）；
2. 推送 toast 通知：调用 useNotifications.getState().addNotification(...) 向全局通知 store 写入一条 type: 'error' 的通知。注意这里用的是 Zustand 的 getState() 而非 hook 形式——因为拦截器运行在 React 组件生命周期之外，必须用 store 的非 React 访问方式；
3. 401 专门处理：当状态码为 401 时，构造带 redirectTo 参数的登录页 URL 并跳转，让用户重新认证后能回到原来的页面。

最后 return Promise.reject(error) 保证错误仍然会沿 Promise 链抛出——拦截器只负责"副作用"（提示、跳转），不吞掉错误本身，调用方依然可以感知失败。

401 跳转与 redirectTo 的配合

登录跳转的 URL 由 apps/react-vite/src/config/paths.ts 中的 paths.auth.login.getHref(redirectTo) 生成：

login: {
  path: '/auth/login',
  getHref: (redirectTo?: string | null | undefined) =>
    `/auth/login${redirectTo ? `?redirectTo=${encodeURIComponent(redirectTo)}` : ''}`,
},

当前实现采取的是"401 即登出重定向"策略。官方文档中提到的"send requests to refresh tokens（发起 token 刷新请求）"属于该拦截器预留的扩展点：在真实的 token 刷新方案中，可以在 status === 401 分支里先尝试刷新 token 并重放原请求，刷新失败再跳转到登录页。从当前源码看，仓库选择了更简单直接的登出重定向方案，而拦截器结构本身恰好为两种策略提供了同一个插入位置——这正是"用拦截器管理错误"这一架构价值的体现。

通知 toast 的底层实现

toast 的存储与渲染分别由两个文件完成：

• notifications-store.ts：基于 Zustand 的 store，Notification 类型为 { id, type: 'info' | 'warning' | 'success' | 'error', title, message? }，addNotification 用 nanoid() 生成唯一 id 后追加，dismissNotification 按 id 移除；
• notification.tsx：单条通知的渲染组件，按 type 映射 lucide-react 图标与颜色（error 为红色 CircleX），根节点带 role="alert" 和 aria-label，保证屏幕阅读器可感知。

<Notifications /> 容器挂载在应用 Provider 层（provider.tsx），因此任何深度发起的请求失败都能被顶层 toast 展示，无需逐层传递回调。

应用内错误：ErrorBoundary 的局部隔离策略

官方文档第二条原则是："不要只为整个应用放一个 error boundary，而是在不同区域放置多个 boundary，这样错误可以被局部包含和管理。" 仓库中的示例实现是 discussion.tsx（讨论详情页路由）：

return (
  <>
    <ContentLayout title={discussion.title}>
      <DiscussionView discussionId={discussionId} />
      <div className="mt-8">
        <ErrorBoundary
          fallback={
            <div>Failed to load comments. Try to refresh the page.</div>
          }
        >
          <Comments discussionId={discussionId} />
        </ErrorBoundary>
      </div>
    </ContentLayout>
  </>
);

这里用的是 react-error-boundary 库，fallback 属性可以直接接收 React 节点。设计意图非常具体：评论区（Comments）出渲染错误时，只降级评论区为一行"Failed to load comments. Try to refresh the page."提示，而页面主体 DiscussionView（讨论标题、正文、操作区）完全不受影响。如果没有这层局部 boundary，评论区抛出的错误会一路上冒到最近的祖先 boundary，轻则整页白屏，重则触发根级 fallback 把用户踢回首页。

注意数据加载与渲染错误的分工：页面顶部的 discussionQuery.isLoading 分支显示 Spinner，数据获取失败由 React Query 层处理（见下文），ErrorBoundary 只负责"组件渲染期间抛出的异常"。两者互补，不构成重复处理。

仓库中 ErrorBoundary 的实际布局：不止一个

从源码结构看，仓库对"多层 boundary"的执行相当彻底，以下位置都部署了独立的边界（三套应用中模式一致，这里以 react-vite 为主线）：

层级	位置	作用
应用根级	provider.tsx 中的 <ErrorBoundary FallbackComponent={MainErrorFallback}>	最后一道防线，兜住任何漏网的渲染错误
路由级	router.tsx 的 app 根路由 ErrorBoundary: AppRootErrorBoundary（react-router 原生能力），实现见 root.tsx	单个应用内路由崩溃时局部降级
布局级	Next.js 版 dashboard-layout.tsx 的 <ErrorBoundary key={pathname}>	按路由隔离，换路由自动重置边界状态
功能区块级	discussion.tsx 的评论区 boundary	错误仅影响评论区

根级兜底的 fallback 组件是 main.tsx 中的 MainErrorFallback：全屏居中的红色告警 + "Ooops, something went wrong :(" 文案 + 一个跳回 origin 的 Refresh 按钮，并带 role="alert" 无障碍属性。它在 provider.tsx 中包裹 HelmetProvider、QueryClientProvider 与 Notifications 等全部全局 Provider。

一个值得借鉴的细节在 Next.js App 版布局中：<ErrorBoundary key={pathname}> 通过把 pathname 作为 key，让路由切换时 boundary 整体卸载重建，从而自动重置已捕获的错误状态——用户从一个崩溃页面导航走再回来，看到的是干净的新组件而非缓存的 fallback。这是 react-error-boundary 场景下常用的状态复位手法。

错误追踪：生产环境的可观测性

官方文档第三部分的要求是：生产环境中出现的任何错误都应被追踪。虽然可以自己实现上报，但文档建议直接使用 Sentry 这类现成工具，它能上报任何导致应用损坏的问题，并提供错误发生的平台、浏览器等上下文；同时必须上传 source map，否则只能看到压缩后的堆栈而无法定位到源码位置。

这一层与前面的两层是正交的：拦截器保证用户"感知得到"错误，ErrorBoundary 保证应用"崩溃不了"，而错误追踪保证团队"发现得了"线上问题。仓库当前代码中未内置具体 SDK 的接入代码（属于部署时按需集成），落地时需要注意文档强调的两点前提：

• 上报钩子要同时覆盖 API 拦截器的错误分支（网络层错误）和 ErrorBoundary 的 onError 回调（渲染层错误）；
• 构建产物必须与线上 bundle 的 source map 版本一致，否则堆栈还原会错位。

与 React Query 的配合：错误只处理一次

理解这套错误处理为何不会"重复弹 toast"，需要看全局查询配置 react-query.ts：

export const queryConfig = {
  queries: {
    // throwOnError: true,
    refetchOnWindowFocus: false,
    retry: false,
    staleTime: 1000 * 60,
  },
} satisfies DefaultOptions;

关键在 retry: false：请求失败后 React Query 不会自动重试，错误经由上述 Axios 拦截器恰好被处理一次（弹一条 toast），然后以 rejected 状态停留在 query 中，由 UI 自行决定展示。如果开启默认的重试策略，一次失败可能触发多次 toast，而文档中"interceptor 是错误管理的有效手段"这一论断的前提，正是错误有唯一、确定的处理点。staleTime 一分钟则减少了不必要的重复请求，间接降低了错误面。

小结

bulletproof-react 的错误处理架构可以归纳为三条可直接复用的工程决策：

1. 错误处理集中化：所有 HTTP 错误收敛到 Axios 响应拦截器一处，完成"toast 提示 + 401 登出重定向 + 保持 Promise 拒绝链"三件事，业务代码无需各自 try/catch 做用户提示；
2. 错误隔离分级化：从功能区块（评论区）→ 路由（react-router ErrorBoundary / key={pathname} 布局级）→ 应用根（MainErrorFallback 全屏兜底）逐层布防，局部故障不扩散为全局白屏；
3. 线上错误可观测化：用 Sentry 等工具 + source map 上传兜住前两层看不到的生产异常。

以上三套应用（react-vite、nextjs-app、nextjs-pages）共享同一套错误处理骨架，相关代码入口均已在前文给出，可对照阅读验证。