Skip to main content

渲染异常捕获 ErrorBoundary

ErrorBoundary 是一个 React 错误边界组件，用于捕获子组件渲染过程中的异常，防止页面直接白屏，并提供友好的错误提示页面。

📦 引入方式​

import { ErrorBoundary } from '@npmqg/react-ui-errorboundary';

🧩 使用示例​

📚 基础用法​

将 ErrorBoundary 包裹在你需要保护的组件外层即可：

<ErrorBoundary path="/index">
  <MyComponent />
</ErrorBoundary>

当 MyComponent 或其子组件发生渲染错误时，ErrorBoundary 会自动捕获并展示 Error_1001 页面。

📚 带路由跳转的错误页​

内置 path 属性，可以配置点击按钮后跳转指定路由：

<ErrorBoundary path="/index">
  <RouterView /> {/* 路由出口 */}
</ErrorBoundary>

错误发生时，会显示错误提示，并提供跳转到 指定路由 的按钮。

📚 自定义点击事件和按钮文本​

<ErrorBoundary
  title="刷新页面"
  onClick={() => {
    location.reload();
  }}
>
  <App />
</ErrorBoundary>

📚 捕获局部错误​

如果只希望在某个模块内捕获错误，可以局部使用：

function App() {
  return (
    <div>
      <Header />

      {/* 仅保护主要业务模块 */}
      <ErrorBoundary path="/index">
        <MainContent />
      </ErrorBoundary>

      <Footer />
    </div>
  );
}

这样即使 MainContent 内报错，Header 和 Footer 仍然正常渲染。

🔔 注意事项​

  • ErrorBoundary 无法捕获以下错误：

    • 事件处理函数中的错误
    • 异步代码（如 setTimeout、Promise）中的错误
    • 服务端渲染（SSR）时的错误
    • 👉 这些需要用 try/catch 或全局 window.onerror/unhandledrejection 来处理。

  • getDerivedStateFromError 返回的 error 建议保持为 Error 类型，而不是字符串拼接（可以在 render 时转成字符串），否则可能丢失堆栈信息。

  • 日志建议上报到监控平台（如 Sentry、阿里 ARMS）。