uniapp-error-monitor

🔍 UniApp 专业错误监控和上报工具 - 支持全平台、多场景错误捕获

✨ 核心特性

• 🎯 零配置使用: 开箱即用，支持多种导入方式
• 🔍 全面错误捕获: 全局错误、Promise错误、控制台错误、网络错误、小程序错误
• 🧠 环境智能: 自动检测生产环境，非生产环境优雅降级
• ⚡ 高性能: 异步发送错误，不阻塞主线程
• 🔄 重试机制: 网络失败自动重试，可配置次数和间隔
• 📊 错误统计: 内置统计功能，便于数据分析
• 🔧 高度可定制: 支持自定义发送器和格式化函数
• 📱 全平台支持: H5、微信小程序、App、支付宝小程序等
• 🛡️ 类型安全: 完整的 TypeScript 类型定义
• 📦 多格式输出: 支持 ESM、CommonJS、UMD 格式

📦 安装

# npm
npm install uniapp-error-monitor

# yarn
yarn add uniapp-error-monitor

# pnpm
pnpm add uniapp-error-monitor

🚀 快速开始

方式一：命名导出（推荐）

import { initErrorMonitor, reportError, getErrorStats, wrapPromise } from 'uniapp-error-monitor'

// 初始化错误监控
initErrorMonitor({
  webhookUrl: 'https://your-webhook-url.com', // 必填
  enableGlobalError: true,       // 启用全局错误捕获
  enablePromiseError: true,      // 启用 Promise 错误捕获
  enableConsoleError: false,     // 禁用 console.error 捕获
})

// 手动上报错误
reportError('manual', new Error('自定义错误'), {
  page: 'index',
  action: '用户操作失败'
})

// Promise 包装（自动捕获 Promise 错误）
const result = await wrapPromise(
  fetch('https://api.example.com/data')
)

// 获取错误统计
const stats = getErrorStats()
console.log('错误统计:', stats)

方式二：类实例（高级用法）

import { ErrorMonitor } from 'uniapp-error-monitor'

// 创建自定义实例
const errorMonitor = new ErrorMonitor()

// 设置自定义发送器
errorMonitor.setSender(async (errorInfo) => {
  // 发送到自己的服务器
  await fetch('/api/errors', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(errorInfo)
  })
})

// 设置自定义格式化函数
errorMonitor.setFormatter((errorInfo) => {
  return `🔴 错误详情：
  类型：${errorInfo.type}
  消息：${errorInfo.error}
  页面：${errorInfo.page}
  时间：${new Date(errorInfo.timestamp).toLocaleString()}`
})

// 初始化
errorMonitor.initErrorMonitor({
  webhookUrl: 'your-webhook-url'
})

// 使用实例方法
errorMonitor.reportError('api', new Error('接口调用失败'))

方式三：默认实例（向后兼容）

import ErrorMonitor from 'uniapp-error-monitor'

// 使用默认实例
ErrorMonitor.initErrorMonitor({
  webhookUrl: 'https://your-webhook-url.com'
})

ErrorMonitor.reportError('manual', new Error('测试错误'))

⚙️ 配置选项

interface ErrorMonitorOptions {
  // 基础配置
  webhookUrl?: string           // Webhook 地址（可选，使用环境变量）
  enableGlobalError?: boolean   // 启用全局错误捕获（默认：true）
  enablePromiseError?: boolean  // 启用 Promise 错误捕获（默认：true）
  enableConsoleError?: boolean  // 启用 console.error 捕获（默认：false）
  
  // 重试配置
  maxRetries?: number           // 最大重试次数（默认：3）
  retryDelay?: number           // 重试延迟时间(ms)（默认：1000）
  
  // 高级配置
  forceEnable?: boolean         // 强制启用错误监控（忽略环境检查）
  sender?: (errorInfo: ErrorInfo) => Promise<void>  // 自定义发送器
  formatter?: (errorInfo: ErrorInfo) => string      // 自定义格式化函数
}

📊 错误类型

类型	说明	自动捕获	手动上报	触发场景
global	全局 JavaScript 错误	✅	❌	window.onerror
promise	Promise 拒绝错误	✅	❌	unhandledrejection
console	console.error 输出	✅	❌	启用后自动捕获
miniProgram	小程序特定错误	✅	❌	uni.onError, uni.onPageNotFound
network	网络请求失败	✅	❌	拦截的 uni.request 失败
api	API 接口错误	❌	✅	手动调用 reportError
manual	手动上报错误	❌	✅	手动调用 reportError

🔧 高级用法

环境检测

import { getEnvironmentInfo } from 'uniapp-error-monitor'

const envInfo = getEnvironmentInfo()

if (envInfo.isProduction) {
  console.log('生产环境，错误监控已启用')
} else {
  console.log('开发环境，错误监控已禁用')
}

重置统计

import { resetErrorStats } from 'uniapp-error-monitor'

// 重置错误统计（在页面刷新或特定事件后）
resetErrorStats()
console.log('错误统计已重置')

丰富的错误上下文

reportError('global', new Error('页面崩溃'), {
  // 用户信息
  userId: 'user123',
  userAgent: navigator.userAgent,
  
  // 页面信息
  currentPage: getCurrentPageName(),
  routeParams: getCurrentPage()?.$page?.fullPath,
  
  // 业务信息
  action: '用户点击按钮',
  component: 'UserProfile',
  
  // 性能信息
  loadTime: performance.now(),
  memoryUsage: performance.memory?.usedJSHeapSize,
  
  // 自定义数据
  customData: {
    sessionId: getSessionId(),
    feature: 'user_management'
  }
})

批量错误处理

// 定时检查错误状态
setInterval(() => {
  const stats = getErrorStats()
  if (stats.total > 10) {
    console.warn('检测到大量错误:', stats)
    // 可以发送告警或执行其他处理逻辑
  }
}, 60000) // 每分钟检查一次

🛡️ TypeScript 支持

完整的类型安全支持：

import type { 
  ErrorMonitorOptions, 
  ErrorType, 
  ErrorStats,
  EnvironmentInfo,
  ErrorInfo 
} from 'uniapp-error-monitor'

// 类型安全的配置
const options: ErrorMonitorOptions = {
  webhookUrl: 'https://example.com/webhook',
  enableGlobalError: true,
  enablePromiseError: true,
  maxRetries: 5,
  retryDelay: 2000,
}

// 类型安全的错误上报
const reportTypeSafeError = (type: ErrorType, message: string) => {
  reportError(type, new Error(message), {
    timestamp: Date.now(),
    userId: '12345'
  })
}

📱 平台兼容性

• ✅ 微信小程序: 完整支持，包括所有错误类型
• ✅ H5: 完整支持，支持所有现代浏览器
• ✅ App (iOS/Android): 完整支持
• ✅ 支付宝小程序: 基本支持
• ✅ 字节跳动小程序: 基本支持
• ✅ 百度小程序: 基本支持
• ✅ 快应用: 基本支持

🏗️ 环境配置

环境变量

在你的项目中设置环境变量：

# .env 文件
VITE_WEBHOOK=https://your-webhook-url.com

环境检测逻辑

插件会在以下情况下自动禁用（非生产环境）：

• 开发模式 (import.meta.env.MODE === 'development')
• 小程序体验版、开发版、预览版
• 非 UniApp 环境

如需强制启用，设置 forceEnable: true。

📦 构建产物

构建后会在 dist/ 目录生成：

• index.js - CommonJS 格式（Node.js）
• index.esm.js - ES Module 格式（现代构建工具）
• index.umd.js - UMD 格式（浏览器直接使用）
• index.umd.min.js - UMD 压缩版
• index.d.ts - TypeScript 类型声明
• *.map - Source map 文件

🔧 开发调试

# 克隆项目
git clone https://github.com/your-username/uniapp-error-monitor.git
cd uniapp-error-monitor

# 安装依赖
npm install

# 开发调试
npm run dev

# 类型检查
npm run type-check

# 代码检查
npm run lint

# 构建
npm run build

# 发布
npm publish

📄 使用示例

完整的使用示例请参考 USAGE_EXAMPLES.js 文件。

🤝 贡献指南

欢迎提交 Issue 和 Pull Request！

📄 许可证

MIT License - 详见 LICENSE 文件