@mxyu/monitor

前端监控 SDK：错误、性能、行为一站式采集，开箱即用。

• 错误监控：JS 运行时错误 / Promise 异常 / 资源加载失败 / 网络请求错误 / Vue & React 框架错误
• 性能监控：页面加载（DNS/TCP/SSL/TTFB） / Core Web Vitals（FP/FCP/LCP/FID/CLS/INP）/ 资源加载 / 长任务
• 行为追踪：PV / 路由变化 / 点击 / 滚动 / 输入 / 表单提交 / 会话管理
• 页面检测：白屏检测 / 崩溃检测（心跳）
• 存储兜底：IndexedDB 持久化 + Web Worker 异步上传 + 内存降级队列 + 指数退避重试

安装

pnpm add @mxyu/monitor
# 或
npm install @mxyu/monitor

SDK 走 monorepo workspace:* 协议，本地开发直接引用；发布时 changeset 会自动转为实际版本号。

快速开始（错误监控）

import { createMonitor } from '@mxyu/monitor';

const monitor = createMonitor({
  appId: 'my-app',                    // 必填：项目标识（用于服务端路由与限流）
  uploadUrl: 'http://localhost:3000/api/v1/report/error',  // 必填：后端错误上报地址
  env: 'production',                  // 可选：环境标识
});

// 设置当前用户（用于错误归因）
monitor.setUser({ id: 'u_123', username: 'alice' });

// 手动上报
monitor.captureError(new Error('Manual captured'));

// 页面卸载时自动用 sendBeacon 兜底发送

重要：uploadUrl 的路径必须是 /api/v1/report/error（不是设计文档的 /api/v1/monitor/error）。 后端实现见 apps/monitor-server/src/routes/report.ts，路由前缀为 /api/v1/report。

Vue 3 接入

import { createApp } from 'vue';
import { createMonitor, createVuePlugin } from '@mxyu/monitor';

const monitor = createMonitor({
  appId: 'vue-app',
  uploadUrl: 'http://localhost:3000/api/v1/report/error',
});

const vuePlugin = createVuePlugin(monitor);

const app = createApp(App);
app.use(vuePlugin);  // 自动捕获 Vue 组件错误（errorHandler 钩子）
app.mount('#app');

React 接入

import { createMonitor, createReactPlugin } from '@mxyu/monitor';

const monitor = createMonitor({
  appId: 'react-app',
  uploadUrl: 'http://localhost:3000/api/v1/report/error',
});

const reactPlugin = createReactPlugin();
reactPlugin.install(monitor);

// 在 ErrorBoundary 的 componentDidCatch 中调用
const api = reactPlugin.getApi(monitor);
api.captureError(error, { componentStack: errorInfo.componentStack });

配置项

| 选项 | 类型 | 默认值 | 说明 | |---|---|---|---| | appId | string | 必填 | 项目标识，用于服务端路由 | | uploadUrl | string | 必填 | 错误上报 URL（见下方路由说明） | | env | string | - | 环境标识（production/staging/development） | | user | UserInfo | - | 初始用户信息 | | tags | Record<string, string> | - | 自定义标签 | | uploadInterval | number | 30000 | 上传间隔（ms） | | batchThreshold | number | 10 | 批量上传阈值 | | enableWorker | boolean | true | 是否启用 Web Worker 异步处理 | | captureResource | boolean | true | 捕获资源加载错误 | | captureNetwork | boolean | true | 拦截 fetch / XHR 网络错误 | | captureConsole | boolean | false | 捕获 console.error | | enableDedupe | boolean | true | 启用错误去重（5 秒窗口） | | dedupeWindow | number | 5000 | 去重时间窗口（ms） | | beforeUpload | (errors) => ErrorEvent[] \| false | - | 上传前钩子，返回 false 取消上传 |

性能监控（独立模块）

性能监控与错误监控解耦，需要单独初始化：

import { createPerformanceMonitor } from '@mxyu/monitor';

const performance = createPerformanceMonitor(
  {
    appId: 'my-app',
    uploadUrl: 'http://localhost:3000/api/v1/report/performance',
    enableLoadMetrics: true,    // 页面加载指标
    enableWebVitals: true,      // Core Web Vitals
    enableResourceMetrics: true, // 资源加载
    enableLongTask: true,       // 长任务（>50ms）
    longTaskThreshold: 50,
    performanceUploadInterval: 60000,
    resourceBatchThreshold: 20,
  },
  (event) => {
    // 实时回调（可选，用于自定义处理）
    console.log('Performance event:', event);
  },
);

行为追踪（独立模块）

import { createBehaviorTracker, createSessionManager } from '@mxyu/monitor';

const session = createSessionManager();
const tracker = createBehaviorTracker({
  sessionId: session.getSessionId(),
  uploadUrl: 'http://localhost:3000/api/v1/report/behavior',
});

tracker.start();  // 自动监听点击、滚动、路由变化等

上报数据格式

SDK 上报到 /api/v1/report/error 的批量格式：

{
  "appId": "my-app",
  "env": "production",
  "pageUrl": "https://example.com/page",
  "userAgent": "...",
  "events": [
    {
      "type": "jsError",
      "level": "error",
      "message": "Cannot read property 'x' of undefined",
      "stack": "...",
      "timestamp": 1718700000000,
      "filename": "app.js",
      "lineno": 42,
      "colno": 15
    }
  ],
  "timestamp": 1718700000000
}

路由前缀说明（重要）

| 数据类型 | SDK uploadUrl | 后端实现 | |---|---|---| | 错误上报 | /api/v1/report/error | apps/monitor-server/src/routes/report.ts | | 批量错误 | /api/v1/report/errors | 同上 | | 性能上报 | /api/v1/report/performance | 同上 | | 行为上报 | /api/v1/report/behavior | 同上 | | 综合上报 | /api/v1/report/batch | 同上 | | 健康检查 | /api/v1/health | routes/health.ts |

后端默认端口 3000，可通过 PORT 环境变量修改（见 .env.example）。 路由前缀实现为 /api/v1/report/*，与设计文档的 /api/v1/monitor/* 不同—— 实现已稳定且合理，未为对齐文档而调整；接入时以本表为准。

上报失败重试

SDK 内置指数退避重试：

• 失败 1 次：1 秒后重试
• 失败 2 次：2 秒后重试
• 失败 3 次：4 秒后重试
• 失败 4 次：8 秒后重试
• 失败 5 次：16 秒后重试
• 超过 5 次：丢弃数据（避免队列无限增长）

页面卸载时使用 navigator.sendBeacon 兜底发送，确保数据不丢失。

后端部署

见仓库根 docker-compose.yml 与 scripts/init-db.sh：

cp .env.example .env
docker compose up -d            # 起 MySQL + Redis + ES + ClickHouse + Server
bash scripts/init-db.sh         # 建表
# Server 起在 http://localhost:3000

API 类型定义

详细类型见 src/types/：

• types/index.ts：核心类型入口
• types/performance.ts：性能事件类型
• types/behavior.ts：行为事件类型
• types/detection.ts：检测事件类型
• types/storage.ts：存储类型

License

MIT