前端错误监控全攻略：Sentry、SourceMap 与用户无感知的异常捕获

前端工程（更新于 2026年6月2日）

为什么前端错误监控不可或缺？

线上用户遇到白屏、按钮无响应、接口报错——如果你不知道，就无法修复。前端错误监控是连接用户真实体验与开发者认知的桥梁。

不监控的代价 监控的收益
用户投诉才发现 Bug 实时感知异常，分钟级响应
无法复现的偶发问题 完整堆栈 + 用户行为回放
线上故障持续数小时 自动告警，MTTR 大幅缩短
修复靠猜测 数据驱动，精准定位

前端错误的五大来源

1. 语法与运行时错误

// ReferenceError: x is not defined
console.log(x);

// TypeError: Cannot read properties of undefined
const user = undefined;
user.name;

2. 资源加载错误

// 图片、脚本、样式表加载失败
const img = new Image();
img.src = '/broken-image.png';
img.onerror = () => {
  trackError({ type: 'resource', tag: 'img', src: img.src });
};

3. 未捕获的 Promise 异常

// 最容易被遗漏的错误类型
fetch('/api/data')
  .then(res => res.json())
  // .then 中抛出异常但无 .catch
  .then(data => data.results.map(r => r.name));

4. 接口异常

// HTTP 错误码 + 业务错误码
fetch('/api/order')
  .then(res => {
    if (!res.ok) {
      trackError({ type: 'http', status: res.status, url: res.url });
    }
    return res.json();
  });

5. Web Worker / iframe 错误

// Worker 内部异常不会冒泡到主线程
const worker = new Worker('/worker.js');
worker.onerror = (e) => {
  trackError({
    type: 'worker',
    message: e.message,
    filename: e.filename,
    lineno: e.lineno,
  });
};

全局错误捕获：四道防线

防线一：window.onerror

window.onerror = (message, source, lineno, colno, error) => {
  trackError({
    type: 'runtime',
    message,
    source,
    lineno,
    colno,
    stack: error?.stack,
  });
  return false; // 不阻止默认控制台输出
};

局限：无法捕获资源加载错误和 Promise 异常。

防线二：window.addEventListener('error')

window.addEventListener('error', (event) => {
  if (event.target instanceof HTMLElement) {
    // 资源加载错误
    trackError({
      type: 'resource',
      tagName: event.target.tagName,
      src: event.target.src || event.target.href,
    });
  } else {
    // 运行时错误（与 onerror 重复，需去重）
    trackError({
      type: 'runtime',
      message: event.message,
      stack: event.error?.stack,
    });
  }
}, true); // 使用捕获阶段

防线三：window.addEventListener('unhandledrejection')

window.addEventListener('unhandledrejection', (event) => {
  trackError({
    type: 'unhandledRejection',
    reason: event.reason?.message || String(event.reason),
    stack: event.reason?.stack,
  });
});

防线四：React Error Boundary

class ErrorBoundary extends React.Component {
  state = { hasError: false };

  static getDerivedStateFromError(error) {
    return { hasError: true };
  }

  componentDidCatch(error, errorInfo) {
    trackError({
      type: 'react',
      message: error.message,
      stack: error.stack,
      componentStack: errorInfo.componentStack,
    });
  }

  render() {
    if (this.state.hasError) {
      return <FallbackUI onRetry={() => this.setState({ hasError: false })} />;
    }
    return this.props.children;
  }
}

SourceMap 反解：从压缩代码还原真实堆栈

线上代码经过压缩混淆，错误堆栈毫无可读性。SourceMap 反解是线上排障的核心能力。

压缩后的堆栈示例

TypeError: Cannot read properties of undefined (reading 'name')
  at a (main.abc123.js:1:2345)
  at o (main.abc123.js:1:5678)
  at t (main.abc123.js:1:9012)

反解后的真实堆栈

TypeError: Cannot read properties of undefined (reading 'name')
  at getUserInfo (src/services/user.ts:42:15)
  at fetchDashboard (src/pages/dashboard.tsx:128:22)
  at useEffectCallback (src/pages/dashboard.tsx:115:5)

SourceMap 安全策略

方案 安全性 复杂度 适用场景
私有 NPM + CI 反解 高 中 大多数团队
Sentry 服务端反解 中 低 快速接入
Base64 内联 SourceMap 低 低 仅开发环境
独立 .map 文件上线 极低 低 不推荐 
// 使用 source-map 库反解
import { SourceMapConsumer } from 'source-map';

async function applySourceMap(position, mapContent) {
  const consumer = await new SourceMapConsumer(mapContent);
  const original = consumer.originalPositionFor({
    line: position.line,
    column: position.column,
  });
  return original;
}

Sentry 集成实战

安装与初始化

npm install @sentry/react @sentry/tracing

import * as Sentry from '@sentry/react';

Sentry.init({
  dsn: 'https://xxx@o123456.ingest.sentry.io/789',
  environment: process.env.NODE_ENV,
  release: process.env.APP_VERSION,
  tracesSampleRate: 0.1,
  replaysSessionSampleRate: 0.01,
  replaysOnErrorSampleRate: 1.0,
  integrations: [
    Sentry.browserTracingIntegration(),
    Sentry.replayIntegration(),
  ],
  beforeSend(event, hint) {
    // 过滤无意义错误
    if (event.exception?.values?.[0]?.type === 'ResizeObserver loop limit exceeded') {
      return null;
    }
    return event;
  },
});

React 路由集成

const SentryRoutes = Sentry.withSentryReactRouterV6Routing(Routes);

function App() {
  return (
    <SentryRoutes>
      <Route path="/" element={<Home />} />
      <Route path="/dashboard" element={<Dashboard />} />
    </SentryRoutes>
  );
}

手动上报与面包屑

// 手动上报业务异常
Sentry.captureException(new Error('订单支付超时'), {
  tags: { orderId: 'ORD-12345', paymentMethod: 'alipay' },
  extra: { retryCount: 3, lastAttempt: Date.now() },
});

// 添加面包屑（用户行为轨迹）
Sentry.addBreadcrumb({
  category: 'ui.click',
  message: '点击提交按钮',
  level: 'info',
});

自建轻量监控体系

如果不想依赖第三方服务，可以自建监控：

数据采集 SDK

class ErrorMonitor {
  constructor(options) {
    this.endpoint = options.endpoint;
    this.queue = [];
    this.timer = null;
    this.install();
  }

  install() {
    window.addEventListener('error', this.handleError.bind(this), true);
    window.addEventListener('unhandledrejection', this.handleRejection.bind(this));
  }

  handleError(event) {
    this.report({
      type: event.target instanceof HTMLElement ? 'resource' : 'runtime',
      message: event.message || event.target?.outerHTML,
      stack: event.error?.stack,
      timestamp: Date.now(),
      url: location.href,
      ua: navigator.userAgent,
    });
  }

  handleRejection(event) {
    this.report({
      type: 'unhandledRejection',
      message: event.reason?.message || String(event.reason),
      stack: event.reason?.stack,
      timestamp: Date.now(),
    });
  }

  report(data) {
    this.queue.push(data);
    if (!this.timer) {
      this.timer = setTimeout(() => this.flush(), 5000);
    }
  }

  flush() {
    if (this.queue.length === 0) return;
    const batch = this.queue.splice(0);
    navigator.sendBeacon(this.endpoint, JSON.stringify(batch));
    this.timer = null;
  }
}

关键指标仪表盘

指标 计算方式 告警阈值
JS 错误率 错误 PV / 总 PV > 0.1%
接口失败率 5xx 数 / 总请求数 > 1%
首屏崩溃率 白屏 PV / 总 PV > 0.01%
平均修复时间 首次告警到部署耗时 > 30min

最佳实践清单

  1. 四道防线全覆盖：onerror + error 事件 + unhandledrejection + Error Boundary
  2. SourceMap 不上线：构建产物分离，CI 环境反解
  3. 错误采样与过滤：避免高频无意义错误淹没真实问题
  4. 用户行为回放：面包屑 + Session Replay 加速定位
  5. 告警分级：P0 立即通知，P1 工单跟踪，P2 周报汇总
  6. 版本关联：每次发布携带版本号，错误自动关联代码变更
  7. 隐私合规：上报数据脱敏，不包含用户个人信息
  8. 性能关联：错误监控与性能监控联动，发现性能劣化根因

本站提供浏览器本地工具，免注册即可试用 →

#错误监控#Sentry#SourceMap#异常捕获#DevOps