mini-sentry-sdk weekly downloads statistics

Mini-Sentry SDK 使用说明文档

📋 目录

• 快速开始 • 安装配置 • 基础用法 • 功能详解 • SourceMap 配置 • React 集成 • Webpack 插件 • API 参考 • 最佳实践 • 故障排除

🚀 快速开始

安装

基础使用

📦 安装配置

1. 项目依赖

确保项目满足以下要求： • Node.js >= 14.0.0 • 现代浏览器支持 (支持 ES2019) • React >= 16.8.0 (如果使用 React 功能)

2. 安装方式

NPM/Yarn 安装 (推荐)

CDN 引入

ES Module

CommonJS

🎯 基础用法

1. 创建监控实例

2. 手动错误上报

🔧 功能详解

错误监控

自动捕获的错误类型： • JavaScript 运行时错误 • Promise 未处理的拒绝 • 资源加载错误 • HTTP 请求错误 • React 组件错误（配合 ErrorBoundary）

错误信息包含： • 错误堆栈信息 • 用户行为轨迹（面包屑） • 设备和浏览器信息 • 当前页面 URL • 自定义标签

性能监控

监控指标： • TTFB: 首字节时间 • FCP: 首次内容绘制 • LCP: 最大内容绘制 • DOM Ready: DOM 准备时间 • Load Complete: 页面完全加载时间 • Long Tasks: 长任务检测 (>50ms)

使用示例：

用户行为追踪

自动追踪的行为： • 页面访问和路由变化 • 用户点击事件 • 表单提交 • 滚动行为 • 页面可见性变化 • 页面停留时间

自定义行为追踪：

网络监控

自动拦截： • Fetch API 请求 • XMLHttpRequest 请求 • 请求失败和超时 • HTTP 状态码异常

🗺️ SourceMap 配置

1. Webpack 配置

步骤 1：配置 webpack.config.js

步骤 2：构建项目

构建时插件会自动： 1. 收集生成的 .map 文件 2. 上传到指定的 API 地址 3. 删除本地 sourcemap 文件（可配置）

2. 手动上传 SourceMap

3. SourceMap 最佳实践

文件命名规范： • JS 文件：main.abc123.js (包含 hash) • SourceMap 文件：main.abc123.js.map

生产环境安全：

⚛️ React 集成

1. ErrorBoundary 使用

2. Hook 集成

🔌 Webpack 插件

插件功能

• 自动收集构建生成的 sourcemap 文件 • 智能识别文件 hash 和映射关系 • 批量上传到后端服务器 • 支持重试和错误处理 • 构建后自动清理本地 sourcemap

高级配置

📚 API 参考

Monitor 类

构造函数

主要方法

init(): Promise • 初始化监控 • 启动所有监控模块

captureError(error: Error, tags?: Record): void • 手动上报错误 • error: Error 对象 • tags: 自定义标签

trackEvent(category, message, data?): void • 追踪用户事件 • category: 事件类别 • message: 事件描述 • data: 事件数据

trackMetric(name: string, value: number, tags?): void • 追踪性能指标 • name: 指标名称 • value: 指标值 • tags: 标签

trackBusiness(event: string, data?): void • 追踪业务事件 • event: 事件名称 • data: 事件数据

addBreadcrumb(category, message, level?, data?, captureType?): void • 添加面包屑 • category: 类别 • message: 消息 • level: 级别 ('info' | 'warning' | 'error') • data: 附加数据 • captureType: 捕获类型 ('auto' | 'manual')

调试方法

getStatus(): object • 获取监控状态

getVitalsStatus(): object • 获取性能指标状态

getBreadcrumbStatus(): object • 获取面包屑状态

debugLcpSituation(): void • 调试 LCP 问题

debugErrorMapping(): void • 调试错误映射

destroy(): void • 销毁监控实例

ErrorBoundary 组件

Props

SourceMapUploader 类

构造函数

方法

upload(request: UploadRequest): Promise • 上传 sourcemap 文件

validateSourceMap(content: string): boolean • 验证 sourcemap 文件格式

compressSourceMap(content: string): string • 压缩 sourcemap 内容

💡 最佳实践

1. 环境配置

2. 错误分类

3. 性能监控

4. 批量数据处理

5. 安全和隐私

🔧 故障排除

常见问题

1. SDK 初始化失败

2. SourceMap 上传失败

3. 性能指标不准确

4. 错误上报过多

调试技巧

启用调试模式：

检查上报状态：

网络问题诊断：

📞 技术支持

如果遇到问题：

1. 查看控制台错误信息 2. 启用 debug 模式获取详细日志 3. 检查网络连接和 API 配置 4. 确认浏览器兼容性 5. 参考本文档的故障排除部分

📄 许可证

MIT License

版本信息： v1.1.43 更新时间： 2025年 兼容性： 现代浏览器、Node.js 14+

🚀 实际项目示例

完整的 Vite + React 项目配置

基于真实项目的最佳实践配置，这是一个可直接运行的完整示例。

项目结构

1. 环境配置

2. Vite 配置

3. SDK 初始化

4. React ErrorBoundary 集成

5. 构建和部署

6. 测试验证

项目包含完整的测试页面：

• 错误测试：/error-test - 测试各种错误捕获 • 性能测试：/performance-test - 测试性能指标收集 • 行为测试：/behavior-test - 测试用户行为追踪

7. 实际业务场景

🎯 关键优势

1. 零配置启动：克隆即可运行 2. 生产级配置：包含完整的构建和部署流程 3. 实战场景：模拟真实的电商、仪表板等业务场景 4. 完整测试：涵盖所有SDK功能的测试用例 5. 开箱即用：包含 Mock 服务器和环境配置

这个示例展示了如何在真实项目中集成 Mini-Sentry SDK，比文档中的简单示例更加实用和完整。

Description from the npm listing.