# wx-error-logger

**Repository Path**: renlong/wx-error-logger

## Basic Information

- **Project Name**: wx-error-logger
- **Description**: wx-error-logger：一个专注于微信小程序错误日志管理的开源项目，提供实时监控、错误收集与分析功能，助力开发者快速定位并解决问题。
- **Primary Language**: JavaScript
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-04-29
- **Last Updated**: 2025-04-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# wx-error-logger

## 项目介绍
wx-error-logger 是一个专注于微信小程序错误日志管理的开源项目，提供实时监控、错误收集与分析功能，助力开发者快速定位并解决问题。

该项目实现了一套完整的错误日志收集与上报机制，具有以下特点：

1. **队列处理**：减少并发请求压力
2. **批量上传**：减少网络请求次数
3. **去重处理**：避免重复错误大量上报
4. **限流处理**：控制上报频率
5. **失败重试**：提高上报成功率
6. **用户活动感知**：避免在用户操作时上传
7. **网络状态感知**：优先在良好网络环境上传
8. **智能调度**：使用空闲时间处理日志
9. **接口故障检测**：自动切换到本地存储模式
10. **可插拔队列**：支持自定义队列实现

## 软件架构

项目主要由以下几部分组成：

- **核心日志处理模块 (utils/error-logger.js)**：负责错误捕获、日志处理和上报
- **队列接口模块 (utils/queue-interface.js)**：定义队列的标准接口
- **默认队列实现 (utils/queue.js)**：提供默认的队列处理实现
- **环境配置模块 (utils/env.js)**：管理环境配置和开关
- **API模块 (api/error-logger.js)**：提供日志上报接口
- **测试模块**：包含错误测试页面和日志查看页面

### 技术架构图

```
┌──────────────┐         ┌───────────────┐         ┌──────────────┐
│   错误捕获    │ ──────→ │   错误处理     │ ──────→ │   日志上报    │
└──────────────┘         └───────────────┘         └──────────────┘
      ↑                         │                        ↓
      │                         ↓                        │
┌──────────────┐         ┌───────────────┐         ┌──────────────┐
│  全局监听     │         │   本地缓存     │         │   网络检测    │
└──────────────┘         └───────────────┘         └──────────────┘
                               ↑
                               │
                        ┌──────────────┐
                        │   队列处理     │
                        └──────────────┘
```

## 安装使用

### 项目依赖

本项目适用于微信小程序项目，无需额外依赖。

### 安装步骤

1. 克隆仓库到本地
   ```bash
   git clone https://github.com/yourusername/wx-error-logger.git
   ```

2. 将 `utils` 和 `api` 文件夹复制到您的小程序项目中

3. 在 `app.js` 中引入并初始化
   ```javascript
   import errorLogger from './utils/error-logger';
   
   App({
     onLaunch() {
       // 初始化错误日志监听
       wx.onUnhandledRejection(({reason}) => {
         errorLogger.log({
           type: 'promise',
           error: reason,
           message: 'Promise未处理的拒绝',
           source: 'global'
         });
       });
     }
   })
   ```

## 使用说明

### 基本用法

1. **记录错误日志**
   ```javascript
   import errorLogger from 'path/to/utils/error-logger';
   
   try {
     // 可能出错的代码
   } catch (error) {
     errorLogger.log({
       type: 'js',  // 错误类型: js, api, network, etc.
       error: error,  // 错误对象
       message: '操作失败',  // 错误消息
       source: 'componentName',  // 错误来源
       extra: { /* 额外信息 */ }  // 可选
     });
   }
   ```

2. **手动刷新日志**
   ```javascript
   errorLogger.flush();
   ```

3. **更新配置**
   ```javascript
   errorLogger.updateConfig({
     maxLogCount: 50,
     flushInterval: 30000
   });
   ```

### 高级配置

错误日志模块支持多种配置项，可根据需求进行自定义：

```javascript
// 自定义配置
errorLogger.updateConfig({
  maxLogCount: 100,        // 最大日志缓存数量
  maxLogsPerSession: 50,   // 每个会话最大日志数
  flushInterval: 60000,    // 日志上传间隔 (ms)
  batchSize: 10,           // 批量上传数量
  maxRetries: 3,           // 最大重试次数
  retryDelay: 5000,        // 重试延迟 (ms)
  deduplicate: true,       // 是否去重
  logLevel: 'error',       // 日志级别 ('debug', 'info', 'warn', 'error')
  // ... 更多配置
});
```

### 自定义队列实现

错误日志模块支持自定义队列实现，可以根据项目需求定制队列处理逻辑：

1. **实现队列接口**

   自定义队列需要实现 `QueueInterface` 接口：

   ```javascript
   import { QueueInterface } from './utils/queue-interface';
   
   class MyCustomQueue extends QueueInterface {
     constructor() {
       super();
       // 初始化队列
     }
     
     // 实现接口方法
     addTask(task, params, hooks) {
       // 添加任务到队列
       return Promise.resolve();
     }
     
     isEmpty() {
       // 检查队列是否为空
       return true;
     }
     
     size() {
       // 获取队列大小
       return 0;
     }
     
     start() {
       // 开始执行队列
     }
     
     lock() {
       // 锁定队列
     }
     
     then(callback) {
       // 添加队列执行完成后的回调
     }
   }
   ```

2. **设置自定义队列**

   ```javascript
   import errorLogger, { setQueueImplementation } from './utils/error-logger';
   import MyCustomQueue from './my-custom-queue';
   
   // 创建自定义队列实例
   const customQueue = new MyCustomQueue();
   
   // 方法1: 使用setQueueImplementation函数
   setQueueImplementation(customQueue);
   
   // 方法2: 通过updateConfig方法设置
   errorLogger.updateConfig({
     // 可选的其他配置...
   }, customQueue);
   ```

## 测试功能

本项目包含错误测试页面 (`pages/error-test/error-test`)，提供以下测试功能：

1. **JS错误测试** - 触发JavaScript错误
2. **Promise错误测试** - 触发Promise拒绝错误
3. **网络错误测试** - 触发网络请求错误
4. **自定义错误测试** - 记录自定义错误信息
5. **日志查看** - 查看已收集的错误日志

## 常见问题

1. **为什么有些错误没有被捕获？**
   - 检查是否正确初始化了全局错误监听
   - 确保错误日志收集开关已开启

2. **如何处理敏感信息？**
   - 在记录错误前，过滤掉可能包含的敏感信息

3. **如何自定义上报接口？**
   - 修改 `api/error-logger.js` 中的上报逻辑

4. **如何根据项目需求定制队列处理逻辑？**
   - 实现 `QueueInterface` 接口，然后使用 `setQueueImplementation` 或 `updateConfig` 设置自定义队列

## 参与贡献

1. Fork 本仓库
2. 新建 Feature_xxx 分支
3. 提交代码
4. 新建 Pull Request

## 许可证

本项目采用 MIT 许可证 - 详见 [LICENSE](LICENSE) 文件