vue-error-monitor

Vue 2 / Vue 3 前端错误监控插件（npm 包）。构建目标包含 IE11 / ES5，同时提供 ESM / CJS / UMD 产物。

安装

npm i vue-error-monitor

快速使用

Vue 3

import { createApp } from 'vue'
import App from './App.vue'
import VueErrorMonitor from 'vue-error-monitor'

const app = createApp(App)
app.use(VueErrorMonitor, {
  report: {
    errorCallback(info) {
      // info: { pageResult, level, msg, errorTime, errorPageUrl, userAgent, errorType, behaviors }
    }
  }
})
app.mount('#app')

Vue 2

import Vue from 'vue'
import VueErrorMonitor from 'vue-error-monitor'

Vue.use(VueErrorMonitor, {
  report: { errorCallback(info) { /* ... */ } }
})

销毁与内存

在单页应用中离开页面或需关闭监控时，请手动销毁并移除监听，避免闭包与队列长期持有引用：

const app = createApp(App)
app.use(VueErrorMonitor, options)
// ...
app.config.globalProperties.$errorMonitor?.destroy()

Vue 2：this.$errorMonitor.destroy()。

销毁时会：移除 window / document 监听、恢复 XHR / fetch（若劫持）、停止白屏定时器、清空行为队列与节流状态，并调用你配置的 destroy 钩子。

配置说明

完整配置示例（覆盖全部参数）

app.use(VueErrorMonitor, {
  enable: true,
  monitors: {
    js: true,
    resource: true,
    promise: true,
    vue: true,
    network: true,
    whiteScreen: true
  },
  levelRules: {
    byType: {
      jsFatal: 'danger',
      whiteScreen: 'danger',
      coreResourceError: 'danger',
      promiseError: 'warning',
      networkCoreError: 'danger',
      networkNonCoreError: 'info',
      jsWarning: 'warning',
      imgError: 'info',
      cssError: 'info',
      htmlError: 'info',
      imgPerfError: 'info',
      resourcePerfError: 'info'
    },
    byKeyword: {
      timeout: 'warning',
      abort: 'warning',
      'Network Error': 'warning',
      'network request failed': 'warning',
      'Script error': 'danger',
      'white screen': 'danger'
    }
  },
  rootSelector: '#app',
  networkIgnoreUrls: [],
  whiteScreen: {
    enable: true,
    checkInterval: 2000,
    maxCheckTimes: 5,
    checkFunction: null,
    ignoreSelectors: ['.skeleton', '.loading', '.el-loading-mask'],
    waitForPaint: true,
    useMutationObserver: true,
    mutationDebounce: 300
  },
  report: {
    start: true,
    errorCallback: function (info) {
      // info: { pageResult, level, msg, errorTime, errorPageUrl, userAgent, errorType, behaviors }
      // 例如：axios.post('/api/log', info)
    }
  },
  behavior: {
    enable: false,
    maxLength: 20,
    types: ['click', 'navigate', 'input'],
    captureInputValue: true,
    sensitiveSelectors: ['input[type="password"]', 'input[type="hidden"]'],
    maxDataAttrs: 10
  },
  created: function (instance) {},
  mounted: function (instance) {},
  destroy: function (instance) {}
})

顶层参数表

| 参数 | 类型 | 默认值 | 必传 | 说明 | |------|------|--------|------|------| | enable | Boolean | true | 否 | 总开关，false 时禁用所有监控。 | | monitors | Object | 见下表 | 否 | 各类型监控开关。 | | levelRules | Object | 见下表 | 否 | 错误等级分配规则。 | | rootSelector | String | '#app' | 否 | 白屏检测根容器。 | | networkCoreUrlPatterns | String[] | 见默认值 | 否 | 核心接口关键字/子串：匹配到这些 URL 的网络错误将作为致命级告警。 | | jsCoreSourceUrlPatterns | String[] | 见默认值 | 否 | 核心脚本来源关键字/子串：用于启发式判断入口脚本错误倾向致命级。 | | networkIgnoreUrls | String[] | [] | 否 | 开启网络监控时，URL 包含任一字串则不上报。 | | whiteScreen | Object | 见下表 | 否 | 白屏检测详细配置。 | | resourcePerf | Object | {imageDurationMs:5000, largeResourceDurationMs:8000} | 否 | 资源性能异常阈值（仅当 monitors.resourcePerf=true 时生效）。 | | report | Object | 见下表 | 否 | 上报控制项。 | | behavior | Object | 见下表 | 否 | 用户行为记录配置。 | | created | Function \| null | null | 否 | 插件创建后、挂载监听前调用。 | | mounted | Function \| null | null | 否 | 所有监听挂载后异步调用。 | | destroy | Function \| null | null | 否 | 调用实例 destroy() 时触发。 |

monitors 参数表

| 参数 | 类型 | 默认值 | 必传 | 说明 | |------|------|--------|------|------| | js | Boolean | true | 否 | JS 运行时错误监控。 | | resource | Boolean | true | 否 | 资源加载错误监控（img/script/css）。 | | resourcePerf | Boolean | false | 否 | 资源性能异常监控（体验级）：图片加载 > 5s / 大资源耗时过长。 | | promise | Boolean | true | 否 | 未捕获 Promise 错误监控。 | | vue | Boolean | true | 否 | Vue 组件错误监控。 | | network | Boolean | true | 否 | XHR/fetch 网络错误监控（核心接口致命级，非核心体验级）。 | | whiteScreen | Boolean | true | 否 | 白屏检测开关。 |

资源监控（monitors.resource=true）会在上报时把 type 细分为 js/img/css/html/png/jpg/jpeg/...，并且只在浏览器能确认该资源请求发生了网络错误（responseStatus >= 400）时上报；如果无法确认则会跳过，避免“HTTP 200 但解码失败”的误报。

levelRules 参数表

| 参数 | 类型 | 默认值 | 必传 | 说明 | |------|------|--------|------|------| | byType | Object | { jsFatal:'danger', whiteScreen:'danger', coreResourceError:'danger', promiseError:'warning', networkCoreError:'danger', networkNonCoreError:'info', jsWarning:'warning', imgError:'info', cssError:'info', htmlError:'info', imgPerfError:'info', resourcePerfError:'info' } | 否 | 按错误类型映射等级（内部统一分类）。 | | byKeyword | Object | { timeout:'warning', abort:'warning', ... } | 否 | 按错误关键字映射等级，优先级高于 byType。 |

whiteScreen 参数表

| 参数 | 类型 | 默认值 | 必传 | 说明 | |------|------|--------|------|------| | enable | Boolean | true | 否 | 白屏检测总开关。 | | checkInterval | Number | 2000 | 否 | 检测间隔（毫秒）。 | | maxCheckTimes | Number | 5 | 否 | 最大检测次数。 | | checkFunction | Function \| null | null | 否 | 自定义白屏判定函数，参数为根节点。 | | ignoreSelectors | String[] | ['.skeleton','.loading','.el-loading-mask'] | 否 | 忽略选择器列表。 | | waitForPaint | Boolean | true | 否 | 首次检测前经 requestAnimationFrame 双帧，给首屏绘制留时间。 | | useMutationObserver | Boolean | true | 否 | 根节点 DOM 变化时防抖触发一次白屏检测（需浏览器支持）。 | | mutationDebounce | Number | 300 | 否 | Mutation 触发白屏检测的防抖毫秒。 |

白屏策略：为减少 Vue 首屏渲染前的误报，插件会延后首次检测，并且忽略第一次“白屏判断”；若后续检测仍持续判定白屏才会触发上报。

report 参数表

| 参数 | 类型 | 默认值 | 必传 | 说明 | |------|------|--------|------|------| | start | Boolean | true | 否 | 是否执行上报回调。 | | errorCallback | Function \| null | null | 否 | 错误回调：收到 pageResult/level/msg/errorTime/errorPageUrl/userAgent/errorType/behaviors。 |

behavior 参数表

| 参数 | 类型 | 默认值 | 必传 | 说明 | |------|------|--------|------|------| | enable | Boolean | false | 否 | 是否记录用户行为。 | | maxLength | Number | 20 | 否 | 行为队列最大长度（FIFO）。 | | types | String[] | ['click','navigate'] | 否 | 记录类型：click（含 selector、params、pagePath 等）、navigate、input。 | | captureInputValue | Boolean | true | 否 | 是否记录输入框值（截断）；false 时 value 恒为 ""。 | | sensitiveSelectors | String[] | ['input[type="password"]','input[type="hidden"]'] | 否 | 匹配到的输入框不记录值（value 为 ""）。 | | maxDataAttrs | Number | 10 | 否 | 点击行为中最多采集的 data-* 个数。 |

开启 behavior 后，每次上报会在 behaviors 中附带用户行为上下文：

• behaviors.behaviorList：近期行为队列（click/input/navigate）。
• behaviors.lastBehavior：最近一次触发行为的 detail（点击会包含 selector/params/pagePath，输入会包含 value/pagePath，取不到或敏感输入为 ""）。

结论：当前版本所有配置项均为非必传，可零配置使用。

reportManually 会不走采样与节流/分钟配额（仍会执行 errorCallback 与 report.start），适合初始化埋点。

构建

npm run build
npm test

产物在 dist/。

许可

MIT