js-monitor

背景介绍

• 为了完善项目质量, 我们需要对异常进行监控, 基于此背景开发一个异常监控sdk捕获错误,即js-monitor

安装

yarn install @ustinian-wang/js-monitor@latest
# 或
npm install @ustinian-wang/js-monitor@latest

使用

1. 引入并初始化

umd

<script src="https://cdn.jsdelivr.net/npm/@ustinian-wang/js-monitor@latest">
window.addEventListener('DOMContentLoaded', (e) => {
    console.log('DOMContentLoaded', e);
    const JsMonitor = window.JsMonitor;
    JsMonitor.setup({
        appId: 'monitor-demo',
        api: 'http://localhost:3000/api/monitor',
        debug: true
    });
});
</script>

esm

import { setup } from 'js-monitor';

setup({
  appId: 'your-app-id',
  api: '/api/report', // 或自定义函数
  debug: true,
  filter: (data) => false, // 返回 true 则不上报
  transform: (data) => data, // 可自定义数据转换
});

| 参数名 | 类型 | 必填 | 说明 | | --------- | -------------------------- | ---- | -------------------------------------------------------------------- | | force | boolean | 否 | 是否强制安装，默认false。setup默认只能执行一次，重复setup只执行一次，但force为true时每次setup都会重新初始化 | | appId | string | 是 | 应用唯一标识 | | api | string | Function | 是 | 上报地址（字符串）或自定义上报函数 | | debug | boolean | 否 | 是否开启调试模式（开启后会打印调试日志） | | filter | (data) => boolean | 否 | 过滤函数，返回 true 时本次数据不上报 | | transform | (data) => object | 否 | 数据转换函数，上报前可对数据进行自定义处理 | | warnHandler | (error, vm, info) => void | 否 | Vue.config.warnHandler 警告处理函数 | | errorHandler | (error, vm, info) => void | 否 | Vue.config.errorHandler 错误处理函数 | | unhandledrejection | (event) => void | 否 | window.unhandledrejection 未捕获异常处理函数 | | onerror | (message, source, lineno, colno, error) => void | 否 | window.onerror 错误处理函数 | | error | (event) => void | 否 | window.addEventListener('error', config.error) 资源加载错误处理函数 | | report | (config, data) => void | 否 | 上报回调 |

2. 手动上报

import { report } from 'js-monitor';

report({
  appId: 'your-app-id',
  api: '/api/report',
  filter: () => false,
  transform: (data) => data,
}, {
  type: 'custom',
  message: '自定义上报内容'
});

| 参数名 | 类型 | 必填 | 说明 | | ------ | ---------------------- | ---- | ---------------------------- | | config | setupConfigDef | 是 | 同 setup 的配置参数 | | data | reportDataDef | 是 | 需要上报的数据对象 |

data（reportDataDef）常用字段 | 字段名 | 类型 | 说明 | | --------- | --------- | ---------------------- | | appId | string | 应用ID | | type | ErrTypeEnum | 错误/事件类型，枚举值：'vue-warn'、'vue-error'、'unhandledrejection'、'onerror'、'resource-error'、'test' | | error | Error | 错误对象 | | vmName | string | Vue 组件名 | | info | string | 额外信息 | | message | string | 错误消息 | | stack | string | 错误堆栈 | | url | string | 当前页面地址 | | time | number | 上报时间戳 | | userAgent | string | UA 信息 | | source | string | 错误来源 | | lineno | number | 行号 | | colno | number | 列号 | | reason | any | Promise 拒绝原因 | | tagName | string | 资源标签名 | | src | string | 资源地址 | | resConfig | string | 请求配置，Promise reject 时，可能是 axios 的请求配置 |

ErrTypeEnum 枚举

type 字段为 ErrTypeEnum，可选值如下：

• 'vue-warn' Vue 警告
• 'vue-error' Vue 错误
• 'unhandledrejection' Promise 未捕获异常
• 'onerror' 全局 JS 错误
• 'resource-error' 资源加载错误
• 'test' 测试类型

API 扩展

除了 setup 和 report，还暴露了以下辅助函数，便于自定义集成：

• callWarnHandler(config, error, vm, info)：手动触发 Vue 警告处理和上报。
• callErrorHandler(config, error, vm, info)：手动触发 Vue 错误处理和上报。
• callUnhandledrejection(config, event)：手动处理 Promise 未捕获异常并上报。
• callError(config, event)：手动处理资源加载错误并上报。

这些函数可用于更细粒度的错误监控或自定义场景。

在线用例

https://stackblitz.com/edit/stackblitz-starters-ofnzdvcm?embed=1&file=index.html

功能特性

• Vue 错误与警告监控：自动代理 Vue 的 errorHandler 和 warnHandler。
• 全局 JS 错误监控：自动监听 window.onerror。
• Promise 未捕获异常监控：自动监听 unhandledrejection。
• 静态资源加载错误监控：自动监听 error 事件，捕获图片、脚本、样式等资源加载失败。
• 可配置过滤与转换：支持自定义过滤和数据转换逻辑。
• 支持自定义上报函数：可通过 api 传入自定义上报方法。

测试

本项目使用 Jest 进行单元测试。

运行测试

yarn test
# 或
npm test

测试文件示例

测试文件位于 __tests__/ 目录下，覆盖了 setup 和 report 的主要逻辑。

开发

本地开发

yarn dev

构建

yarn build

依赖

• TypeScript
• Vite
• Jest
• ts-jest

贡献

欢迎提 issue 或 PR！

License

MIT