Sunshine-Track：轻量级前端监控库，适用于 Vue、React、Angular (错误、性能、行为追踪)

type

status

date

slug

summary

Sunshine-Track 简介：让前端监控更简单

sunshine-track 是一个轻量级的、开源的前端监控和行为追踪库，旨在为开发者提供关于用户交互、应用错误和性能瓶颈的宝贵洞察。它以灵活性为核心设计，能够无缝集成到 Vue、React、Angular 等主流框架中。

其核心原理是行为上报，允许您捕获关键数据点，例如：

用户交互（点击、页面跳转）

JavaScript 错误（运行时错误、Promise 拒绝）

API 请求监控

页面性能指标（包括 Web Vitals）

页面生命周期事件（加载、卸载、可见性）

问题检测（如白屏）

欢迎参与！在 GitHub 上查看源代码：https://github.com/sanxin-lin/sunshine-track。如果您觉得它有用，请点个 Star！⭐

Sunshine-Track 的核心功能

sunshine-track 提供了一套全面的监控能力：

✅ 用户行为追踪: 自动捕获用户点击、页面导航（包括历史记录追踪）和网络请求。

✅ 手动事件上报: 提供灵活的方式来发送自定义追踪数据，包括 JavaScript 函数（add, report）和一个方便的 Vue.js v-track 指令。

✅ 可定制的上报流程: 提供钩子函数，用于在数据发送前格式化数据 (format)、根据条件取消上报 (isReport) 或实现完全自定义的上报逻辑 (customReport)。

✅ 精细的请求监控: 配置规则以过滤哪些 API 请求被追踪，并定义自定义逻辑 (checkHttpStatus) 以根据您的特定 API 约定来验证响应成功/失败。

✅ 灵活的上报方式: 选择数据发送到后端的方式：img (信标)、http (通过 xhr 或 fetch，支持自定义请求头) 或 beacon (使用 navigator.sendBeacon)。

✅ 强大的数据缓存: 通过配置客户端缓存（内存 normal、localStorage storage 或 IndexedDB db），防止页面卸载或网络问题导致的数据丢失。

✅ 可配置的上报阈值: 批量处理用户行为事件，并在达到特定数量 (maxEvents) 后才发送，以优化网络使用。错误和性能数据通常会立即发送。

✅ 自动化点击追踪: 基于 CSS 选择器或元素文本内容，轻松配置全局监听器以自动追踪特定 DOM 元素的点击。

✅ Web 性能监控: 自动测量关键性能指标，包括白屏检测、FP (首次绘制)、FCP (首次内容绘制)、LCP (最大内容绘制)、CLS (累积布局偏移)、TTFB (首字节时间) 和 FID (首次输入延迟)。

标准化的上报数据格式

所有由 sunshine-track 上报的数据都遵循一致的结构，以便于后端处理：

字段 (Field)	描述 (Description)	类型 (Type)	示例 (Example)
`uuid`	该数据点的唯一标识符	`string`	`"a1b2c3d4-e5f6-..."`
`type`	上报数据的类别	`string`	`"behavior"`, `"error"`, `"performance"`
`data`	特定事件类型的具体载荷	`any`	`{ element: 'button#submit', ... }`
`time`	事件发生时的时间戳（毫秒）	`number`	`1678886400000`
`status`	上报事件的状态（例如，请求状态）	`string`	`"success"`, `"fail"`
`domain`	当前页面的域名	`string`	`"example.com"`
`href`	当前页面的完整 URL	`string`	`"<https://example.com/path>"`
`userAgent`	浏览器的 User-Agent 字符串	`string`	`"Mozilla/5.0 ..."`
`deviceInfo`	包含设备详情的对象（屏幕尺寸等）	`object`	`{ width: 1920, height: 1080, ... }`
`projectKey`*	您的项目标识符	`string`	`"YOUR_PROJECT_KEY"`
`userId`*	当前用户的标识符	`string`	`"user_123"`

(projectKey 和 userId 在初始化时添加)

安装

您可以使用 npm 或 yarn 安装 sunshine-track：

快速开始：基本用法

以下是如何在您的应用中初始化 sunshine-track（以 Vue.js 为例）：

配置示例

全局点击监听器 (`globalClickListeners`)

无需在每个元素上手动添加代码，即可自动追踪应用中特定元素的点击。使用 CSS 选择器配置 globalClickListeners：

上报阈值 (`maxEvents`)

控制行为数据（点击、导航、请求）的发送频率。错误和性能数据会立即发送。

默认: 缓存 10 个事件后批量发送。

自定义: 设置 maxEvents 为其他值。

数据缓存策略 (`cacheType`)

选择未发送数据的存储方式，以减少用户在数据发送前关闭标签页导致的数据丢失：

normal: (默认) 内存缓存（页面关闭后丢失）。

storage: 使用浏览器 localStorage。

db: 使用浏览器 IndexedDB（对于大量数据更健壮）。

调试：打印上报数据 (`log`)

在开发过程中启用控制台日志，查看准备上报的数据：

自定义请求上报

对 API 请求监控进行精细控制：

filterHttpUrl: 一个函数，用于排除特定 API 调用不被追踪。返回 true 进行追踪，false 则忽略。

checkHttpStatus: 一个函数，用于定义自定义逻辑，根据响应状态码或内容判断 API 响应是成功还是失败。

高级自定义钩子 (`report`)

使用 report 配置对象来修改上报过程：

format: 一个函数，在数据对象添加到上报队列之前对其进行修改。

isReport: 一个函数，接收数据批次，返回 true 以继续上报，或 false 以取消本次上报。

customReport: 一个函数，用于完全接管上报逻辑。如果提供此函数，库内置的上报方法（img, http, beacon）将被绕过。

手动上报

通过编程方式触发追踪事件：

add(data): 将自定义数据添加到上报队列中（遵循 maxEvents 阈值）。

report(data): 立即发送数据，绕过队列和阈值。

v-track 指令 (Vue.js): 在 Vue 模板中轻松追踪特定元素的点击。

完整配置选项参考

路径 (Path)	描述 (Description)	类型 (Type)	默认值 (Default)
`projectKey`	必填: 您的唯一项目标识符	`string`	-
`userId`	可选：当前用户的标识符	`string`	`''`
`report.url`	必填: 您的后端上报接口 URL	`string`	-
`report.reportType`	上报方式 (`img`, `http`, `beacon`)	`string`	`'http'`
`report.headers`	`http` 上报模式的自定义请求头	`object`	`{}`
`report.format`	数据入队前格式化数据的函数	`(data: any) => any`	`undefined`
`report.customReport`	自定义上报逻辑的函数	`(data: any[]) => void`	`undefined`
`report.isReport`	条件性取消上报批次的函数	`(data: any[]) => boolean`	`undefined`
`cacheType`	缓存方式 (`normal`, `storage`, `db`)	`string`	`'normal'`
`globalClickListeners`	全局点击追踪的配置数组	`array`	`[]`
`log`	启用控制台日志进行调试	`boolean`	`false`
`maxEvents`	批量处理行为事件的阈值	`number`	`10`
`historyUrlsNum`	在导航历史中保留的先前 URL 数量	`number`	`10`
`checkHttpStatus`	验证 API 响应状态的函数	`(data: any, status: number) => boolean`	(内部检查)
`filterHttpUrl`	过滤哪些 API 请求被追踪的函数	`(url: string) => boolean`	`() => true`
`switchs.xhr`	启用/禁用 `XMLHttpRequest` 监控	`boolean`	`true`
`switchs.fetch`	启用/禁用 `fetch` API 监控	`boolean`	`true`
`switchs.error`	启用/禁用 JavaScript 错误监控	`boolean`	`true`
`switchs.whitescreen`	启用/禁用白屏检测	`boolean`	`true`
`switchs.hashchange`	启用/禁用 `hashchange` 事件追踪	`boolean`	`true`
`switchs.history`	启用/禁用 `pushState`/`replaceState` 事件追踪	`boolean`	`true`
`switchs.performance`	启用/禁用 Web 性能指标追踪	`boolean`	`true`