web-monitoring-sdk-vue

可复用的前端监控 SDK（Vue3 + Vue Router 场景），支持：

• 前端异常监控（front_page_error）
• API 性能监控（front_api_performance）
• Web Vitals（front_web_vitals_performance）
• 路由性能（front_page_route）
• 页面停留（front_page_stay）
• 点击行为（front_behavior_click）

安装

pnpm add web-monitoring-sdk-vue

快速使用

import { initAllMonitoring } from 'web-monitoring-sdk-vue'

await initAllMonitoring({
  app,
  router,
  reportApiConfig: {
    reportUrl: 'https://example.com/monitor/report',
    platform: 'merchant',
    tokenProvider: () => getToken(),
    transport: 'auto'
  }
})

业务侧初始化

建议在业务项目中封装一层 setupMonitoring，统一处理环境变量、菜单/用户数据适配、事件映射。

// src/config/monitoring/setupMonitoring.ts
import type { App } from 'vue'
import type { Router } from 'vue-router'
import { initAllMonitoring, type MonitoringConfig } from 'web-monitoring-sdk-vue'
import { getMonitoringMenuTree, getMonitoringUserInfo } from './merchantAdapter'
import {
  merchantActionKeyMap,
  merchantActionNameMap,
  merchantMenuRouteEventKeyMap
} from './merchantEventMap'

const DEFAULT_REPORT_TYPE_FLAGS = {
  front_page_error: true,
  front_behavior_click: true,
  front_api_performance: true,
  front_page_route: true,
  front_page_stay: true,
  front_web_vitals_performance: true
}

function resolveEnvBoolean(rawValue: unknown, fallback: boolean): boolean {
  if (typeof rawValue === 'boolean') return rawValue
  if (typeof rawValue !== 'string') return fallback

  const normalized = rawValue.trim().toLowerCase()
  if (['1', 'true', 'yes', 'on'].includes(normalized)) return true
  if (['0', 'false', 'no', 'off'].includes(normalized)) return false
  return fallback
}

function getReportTypeFlags() {
  return {
    front_page_error: resolveEnvBoolean(import.meta.env.VITE_MONITOR_REPORT_ERROR, DEFAULT_REPORT_TYPE_FLAGS.front_page_error ?? false),
    front_behavior_click: resolveEnvBoolean(import.meta.env.VITE_MONITOR_REPORT_BEHAVIOR, DEFAULT_REPORT_TYPE_FLAGS.front_behavior_click ?? false),
    front_api_performance: resolveEnvBoolean(import.meta.env.VITE_MONITOR_REPORT_PERFORMANCE_API, DEFAULT_REPORT_TYPE_FLAGS.front_api_performance ?? false),
    front_page_route: resolveEnvBoolean(import.meta.env.VITE_MONITOR_REPORT_PERFORMANCE_ROUTE, DEFAULT_REPORT_TYPE_FLAGS.front_page_route ?? false),
    front_page_stay: resolveEnvBoolean(import.meta.env.VITE_MONITOR_REPORT_PERFORMANCE_PAGE_STAY, DEFAULT_REPORT_TYPE_FLAGS.front_page_stay ?? false),
    front_web_vitals_performance: resolveEnvBoolean(import.meta.env.VITE_MONITOR_REPORT_PERFORMANCE_WEB_VITALS, DEFAULT_REPORT_TYPE_FLAGS.front_web_vitals_performance ?? false)
  }
}

function createMonitoringConfig(app: App, router: Router): MonitoringConfig {
  return {
    app,
    router,
    menuConfig: {
      menuDataProvider: getMonitoringMenuTree
    },
    userConfig: {
      userDataProvider: getMonitoringUserInfo
    },
    reportConfig: getReportTypeFlags(),
    reportApiConfig: {
      reportUrl: `${import.meta.env.VITE_BASE_URL}${import.meta.env.VITE_API_URL}${import.meta.env.VITE_MONITOR_REPORT_API}`,
      platform: '管理平台',
      tokenKey: 'ACCESS_TOKEN',
      tokenPrefix: 'Bearer'
    },
    mappingConfig: {
      actionNameMap: merchantActionNameMap,
      actionKeyMap: merchantActionKeyMap,
      menuRouteEventKeyMap: merchantMenuRouteEventKeyMap
    },
    debug: true
  }
}

export async function setupMonitoring(app: App, router: Router): Promise<void> {
  await initAllMonitoring(createMonitoringConfig(app, router))
}

// src/main.ts
import router from './router'
import { setupMonitoring } from './config/monitoring/setupMonitoring'

async function setupAll() {
  // ... 你的其他初始化逻辑
  await router.isReady()
  await setupMonitoring(app, router)
  app.mount('#app')
}

要点：

• 在 router.isReady() 后再初始化监控，避免首个页面会话路由信息不完整。
• menuDataProvider / userDataProvider 由业务项目注入，SDK 不耦合业务 API。
• mappingConfig 建议由业务侧维护，便于不同项目复用同一套 SDK。

构建

pnpm install
pnpm build

目录说明

• src/：SDK 源码
• src/docs/：使用与字段文档（不参与构建输出）
• dist/：构建产物（发布目录）