easemob-uniapp-logger-plugin 1.4.4

package/CHANGELOG.md

@@ -0,0 +1,110 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.4.2] - 2026-03-11
+
+### Changed
+
+- **安全更新**：从 README 中移除 CMD 自动上传机制的说明
+  - 功能代码保留，仅文档中不再暴露
+  - 防止机制被滥用获取终端日志
+  - 文档仅展示自定义服务器上传方式
+
+## [1.4.1] - 2026-03-11
+
+### Changed
+
+- **精简 README.md**：
+  - 淡化 CMD 自动上传的详细描述
+  - 精简为两种主要上传方式：
+    1. 服务端触发自动上传（简要说明）
+    2. 自定义服务器上传（详细示例）
+  - 删除冗长的多方案说明
+  - 保留核心 API 文档和示例
+
+## [1.4.0] - 2026-03-11
+
+### Added
+
+- **上传失败记录错误日志**：上传或上报失败时自动记录错误到本地日志
+  - 包含错误消息、平台信息、时间戳等
+  - 方便后续排查上传问题
+  - 使用 `isInUploadProcess` 标志位防止重复上传
+
+### Changed
+
+- 优化 `handleCmdMessage` 错误处理，避免重复记录错误
+- 拆分 `upload` 方法为 `upload`（包装）和 `doUpload`（实际逻辑）
+
+## [1.3.0] - 2026-03-11
+
+### Added
+
+- **日志原地滚动**：当文件超过 `maxFileSize` 时自动清空重写
+  - 永远只保留一个文件，上传逻辑简单
+  - 适合 IM 场景，只关心最近日志
+  - AppStorage 使用 `truncate(0)` 清空
+  - WechatMPStorage 使用 `writeFile` 覆盖
+
+## [1.2.0] - 2026-03-11
+
+### Added
+
+- **上传超时配置**：新增 `uploadTimeout` 配置项，默认 30 秒
+- **过期日志清理**：启动时自动清理超过 `expireDays` 的日志文件
+- **微信小程序异步化**：全面使用异步文件 API，避免阻塞主线程
+- **延迟格式化**：日志对象在 flush 时才格式化，减少频繁 CPU 操作
+
+### Changed
+
+- **存储接口重构**：`IStorage.append()` 现在接受 `LogEntry[]` 而非格式化后的字符串
+- **AppStorage 优化**：支持目录遍历和文件时间戳读取
+- **WechatMPStorage 优化**：所有文件操作改为异步 Promise 风格
+
+## [1.1.0] - 2026-03-11
+
+### Added
+
+- **日志时间戳**：为所有日志条目添加标准时间戳格式 `[YYYY-MM-DD HH:mm:ss.SSS]`
+- **UMD 格式支持**：构建产物现在包含 UMD 格式 (`easemob-uniapp-logger.js`)，支持 script 标签引入
+- **CMD 自动上传**：支持通过服务端 CMD 消息 (`action: "em_upload_log"`) 触发自动上传
+- **SDK 日志桥接**：新增 `handleSDKLog()` 方法，支持接入环信 SDK 内部日志
+- **详细集成文档**：新增完整的集成指南和多种上传方案说明
+
+### Fixed
+
+- **appKey 脱敏问题**：修复上报时使用脱敏 appKey 导致服务端无法查询日志的问题，现在使用原始 appKey
+- **Flush 机制**：优化 CMD 触发上传时的 flush 逻辑，确保缓存日志完整写入后再压缩上传
+- **文件不存在错误**：在压缩前添加 `ensureFileExists()` 检查，避免空文件错误
+
+### Changed
+
+- **构建流程**：新增 `build:copy` 脚本，自动生成 `easemob-uniapp-logger.esm.js`
+- **类型导出**：从 `logger.ts` 直接导出 `SDKLogData` 和 `SDKMessage` 类型
+- **API 兼容性**：支持 `apiUrl`、`api_url`、`restUrl` 多种字段名获取 API 地址
+
+## [1.0.0] - 2025-XX-XX
+
+### Added
+
+- 初始版本发布
+- 基础日志功能（DEBUG、INFO、WARN、ERROR、FATAL）
+- 多平台存储支持（App - plus.io、微信小程序、内存存储）
+- 日志压缩功能（App 平台）
+- 自定义上传配置（URL、Handler）
+- 环信服务器上传集成
+- TypeScript 类型支持
+
+---
+
+[1.4.2]: https://github.com/Easemob-Community/easemob-uniapp-logger-plugin/compare/v1.4.1...v1.4.2
+[1.4.1]: https://github.com/Easemob-Community/easemob-uniapp-logger-plugin/compare/v1.4.0...v1.4.1
+[1.4.0]: https://github.com/Easemob-Community/easemob-uniapp-logger-plugin/compare/v1.3.0...v1.4.0
+[1.3.0]: https://github.com/Easemob-Community/easemob-uniapp-logger-plugin/compare/v1.2.0...v1.3.0
+[1.2.0]: https://github.com/Easemob-Community/easemob-uniapp-logger-plugin/compare/v1.1.0...v1.2.0
+[1.1.0]: https://github.com/Easemob-Community/easemob-uniapp-logger-plugin/compare/v1.0.0...v1.1.0
+[1.0.0]: https://github.com/Easemob-Community/easemob-uniapp-logger-plugin/releases/tag/v1.0.0

package/README.md

@@ -0,0 +1,283 @@
+# easemob-uniapp-logger-plugin
+
+一个适用于 uni-app 应用的高性能日志收集工具类库，支持日志本地存储和上传到自定义服务器。
+
+## 特性
+
+- 📱 **多平台支持**：兼容 iOS、Android (App平台) 和 微信小程序
+- 📝 **日志级别**：支持 DEBUG、INFO、WARN、ERROR、FATAL 级别
+- 💾 **文件存储**：App平台使用 plus.io 文件系统，小程序使用本地文件系统
+- 🗜️ **日志压缩**：支持将日志文件压缩为 zip (App平台)
+- ☁️ **上传灵活**：支持自定义服务器上传
+- ⚙️ **延迟写入**：批量写入机制，减少 IO 操作
+
+## 安装
+
+```bash
+npm install easemob-uniapp-logger-plugin
+```
+
+或直接将 `dist/easemob-uniapp-logger.esm.js` 复制到你的项目的 `js_sdk` 目录下。
+
+## 快速开始
+
+### 基础用法
+
+```javascript
+//实际SDK
+import websdk from '../js_sdk/Easemob-chat'
+import {
+  logger
+} from '../js_sdk/easemob-uniapp-logger.esm.js'
+
+// 创建 SDK 实例
+const EMClient = new websdk.connection({
+  appKey: 'YOUR_APPKEY#YOUR_ORG',
+  url:'wss://im-api-wechat.easemob.com/websocket',
+  apiUrl:'https://a1.easemob.com'
+})
+console.log('>>>>>SDK version', EMClient.version)
+logger.init({
+  conn: EMClient
+});
+
+websdk.logger.onLog = (data) => {
+  console.log('>>>>>SDK输出的日志', data)
+  logger.handleSDKLog(data);
+}
+```
+
+---
+
+## 上传到自定义服务器
+
+```javascript
+import { logger } from 'easemob-uniapp-logger-plugin';
+
+logger.init({
+  customUpload: {
+    handler: async (logContent) => {
+      const deviceInfo = uni.getSystemInfoSync();
+      
+      // 上传到你的服务器
+      const res = await uni.request({
+        url: 'https://your-server.com/api/logs/upload',
+        method: 'POST',
+        header: {
+          'Content-Type': 'application/json',
+          'Authorization': 'Bearer your-api-token'
+        },
+        data: {
+          logs: logContent,
+          deviceInfo: {
+            brand: deviceInfo.brand,
+            model: deviceInfo.model,
+            system: deviceInfo.system,
+            platform: deviceInfo.platform,
+          },
+          timestamp: Date.now(),
+        }
+      });
+      
+      if (res.statusCode !== 200) {
+        throw new Error('上传失败: ' + res.statusCode);
+      }
+    }
+  }
+});
+
+// 在合适的时机调用上传
+await logger.upload();
+```
+
+---
+
+## 完整示例
+
+### 在 App.vue 中使用
+
+```vue
+<script>
+import { logger } from 'easemob-uniapp-logger-plugin';
+import { conn } from '@/utils/websdk'; // 你的 SDK 实例
+
+export default {
+  globalData: { logger },
+  
+  onLaunch() {
+    // 初始化 logger（传入 conn 以使用环信上传功能）
+    logger.init({ conn });
+    
+    // 桥接 SDK 日志
+    websdk.logger.onLog = (data) => {
+      logger.handleSDKLog(data);
+    };
+    
+    logger.info('App launched');
+  },
+  
+  onError(err) {
+    logger.error('App error', err);
+  }
+}
+</script>
+```
+
+### 反馈页面上传日志
+
+```vue
+<template>
+  <view class="feedback-page">
+    <textarea v-model="content" placeholder="请输入反馈内容" />
+    <button @click="submitFeedback">提交反馈并上传日志</button>
+  </view>
+</template>
+
+<script>
+import { logger } from 'easemob-uniapp-logger-plugin';
+
+export default {
+  data() {
+    return { content: '' };
+  },
+  methods: {
+    async submitFeedback() {
+      try {
+        uni.showLoading({ title: '上传中...' });
+        logger.info('用户反馈', { content: this.content });
+        await logger.upload();
+        uni.showToast({ title: '提交成功', icon: 'success' });
+      } catch (err) {
+        uni.showToast({ title: '上传失败', icon: 'none' });
+      }
+    }
+  }
+}
+</script>
+```
+
+---
+
+## API 文档
+
+### 初始化
+
+```typescript
+logger.init(options?: LoggerOptions): void
+```
+
+**LoggerOptions:**
+
+| 属性 | 类型 | 描述 |
+|------|------|------|
+| `log` | `Partial<LoggerConfig>` | 日志配置 |
+| `customUpload` | `CustomUploadConfig` | 自定义上传配置 |
+
+**LoggerConfig:**
+
+| 属性 | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `expireDays` | `number` | `7` | 日志文件过期天数 |
+| `maxFileSize` | `number` | `2097152` (2MB) | 单个文件最大大小 |
+| `uploadTimeout` | `number` | `30000` | 上传超时时间(ms) |
+
+### 记录日志
+
+```typescript
+logger.debug(message: string, data?: unknown): void
+logger.info(message: string, data?: unknown): void
+logger.warn(message: string, data?: unknown): void
+logger.error(message: string, data?: unknown): void
+logger.fatal(message: string, data?: unknown): void
+```
+
+### 处理 SDK 日志
+
+```typescript
+logger.handleSDKLog(data: SDKLogData): void
+
+// 使用示例
+websdk.logger.onLog = (data) => {
+  logger.handleSDKLog(data);
+};
+```
+
+### 上传日志
+
+```typescript
+// 基础上传（使用初始化配置）
+await logger.upload(options?: CustomUploadConfig);
+
+// 上传到指定 URL
+await logger.uploadTo(url: string, headers?: Record<string, string>);
+
+// 使用自定义 handler
+await logger.uploadWithHandler(handler: CustomUploadHandler);
+```
+
+### 其他方法
+
+```typescript
+// 读取日志内容
+const logs = await logger.read();
+
+// 获取日志文件路径
+const path = logger.getFilePath();
+
+// 清空日志
+await logger.clear();
+
+// 压缩日志（App平台）
+const zipPath = await logger.compress();
+
+// 设置日志级别
+logger.setMinLevel('WARN');
+
+// 销毁 logger
+logger.destroy();
+```
+
+---
+
+## 构建产物
+
+```
+dist/
+├── index.js                          # ES Module（默认入口）
+├── easemob-uniapp-logger.esm.js      # ES Module（推荐用于 uni-app）
+├── easemob-uniapp-logger.js          # UMD（用于 script 标签）
+└── index.d.ts                        # TypeScript 类型声明
+```
+
+### 使用 ES Module（推荐）
+
+```javascript
+import { logger } from './js_sdk/easemob-uniapp-logger.esm.js';
+```
+
+---
+
+## 平台支持
+
+| 功能 | App (iOS/Android) | 微信小程序 | H5/其他 |
+|------|-------------------|------------|---------|
+| 文件存储 | ✅ plus.io | ✅ wx FileSystem | ❌ 内存存储 |
+| 日志压缩 | ✅ plus.zip | ❌ | ❌ |
+| 上传（Handler） | ✅ | ✅ | ✅ |
+
+---
+
+## 日志格式
+
+```
+[2026-03-11 14:07:28.123] [DEBUG] 调试信息 {"detail":"xxx"}
+[2026-03-11 14:07:28.456] [INFO] 用户登录成功 {"user":"alice"}
+[2026-03-11 14:07:29.789] [ERROR] 请求失败 {"code":500}
+[2026-03-11 14:07:30.012] [DEBUG] [SDK] Call fetchUserInfoById ["user1"]
+```
+
+---
+
+## License
+
+MIT