geca_monitor-nuxt

Nuxt 前端性能与异常监控 SDK（兑容 Nuxt 3 / Nuxt 4）

🚀 快速开始

安装

npm install geca_monitor-nuxt
# 或
pnpm add geca_monitor-nuxt

基础使用

**第一步：**在 nuxt.config.ts 中配置 runtimeConfig.public.monitor

export default defineNuxtConfig({
  runtimeConfig: {
    public: {
      monitor: {
        appId: 'your-app-id',
        env: 'production',
        reportUrl: 'https://your-report-endpoint.com/api/report',
        slowThreshold: 1000,
      }
    }
  }
})

**第二步：**新建 plugins/monitor.client.ts

import { createNuxtMonitor } from 'geca_monitor-nuxt'

export default defineNuxtPlugin((nuxtApp) => {
  const config = useRuntimeConfig()
  const monitor = createNuxtMonitor(config.public.monitor as any)

  return {
    provide: { monitor }
  }
})

配置选项

interface NuxtMonitorConfig {
  // 必填
  appId: string
  
  // 环境 (默认 'production')
  env?: 'development' | 'test' | 'staging' | 'production'
  
  // 慢接口阈值 (默认 1000ms)
  slowThreshold?: number
  
  // 功能开关
  enablePerformance?: boolean    // 性能监控
  enableErrorTracking?: boolean  // 错误追踪
  enableRouteTracking?: boolean  // 路由追踪
  enableApiIntercept?: boolean   // API 拦截
  
  // 上报配置
  reportUrl?: string            // 上报地址
  reportInterval?: number       // 上报间隔 (ms)
  maxBatchSize?: number         // 批量上报最大条数
  
  // 过滤配置
  ignoreErrors?: string[]       // 忽略的错误
  ignoreUrls?: string[]         // 忽略的 URL
}

📊 功能特性

1. 自动监控

• ✅ 页面性能指标 (FCP, LCP, FID, CLS)
• ✅ Vue 错误捕获
• ✅ 全局错误监听
• ✅ Promise 未捕获错误
• ✅ 路由变化追踪
• ✅ API 请求拦截

2. 手动上报

import { useMonitor } from 'geca_monitor-nuxt'

const { reportError, reportMetric } = useMonitor()

// 上报错误
reportError({
  type: 'custom',
  message: 'Custom error message',
  stack: new Error().stack,
})

// 上报指标
reportMetric({
  url: '/api/data',
  method: 'GET',
  duration: 200,
  status: 200,
})

3. 用户行为追踪

// 追踪用户点击
trackClick(element, {
  category: 'button',
  action: 'submit',
  label: 'checkout',
})

// 追踪页面停留
trackPageStay({
  duration: 30000,
  scrollDepth: 80,
})

🔧 Nuxt.js 4.0 特性

• ✅ 支持 Nuxt 4 新架构
• ✅ 自动注册插件
• ✅ TypeScript 支持
• ✅ SSR/SSG 兼容
• ✅ 服务端渲染优化

📁 文件结构

sdk-nuxt/
├── src/
│   ├── index.ts              # 主入口
│   ├── monitor.ts            # 监控核心
│   ├── collectors/
│   │   ├── performance.ts    # 性能收集器
│   │   ├── error.ts          # 错误收集器
│   │   ├── route.ts          # 路由收集器
│   │   └── api.ts            # API 拦截器
│   ├── reporter/
│   │   └── index.ts          # 数据上报器
│   └── types.ts              # 类型定义
├── package.json
└── README.md

📖 完整文档

查看 docs/USAGE.md 获取详细使用文档。

📄 许可证

MIT