@cmjndy/monitor

轻量前端监控 SDK，提供性能采集、错误监控、行为埋点三类能力，面向多项目接入，不含业务逻辑。

安装

npm install @cmjndy/monitor

web-vitals 作为 SDK 的内部依赖，随 SDK 一起安装，无需额外操作。

快速开始

在应用入口文件（main.tsx / index.tsx）的第一行调用 init，确保在 React Router 等路由库实例化之前完成初始化：

import { init } from '@cmjndy/monitor'

init({
  appKey: 'your-app-name',
  reportUrl: '/monitor/collect',
  env: 'production',
  debug: false,
})

API

init(config)

初始化 SDK，全局调用一次。

参数	类型	必填	说明
appKey	string	✅	应用唯一标识，用于区分不同项目的数据
reportUrl	string	✅	上报接口地址，支持同域相对路径或完整 URL
env	'development' | 'staging' | 'production'	—	控制是否上报。development 不上报（仅 debug 打印），其余正常上报。默认视为 production
debug	boolean	—	开启后每条事件在 console 打印，方便本地验证。默认 false

env 与 reportUrl 的职责分工：env 只控制"要不要上报"，环境间的数据隔离由 reportUrl 指向不同的后端实例来保证，SDK 本身不感知环境差异。

---

trackError(error, extraProps?)

手动上报错误，补充自动捕获覆盖不到的场景。

import { trackError } from '@cmjndy/monitor'

参数	类型	说明
error	Error | string	Error 实例或错误描述字符串
extraProps	Record<string, unknown>	附加信息，merge 到上报数据的 props 字段

典型用法：

// React ErrorBoundary
componentDidCatch(error: Error, info: React.ErrorInfo) {
  trackError(error, { componentStack: info.componentStack })
}

// axios 响应拦截器（携带 traceId 关联后端日志）
instance.interceptors.response.use(
  (res) => res,
  (error) => {
    const traceId = error.config?.metadata?.traceId
    trackError(error, { traceId, url: error.config?.url, status: error.response?.status })
    return Promise.reject(error)
  }
)

注意：trackError 不去重——业务层已做 try/catch，不会循环触发，且不同调用点的 extraProps 各不相同，去重会丢数据。

---

trackEvent(eventName, props?)

手动上报自定义行为事件。

import { trackEvent } from '@cmjndy/monitor'

参数	类型	说明
eventName	string	事件名称，建议使用 snake_case
props	Record<string, unknown>	事件附加属性，SDK 不做约束

// 按钮点击
trackEvent('button_click', { buttonId: 'submit', page: 'checkout' })

// 搜索行为
trackEvent('search', { keyword: '耳机', resultCount: 42 })

---

自动采集能力

初始化后以下能力自动开启，无需额外代码：

能力	说明
性能指标	FCP / LCP / CLS / TTFB / INP（基于 web-vitals）
JS 错误	window.onerror 捕获的未处理运行时错误
Promise 异常	unhandledrejection 捕获的未处理 Promise 失败
资源加载错误	图片 / 脚本 / 样式 404 等加载失败
PV 上报	首次加载 + SPA 路由切换（pushState / replaceState / popstate）全量覆盖

自动捕获的盲区（需手动调用 trackError）：

• React ErrorBoundary 捕获的渲染错误
• axios / fetch 拦截器消化的接口错误
• 业务 try/catch 内处理的错误

---

接入示例

// src/utils/monitor.ts（业务项目的薄封装）
import { init, trackError, trackEvent } from '@cmjndy/monitor'
import type { MonitorEnv } from '@cmjndy/monitor'

declare const __DEPLOY_ENV__: string

const ENV_MAP: Record<string, MonitorEnv> = {
  dev:        'development',
  test:       'staging',
  production: 'production',
}

const REPORT_URL_MAP: Record<string, string> = {
  test:       '/monitor/collect',
  production: '/monitor/collect',
}

export function initMonitor() {
  init({
    appKey: 'your-app-name',
    env: ENV_MAP[__DEPLOY_ENV__] ?? 'development',
    reportUrl: REPORT_URL_MAP[__DEPLOY_ENV__] ?? '',
    debug: __DEPLOY_ENV__ === 'dev',
  })
}

export { trackError, trackEvent }

// src/main.tsx
import { initMonitor } from '@/utils/monitor'

initMonitor()  // 必须在第一行，早于路由库实例化

ReactDOM.createRoot(document.getElementById('root')!).render(<App />)

---

数据结构

每条上报事件的结构：

interface MonitorEvent {
  appKey: string                                          // 来源应用
  type: 'perf' | 'error' | 'track' | 'blank_screen'     // 事件类型
  name: string                                           // 指标名
  value?: number                                         // 数值（性能指标）
  props?: Record<string, unknown>                        // 附加信息
  url: string                                            // 当前页面 URL
  ua: string                                             // UserAgent
  timestamp: number                                      // 上报时间 unix ms
}