# webeyssdk

**Repository Path**: baseHuang/webeyssdk

## Basic Information

- **Project Name**: webeyssdk
- **Description**: 前端监控sdk
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 36
- **Created**: 2024-10-15
- **Last Updated**: 2026-05-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# WebEyes SDK

面向 Web 应用的前端监控采集 SDK（错误、性能、行为），计划演进为企业级监控平台。

## 文档

完整产品设计见 **[doc/](./doc/)**：

| 文档 | 内容 |
|------|------|
| [doc/12-前端改版清单.md](./doc/12-前端改版清单.md) | **SDK 改版状态与 init 用法（最新）** |
| [doc/03-SDK增强设计.md](./doc/03-SDK增强设计.md) | 采样、限流、去重、脱敏 |
| [doc/10-上报逻辑设计.md](./doc/10-上报逻辑设计.md) | fetch/beacon、flush 策略 |
| [doc/11-面试难点与亮点.md](./doc/11-面试难点与亮点.md) | 面试话术 |

## 当前 SDK 能力

| 模块 | 说明 |
|------|------|
| **错误** | JS、Promise、资源；Vue `install`、React `errorBoundary` |
| **性能** | FCP、LCP、Paint、Load、资源、fetch/xhr |
| **行为** | PV、hash/popstate、点击（脱敏） |
| **治理** | 采样、限流、去重、熔断、隐私脱敏 |
| **上报** | Envelope 批量、fetch + 关页 Beacon、定时/错误 flush、离线 IndexedDB |
| **行为** | hash/popstate + **SPA pushState/replaceState** |
| **录屏** | rrweb（`modules` 含 `replay`），出错传 buffer |
| **身份** | 可配置 `identity` 字段（deviceId/uid 等），后台按字段排查 |

> 管理后台见 **`admin/`**（独立 npm 包）；ClickHouse 等为规划中能力。

## 快速开始（SDK）

```bash
pnpm install
pnpm run build
```

## 本地服务层（独立目录 `server/`）

```bash
cd server
pnpm install
cp .env.example .env
pnpm run dev
```

浏览器打开 **http://127.0.0.1:9800/demo.html**（需先在根目录 `pnpm run build`）。  
服务说明见 **[server/README.md](./server/README.md)**。

## 管理后台（独立目录 `admin/`）

```bash
cd admin
pnpm install
pnpm run dev
```

浏览器打开 **http://127.0.0.1:5173**（需 server 已启动）。说明见 **[admin/README.md](./admin/README.md)**。

```html
<script src="/dist/monitor.js"></script>
<script>
  // IIFE 全局名为 WebEyes（dist/monitor.js）
  WebEyes.init({
    appId: 'your_app_id',
    url: 'http://127.0.0.1:9800/api/v1/report',
    release: '1.0.0',
    batchSize: 20,
    flushIntervalMs: 10000,
    modules: ['error', 'performance', 'behavior'],
  });
</script>
```

## Vue / React 项目接入

**只使用 `pnpm run build` 后的 `dist/` 文件**，不要引用 `src/`。

| 场景 | 使用文件 |
|------|----------|
| Vue3 / React（Vite） | `import WebEyes from 'eyesdk'` → `dist/monitor.esm.js` |
| 静态资源 | 复制 `dist/monitor.js` 到 `public/vendor/` |
| 本地联调 | `"eyesdk": "file:../webeyssdk"` 后 `import` |

详细步骤见 **[doc/13-Vue与React接入.md](./doc/13-Vue与React接入.md)**。  
业务 ID（deviceId/uid 等）见 **[doc/14-业务身份标识identity.md](./doc/14-业务身份标识identity.md)**。

**Vue 3：**

```typescript
import WebEyes from 'eyesdk';
app.use(WebEyes, {
  appId: 'prod_xxx',
  url: 'https://api.example.com/api/v1/report',
  modules: ['error', 'performance', 'behavior'],
});
```

**React：**

```tsx
import WebEyes from 'eyesdk';
await WebEyes.init({ appId: 'prod_xxx', url: '...' });
// 根组件外包一层 ErrorBoundary，在 componentDidCatch 里调用 WebEyes.errorBoundary(error, info)
```

## 上报接口（由 server/ 提供）

```
POST http://127.0.0.1:9800/api/v1/report
```

响应：`{ "code": 0, "data": { "accepted": N, "dropped": 0 } }`

## 源码结构

```text
src/
  webEyeSDK.js    # 入口
  config.js       # 配置
  event.js        # 事件规范
  privacy/        # 脱敏
  pipeline/       # 采样、限流、去重
  report/         # 上报核心
  offline/        # 离线队列
  error/ performance/ behavior/
```

## 技术栈

- SDK 打包：Rollup + Babel
- 服务层：Express + SQLite（见 `server/`，无需单独装数据库）
- 管理后台：Vite + React + Ant Design（见 `admin/`）