跳转到主要内容
本文档介绍异常类型、捕获机制、手动上报方法、React 集成以及上报的异常数据结构定义。

​
异常类型

RUM 可以监控以下类型的异常：
包括代码语法错误、运行时异常和未处理的 Promise 异常等。这些问题可能导致页面功能失效，严重影响用户体验。

​
上报方式

​
自动错误捕获

RUM SDK 自动捕获以下类型的浏览器错误：
错误类型说明
未捕获的异常运行时抛出的 JavaScript 异常（如 TypeError、ReferenceError）
未处理的 Promise 拒绝未被 .catch() 处理的 Promise 错误
网络错误XHR 或 Fetch 请求失败（如 4xx、5xx 状态码或网络中断）
React 渲染错误React 组件渲染期间的异常（需配合错误边界）
  • 自动捕获的错误默认包含堆栈跟踪、错误消息和来源信息。
  • 来自浏览器扩展或第三方脚本的错误（如 network 来源）会被过滤，避免数据污染。

​
手动错误上报

通过 addError API，您可以手动上报已处理的异常、自定义错误或其他未被自动捕获的错误。 适用场景：
  • 记录业务逻辑中的已处理错误
  • 附加上下文信息（如用户 ID、页面状态）以便问题排查
  • 监控第三方服务或异步操作的异常
// 上报带有上下文的自定义错误
const error = new Error("登录失败");
window.FC_RUM.addError(error, {
  pageStatus: "beta",
  userId: "12345",
  action: "login_attempt",
});

​
React 错误边界集成

RUM 支持通过 React 错误边界捕获组件渲染错误，并将错误信息上报。您可以在 componentDidCatch 中调用 addError API，附加组件堆栈信息以便调试。
1

创建错误边界组件

class ErrorBoundary extends React.Component {
  componentDidCatch(error, info) {
    const renderingError = new Error(error.message);
    renderingError.name = "ReactRenderingError";
    renderingError.stack = info.componentStack; // 组件堆栈
    renderingError.cause = error; // 原始错误

    window.FC_RUM.addError(renderingError, {
      component: this.props.componentName || "Unknown",
      version: "1.0.0",
    });
  }

  render() {
    return this.props.children;
  }
}
2

使用错误边界包装组件

<ErrorBoundary componentName="UserProfile">
  <UserProfile />
</ErrorBoundary>

​
错误数据结构

每条错误数据包含以下属性，用于描述错误详情和上下文：
​
error.source
string
错误来源（如 console、network、custom、source、report）。微信小程序 SDK 还会上报 app（来自 wx.onError）和 promise（来自 wx.onUnhandledRejection）两个值，详情见微信小程序数据采集。
​
error.type
string
错误类型或错误码（如 TypeError、NetworkError）
​
error.message
string
简洁的可读性强的错误消息
​
error.stack
string
错误堆栈跟踪或补充信息
​
error.causes
Array
提供额外上下文的关联错误列表（可选）
​
context
Object
自定义上下文信息（如页面状态、用户 ID），通过 addError 传入

​
错误过滤与配置

为确保错误数据的准确性和相关性，RUM 应用以下过滤规则：
  • 仅处理 source 为 custom、source、report 或 console 的错误
  • 忽略来自浏览器扩展、第三方脚本或 network 来源的无关错误
错误必须包含堆栈跟踪信息，否则可能被忽略
使用 beforeSend 回调自定义错误处理逻辑，过滤或修改错误数据

​
自定义错误过滤示例

window.FC_RUM.init({
  beforeSend: (event) => {
    if (event.type === "error") {
      // 忽略特定错误消息
      if (event.error.message.includes("ThirdPartyScript")) {
        return false; // 丢弃该错误
      }
      // 添加全局上下文
      event.context = { ...event.context, appVersion: "2.1.0" };
    }
    return true;
  },
});

​
常见问题

  • 确认堆栈跟踪是否完整，或自定义指纹是否冲突
  • 检查 sourcemap 是否正确上传，若未上传，堆栈可能无法正确解析
使用 beforeSend 回调过滤特定错误来源或消息：
beforeSend: (event) => {
  if (event.error.source === "network") return false;
  return true;
};
  • 确保 fingerprint 属性正确设置，且值为字符串
  • 检查 beforeSend 回调是否被正确调用

​
最佳实践

丰富上下文信息

在 addError 中附加业务相关上下文（如用户 ID、操作类型），便于问题定位。示例：{ userId: "12345", action: "submit_form" }

优化错误边界

为关键 React 组件配置错误边界，确保渲染错误被捕获。记录组件名称和版本，便于追踪问题。

控制错误量

使用采样率或 beforeSend 过滤低价值错误，避免数据过载。优先监控影响用户体验的关键错误。

分析与可视化

在「分析看板」-「异常分析」Tab 查看错误数据趋势和分布，解决重点异常问题。

​
下一步

查看异常

了解如何在异常追踪模块查看和分析 Issue