【错误监控】别只做工具人了！手把手带你写一个前端错误监控 SDK

error-monitor/├── dist/                # 打包产物├── src/                 # 源码目录│   ├── index.ts         # 入口文件│   ├── errorHandler.ts  # JS 错误捕获│   ├── networkMonitor.ts# 网络请求监控│   ├── resourceMonitor.ts# 资源加载监控│   ├── sender.ts        # 上报逻辑│   └── utils.ts         # 工具函数├── test/                # 测试靶场│   ├── server.js        # 本地测试服务│   └── index.html       # 错误触发页面├── package.json         # 项目配置├── rollup.config.js     # Rollup 打包配置├── tsconfig.json        # TypeScript 配置└── README.md

// src/index.tsimport { monitorJavaScriptErrors } from './errorHandler';import { monitorNetworkErrors } from './networkMonitor';import { monitorResourceErrors } from './resourceMonitor';
interface ErrorMonitorConfig {  reportUrl: string; // 上报接口地址  projectName: string; // 项目标识  environment: string; // 环境 (dev/prod)}
export const initErrorMonitor = (config: ErrorMonitorConfig) => {  const { reportUrl, projectName, environment } = config;
  // 启动三大监控模块  monitorJavaScriptErrors(reportUrl, projectName, environment);  monitorNetworkErrors(reportUrl, projectName, environment);  monitorResourceErrors(reportUrl, projectName, environment);};

// src/errorHandler.tsimport { sendErrorData } from './sender';
export const monitorJavaScriptErrors = (  reportUrl: string,  projectName: string,  environment: string) => {  // 1. 捕获 JS 运行时错误  const originalOnError = window.onerror;  window.onerror = (message, source, lineno, colno, error) => {    const errorInfo = {      type: 'JavaScript Error',      message,      source,      lineno,      colno,      stack: error ? error.stack : null,      projectName,      environment,      timestamp: new Date().toISOString(),    };    sendErrorData(errorInfo, reportUrl);
    // 关键点：如果原来有 onerror 处理函数，继续执行它，避免覆盖用户逻辑    // 这样做是为了不破坏宿主环境（例如用户自己写的或其他 SDK）已有的错误处理逻辑    if (originalOnError) {      return originalOnError(message, source, lineno, colno, error);    }  };
  // 2. 捕获未处理的 Promise Rejection  const originalOnUnhandledRejection = window.onunhandledrejection;  window.onunhandledrejection = (event) => {    const errorInfo = {      type: 'Unhandled Promise Rejection',      message: event.reason?.message || event.reason,      stack: event.reason?.stack,      projectName,      environment,      timestamp: new Date().toISOString(),    };    sendErrorData(errorInfo, reportUrl);
    // 关键点：执行原有的 Promise 错误处理逻辑    // 这样做是为了不破坏宿主环境（例如用户自己写的或其他 SDK）已有的错误处理逻辑    if (originalOnUnhandledRejection) {      return originalOnUnhandledRejection.call(window, event);    }  };};

// src/networkMonitor.tsexport const monitorNetworkErrors = (  reportUrl: string,  projectName: string,  environment: string) => {  // 1. 劫持 XMLHttpRequest  const originalXhrOpen = XMLHttpRequest.prototype.open;  XMLHttpRequest.prototype.open = function (    method: string,    url: string | URL,    ...args: any[]  ) {    // 关键点：排除上报接口自身的请求，防止死循环    const urlStr = typeof url === 'string' ? url : String(url);    if (urlStr.includes(reportUrl)) {      return originalXhrOpen.apply(this, [method, url, ...args] as any);    }
    // 监听 error 事件    this.addEventListener('error', () => {      sendErrorData(        {          type: 'Network Error',          message: `Request Failed: ${method}${url}`,          projectName,          environment,        },        reportUrl      );    });    return originalXhrOpen.apply(this, [method, url, ...args] as any);  };
  // 2. 劫持 Fetch  const originalFetch = window.fetch;  window.fetch = async (input, init) => {    // 关键点：排除上报接口自身的请求，防止死循环    const urlStr = (input instanceof Request) ? input.url : String(input);    if (urlStr.includes(reportUrl)) {      return originalFetch(input, init);    }
    try {      const response = await originalFetch(input, init);      if (!response.ok) {        sendErrorData(          {            type: 'Fetch Error',            message: `HTTP ${response.status}: ${response.statusText}`,            url: input instanceof Request ? input.url : input,            projectName,            environment,          },          reportUrl        );      }      return response;    } catch (error) {      // 网络故障等无法发出请求的情况      sendErrorData(        {          type: 'Fetch Error',          message: `Fetch Failed: ${input}`,          projectName,          environment,        },        reportUrl      );      throw error;    }  };};

// src/resourceMonitor.tsexport const monitorResourceErrors = (  reportUrl: string,  projectName: string,  environment: string) => {  // 注意：useCapture 设置为 true，在捕获阶段处理  window.addEventListener(    'error',    (event) => {      const target = event.target as HTMLElement;      // 过滤掉 window 自身的 error，只处理资源元素的 error      if (target && (target.tagName === 'IMG' || target.tagName === 'SCRIPT')) {        sendErrorData(          {            type: 'Resource Load Error',            message: `Failed to load ${target.tagName}: ${              target.getAttribute('src') || target.getAttribute('href')            }`,            projectName,            environment,          },          reportUrl        );      }    },    true // 捕获阶段  );};

// src/sender.tsexport const sendErrorData = (errorData: Record<string, any>, url: string) => {  // 补充浏览器信息（UserAgent 等）  const dataToSend = {    ...errorData,    userAgent: navigator.userAgent,    // 还可以添加更多环境信息，如屏幕分辨率、当前 URL 等  };
  // 优先使用 sendBeacon (异步，不阻塞，页面卸载时仍有效)  if (navigator.sendBeacon) {    const blob = new Blob([JSON.stringify(dataToSend)], {      type: 'application/json',    });    navigator.sendBeacon(url, blob);  } else {    // 降级使用 fetch    fetch(url, {      method: 'POST',      headers: { 'Content-Type': 'application/json' },      body: JSON.stringify(dataToSend),    }).catch(console.error);  }};

{  "name": "error-monitor-sdk",  "version": "1.0.0",  "description": "A lightweight front-end error monitoring SDK",  "main": "dist/index.cjs.js", // CommonJS 入口  "module": "dist/index.esm.js", // ESM 入口  "browser": "dist/index.umd.js", // UMD 入口  "type": "module",  "scripts": {    "build": "rollup -c",    "dev": "rollup -c -w"  },  "keywords": ["error-monitor", "frontend", "sdk"],  "license": "MIT",  "files": ["dist"], // 发布时仅包含 dist 目录  "devDependencies": {    "rollup": "^4.9.0",    "@rollup/plugin-typescript": "^11.1.0",    "@rollup/plugin-terser": "^0.4.0", // 用于压缩代码    "typescript": "^5.3.0",    "tslib": "^2.6.0"  }}

{  "compilerOptions": {    "target": "es5", // 编译成 ES5，兼容旧浏览器    "module": "esnext", // 保留 ES 模块语法，交给 Rollup 处理    "declaration": true, // 生成 .d.ts 类型文件 (关键！)    "declarationDir": "./dist", // 类型文件输出目录    "strict": true, // 开启严格模式，代码更健壮    "moduleResolution": "node" // 按 Node 方式解析模块  },  "include": ["src/**/*"] // 编译 src 下的所有文件}

import typescript from '@rollup/plugin-typescript';import terser from '@rollup/plugin-terser';
export default {  input: 'src/index.ts', // 入口文件  output: [    {      file: 'dist/index.cjs.js',      format: 'cjs',      sourcemap: true,    },    {      file: 'dist/index.esm.js',      format: 'es',      sourcemap: true,    },    {      file: 'dist/index.umd.js',      format: 'umd',      name: 'ErrorMonitor', // <script> 引入时的全局变量名',      sourcemap: true,      plugins: [terser()], // UMD 格式进行压缩体积    },  ],  plugins: [    typescript({      tsconfig: './tsconfig.json',      declaration: true,      declarationDir: 'dist',    }),  ],};

npm login

npm run build

npm publish --access public

# 请将 error-monitor-sdk 替换为你实际发布的包名npm install error-monitor-sdk

// 请将 error-monitor-sdk 替换为你实际发布的包名import { initErrorMonitor } from 'error-monitor-sdk';
initErrorMonitor({  reportUrl: 'http://localhost:3000/error-report',  projectName: 'MyAwesomeProject',  environment: 'production',});

# 请将 error-monitor-sdk 替换为你实际发布的包名npm install error-monitor-sdk

// 请将 error-monitor-sdk 替换为你实际发布的包名const { initErrorMonitor } = require('error-monitor-sdk');
initErrorMonitor({  reportUrl: 'http://localhost:3000/error-report',  projectName: 'MyAwesomeProject',  environment: 'production',});

<!-- 请将 error-monitor-sdk 替换为你实际发布的包名，x.x.x 替换为具体版本号 --><scriptsrc="https://unpkg.com/[email protected]/dist/index.umd.js"></script>
<script>  // UMD 版本会将 SDK 挂载到 window.ErrorMonitor  ErrorMonitor.initErrorMonitor({    reportUrl: 'http://localhost:3000/error-report',    projectName: 'MyAwesomeProject',    environment: 'production',  });</script>

// src/index.ts (补充)
// Vue 3 插件：统一接入框架错误 + 自动初始化全局监控export const VueErrorMonitorPlugin = {  install(app: any, options: { reportUrl: string; projectName: string; environment: string }) {    if (!options || !options.reportUrl) return;
    // 开启 JS/Promise/网络/资源监控    initErrorMonitor(options); 
    const original = app.config.errorHandler;    // vue提供的捕获组件内错误的事件    app.config.errorHandler = (err: unknown, instance?: unknown, info?: unknown) => {      sendErrorData({        message: formatErrorMessage(err),        stack: (err as any)?.stack || null,        projectName: options.projectName,        environment: options.environment,        errorType: 'Vue Error',        timestamp: new Date().toISOString(),        userAgent: navigator.userAgent,        info,      }, options.reportUrl);
      if (typeof original === 'function') {        try { (original as any)(err, instance, info); } catch {}      }    };  }};
// React 错误边界：捕获子树渲染错误并上报export const createReactErrorBoundary = (React: any, config: { reportUrl: string; projectName: string; environment: string }) => {
  // 确保在创建边界组件时启动全局监控（JS/网络/资源）  if (config && config.reportUrl) {    initErrorMonitor(config);  }
  return class ErrorMonitorBoundary extends React.Component {    constructor(props: any) {      super(props);      this.state = { hasError: false };    }    static getDerivedStateFromError() { return { hasError: true }; }    componentDidCatch(error: any, info: any) {      sendErrorData({        message: formatErrorMessage(error),        stack: error?.stack || null,        projectName: config.projectName,        environment: config.environment,        errorType: 'React Error',        timestamp: new Date().toISOString(),        userAgent: navigator.userAgent,        componentStack: info?.componentStack || null,      }, config.reportUrl);    }    render() {      if ((this.state as any).hasError) return (this.props as any).fallback || null;      return (this.props as any).children;    }  };};

import { createApp } from 'vue';import { VueErrorMonitorPlugin } from 'error-monitor-sdk';
const app = createApp(App);// 一行代码，同时开启全局监控和 Vue 错误捕获app.use(VueErrorMonitorPlugin, {  reportUrl: 'http://localhost:3000/error-report',  projectName: 'MyVueProject',  environment: 'production',});app.mount('#app');

import React from 'react';import ReactDOM from 'react-dom';import { createReactErrorBoundary } from 'error-monitor-sdk';
// 1. 创建错误边界组件const ErrorBoundary = createReactErrorBoundary(React, {  reportUrl: 'http://localhost:3000/error-report',  projectName: 'MyReactProject',  environment: 'production',});
// 2. 包裹根组件，即可捕获整个应用树的渲染错误ReactDOM.render(  <ErrorBoundaryfallback={<h1>Something went wrong.</h1>}>    <App />  </ErrorBoundary>,  document.getElementById('root'));