memory-monitor-sdk/README.md

A powerful JavaScript memory monitoring SDK for Web and mobile applications. Features real-time monitoring, data visualization, automatic reporting, and memory leak detection.

# Memory Monitor SDK

一个功能强大的 JavaScript 内存监控 SDK，专为 Web 应用和移动端应用设计，用于检测内存泄漏和性能问题。支持实时监控、数据可视化、自动报告生成等功能。

## ✨ 特性

- 🔍 **实时内存监控** - 基于 `performance.memory` API 的实时内存使用情况监控
- 📱 **移动端模拟** - 模拟手机环境的内存限制，便于在 PC 上调试移动端应用
- 📊 **可视化面板** - 开发环境下提供可拖拽的实时内存显示面板
- 📈 **数据可视化** - 内置 HTML 可视化工具，支持图表展示和数据分析
- 🚨 **智能告警** - 多级内存使用率告警（注意/警告/危险）
- 📋 **详细报告** - 自动生成包含趋势分析、峰值变化、页面信息的详细报告
- 💾 **数据导出** - 支持将监控数据导出为 JSON 格式
- 🎯 **页面追踪** - 自动追踪页面变化，关联内存使用情况
- ⚡ **零配置** - 开发环境自动启动，生产环境按需使用

## 🚀 快速开始

### 安装

```bash
npm install memory-monitor-sdk
```

### 基础使用

```javascript
import { memoryMonitor } from 'memory-monitor-sdk';

// 开始监控（开发环境会自动启动）
memoryMonitor.startMonitoring(
  2000,    // 监控间隔（毫秒）
  300,     // 模拟手机内存上限（MB）
  20,      // 峰值变化阈值（MB）
  true     // 是否显示DOM面板
);

// 保存数据
memoryMonitor.saveDataToFile();
```

### 在项目中使用

#### 1. 基础监控

```javascript
import { memoryMonitor } from 'memory-monitor-sdk';

// 应用启动时开始监控
memoryMonitor.startMonitoring();

```

#### 2. 高级配置

```javascript
// 自定义监控参数
memoryMonitor.startMonitoring(
  3000,    // 每3秒监控一次
  500,     // 模拟500MB内存上限
  30,      // 30MB以上变化视为峰值
  false    // 不显示DOM面板
);
```



## 📊 数据可视化

项目包含一个功能完整的数据可视化工具，位于 `dist/index.html`。

### 使用方法

1. 在监控过程中保存数据：
   ```javascript
   memoryMonitor.saveDataToFile();
   ```

2. 打开 `dist/index.html` 文件

3. 选择生成的 JSON 数据文件或加载示例数据

4. 查看内存使用趋势图表和详细统计信息

### 可视化功能

- 📈 **趋势图表** - 基于 ECharts 的交互式内存使用趋势图
- 📊 **统计卡片** - 当前/最大/平均内存使用情况
- 🔍 **详细信息** - 会话ID、运行时长、采样点数等
- 📱 **响应式设计** - 支持桌面和移动端查看
- 💾 **数据导出** - 支持重新导出处理后的数据

## 🛠️ API 文档

### MemoryMonitor 类

#### 方法

##### `startMonitoring(intervalMs?, simulatedLimitMB?, peakThresholdMB?, showDisplay?)`

开始内存监控

- `intervalMs` (number, 默认: 2000) - 监控间隔（毫秒）
- `simulatedLimitMB` (number, 默认: 300) - 模拟手机内存上限（MB）
- `peakThresholdMB` (number, 默认: 20) - 峰值变化阈值（MB）
- `showDisplay` (boolean, 默认: true) - 是否显示DOM面板

##### `stopMonitoring()`

停止内存监控

##### `setCurrentPage(pageName)`

设置当前页面名称

- `pageName` (string) - 页面名称或路径

##### `getMemoryTrend()`

获取内存使用趋势分析

返回：
```javascript
{
  trend: 'increasing' | 'decreasing' | 'stable' | 'insufficient_data',
  message: string,
  growth?: string
}
```

##### `generateReport()`

生成基础内存报告

##### `generateDetailedReport(level?)`

生成详细内存报告

- `level` ('warning' | 'danger', 默认: 'warning') - 报告级别

##### `saveDataToFile()`

保存监控数据到JSON文件

##### `getPeakChanges()`

获取峰值变化记录

##### `clearLogs()`

清理监控数据

##### `showDisplay()` / `hideDisplay()` / `toggleDisplayPanel()`

控制DOM面板显示

### 内存状态级别

- 🟢 **normal** - 正常（< 40%）
- 🟡 **caution** - 注意（40-60%）
- ⚠️ **warning** - 警告（60-80%）
- 🚨 **danger** - 危险（≥ 80%）
- 📈 **peak** - 峰值变化（变化 ≥ 阈值）

## 🔧 开发

### 项目结构

```
memory-monitor-sdk/
├── src/
│   ├── index.ts          # SDK 入口文件
│   ├── memory-monitor.ts # 核心监控类
│   └── index.html        # 可视化工具
├── dist/                 # 构建输出
├── package.json
├── tsconfig.json
├── vite.config.ts
└── README.md
```



### 技术栈

- **TypeScript** - 类型安全的 JavaScript
- **Vite** - 快速构建工具
- **ECharts** - 数据可视化图表库
- **HTML5** - 现代化 Web 技术





## ⚠️ 注意事项

1. **浏览器兼容性** - 需要支持 `performance.memory` API（主要是 Chrome）
2. **开发环境** - DOM 面板仅在开发环境显示
3. **内存限制** - 模拟的手机内存限制仅用于参考，实际设备可能不同
4. **数据存储** - 监控数据存储在内存中，页面刷新会丢失

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！


**Memory Monitor SDK** - 让内存监控变得简单高效！ 🚀