Mini Sentry SDK 使用文档

面向 npm 安装 的前端异常监控 SDK。上报协议与 Mini Sentry 后端 Ingest 对齐。

当前版本：2.0.0
模块格式：纯 ESM（"type": "module"）
运行环境：现代浏览器 / 小程序运行时；构建需 Node ≥ 16

1. 包一览

全部发布在 npm 组织 [@zayn919](https://www.npmjs.com/org/zayn919) 下

npm 包	适用场景	依赖
`[@zayn919/minisentry-core](https://www.npmjs.com/package/@zayn919/minisentry-core)`	自定义平台 / 二次封装	无
`[@zayn919/minisentry-browser](https://www.npmjs.com/package/@zayn919/minisentry-browser)`	原生 JS / TS / SPA	core
`[@zayn919/minisentry-vue3](https://www.npmjs.com/package/@zayn919/minisentry-vue3)`	Vue 3	browser
`[@zayn919/minisentry-vue2](https://www.npmjs.com/package/@zayn919/minisentry-vue2)`	Vue 2.6 / 2.7	browser
`[@zayn919/minisentry-uniapp](https://www.npmjs.com/package/@zayn919/minisentry-uniapp)`	uni-app（H5 / 小程序等）	core
`[@zayn919/minisentry-sourcemap](https://www.npmjs.com/package/@zayn919/minisentry-sourcemap)`	构建时自动上传 SourceMap（Vite 插件 / CLI）	无（Node ≥ 18）

业务项目一般只需安装对应适配包（会自动拉取依赖）。SourceMap 上传装 devDependency 即可。

2. 安装

bash

# 选其一
npm install @zayn919/minisentry-browser
npm install @zayn919/minisentry-vue3
npm install @zayn919/minisentry-vue2
npm install @zayn919/minisentry-uniapp

# 或 yarn / pnpm
pnpm add @zayn919/minisentry-vue3

Vue 需自行安装 peer：

bash

# Vue 3
npm install vue@^3

# Vue 2
npm install vue@^2.7

3. 获取 DSN

登录 Mini Sentry Dashboard，创建应用
应用列表点击「复制 DSN」，格式：

text

https://sentry.example.com/api/{public_key}/ingest/

规则说明：

部分	规则
`public_key`	创建应用时生成的 32 位小写十六进制（`secrets.token_hex(16)`，128-bit 熵）
路径	`/api/{public_key}/ingest/`，不含自增数字 `project_id`，避免被枚举猜测
查询参数	无需 `?pk=`（密钥已在路径中）

内部数据库仍使用数字主键做关联；仅对外 DSN / Ingest 入口使用 public_key。

若 Dashboard 与 API 不同域，构建 Dashboard 时设置环境变量 VITE_API_PUBLIC_URL。

4. 快速接入

4.1 Browser（原生 JS / TS）

import { init, getClient, close } from '@zayn919/minisentry-browser';

init({
  dsn: 'https://sentry.example.com/api/<public_key>/ingest/',
  release: 'web@1.2.0',
  environment: 'production',
  sampleRate: 1,              // 0~1；fatal 永不采样
  dedupeWindow: 2000,         // 相同错误客户端去重窗口（ms）
  maxEventsPerMinute: 30,     // 客户端防洪
  // 可选：只允许不可逆标识，stableHash 由业务项目自行实现
  getUser: () => ({ id: localStorage.getItem('uid') ?? undefined }),
  hashUserId: (id) => stableHash(id),
});

// 手动上报
getClient()?.capture({
  type: 'error',
  message: '组件渲染失败',
  level: 'warning',
});

// SPA 路由级卸载时可关闭（恢复原生 fetch/XHR）
// close();

自动捕获：

类型	说明
Runtime	`window.error`
Promise	`unhandledrejection`
Network	`fetch` / `XHR` 失败或 HTTP ≥400
Resource	图片/脚本等加载失败 → breadcrumb
Unload	`pagehide` 时 `sendBeacon` 冲刷队列

4.2 Vue 3

import { createApp } from 'vue';
import { init, vue3Install, getClient, close } from '@zayn919/minisentry-vue3';
import App from './App.vue';

init({
  dsn: 'https://sentry.example.com/api/<public_key>/ingest/',
  release: 'web@1.2.0',
  environment: import.meta.env.MODE,
});

const app = createApp(App);
vue3Install(app); // 必须在 mount 前
app.mount('#app');

在 Browser 能力之上，额外捕获组件渲染 / 生命周期错误，并附带组件名（type.name / __name）。

4.3 Vue 2

import Vue from 'vue';
import MiniSentryVue2 from '@zayn919/minisentry-vue2';

Vue.use(MiniSentryVue2, {
  dsn: 'https://sentry.example.com/api/<public_key>/ingest/',
  release: 'app@2.0.1',
});

或分步：

import { init, vue2Install } from '@zayn919/minisentry-vue2';

init({ dsn: '...' });
vue2Install(Vue);

4.4 uni-app

// main.ts / main.js
import { init, getClient } from '@zayn919/minisentry-uniapp';

init({
  dsn: 'https://sentry.example.com/api/<public_key>/ingest/',
  release: 'mp@1.0.0',
});

在 App.vue 中转发运行时错误（强烈推荐）：

vue

<script>
import { getClient } from '@zayn919/minisentry-uniapp';

export default {
  onError(err) {
    getClient()?.onError(err);
  },
};
</script>

能力说明：

上报走 uni.request（无 window.fetch）
uni.request 失败 / HTTP ≥400 → breadcrumb + network 事件
支持 stack / frames 直接传入；小程序堆栈字符串可解析
getClient()?.close() 可恢复原生 uni.request

5. 配置项（SdkOptions）

字段	类型	默认	说明
`dsn`	string	必填	Ingest 完整 URL
`release`	string	—	版本号，关联 SourceMap
`environment`	string	—	如 `production` / `staging`
`sampleRate`	number	`1`	0~1；`fatal` 跳过采样
`dedupeWindow`	number	`2000`	相同 fingerprint 去重窗口（ms）；`fatal` 跳过
`maxEventsPerMinute`	number	`30`	分钟上限；`fatal` 跳过
`sanitizeKeys`	RegExp	内置	敏感字段名匹配
`getUser`	`() => object`	—	可选用户 ID 来源；单独配置不会上报
`hashUserId`	`(id) => string`	—	与 getUser 同时配置时仅上报散列 ID
`captureExtra`	boolean	`false`	是否允许 extra；开启前必须确认无业务数据
`allowedQueryParams`	string[]	`[]`	URL query 技术参数白名单，默认全部删除
`onTransportResult`	function	—	发送成功/失败回调
`onDiagnostic`	function	—	开发环境诊断采样、去重、限流、网络/CORS
`maxPayloadBytes`	number	`92160`（90KB）	超限按 frames → breadcrumbs → extra 裁剪

6. 手动 API

import { getClient } from '@zayn919/minisentry-browser'; // 或 vue3 / vue2 / uniapp

const client = getClient();

client?.addBreadcrumb({ category: 'navigation', message: '/checkout' });

client?.capture({
  type: 'error',
  level: 'fatal',           // fatal：不采样、不去重、不限流
  message: '前端渲染异常',
  error: err,               // Error 对象会自动解析 stack
  request: { url: location.href },
  // uni-app / 自定义也可：
  // stack: { frames: [...] },
  // frames: [...],
});

capture 返回 event_id（string）或因采样/去重/限流返回 null。

7. 行为说明

技术字段白名单：URL query 默认全部删除，不采集表单、DOM 文本、请求/响应正文
三层防洪：客户端采样 + 去重 + 分钟限流；Nginx IP 限流；服务端 Project 限流 + fingerprint 5s 去重。
失败重试：内存有界队列（最多约 20 条）+ 有限次指数退避；浏览器 pagehide 时 sendBeacon。
payload 上限：默认 90KB，避免触发服务端 100KB 限制（HTTP 413）。
自上报回环防护：发往自身 DSN 的请求不会再被捕获为 network 事件。

8. SourceMap（推荐：构建时自动上传）

第三方业务项目不要手工传 map，用 @zayn919/minisentry-sourcemap：

8.1 Vite（`npm run build` 自动上传）

bash

npm install -D @zayn919/minisentry-sourcemap

// vite.config.ts
import { minisentrySourcemap } from '@zayn919/minisentry-sourcemap/vite'

export default defineConfig({
  build: { sourcemap: true },
  plugins: [minisentrySourcemap()], // 配置走环境变量即可
})

CI 环境变量（勿写入仓库）：

bash

MINISENTRY_URL=https://sentry.example.com
MINISENTRY_PROJECT=1
MINISENTRY_RELEASE=web@1.2.0          # 与 SDK init({ release }) 一致
MINISENTRY_AUTH_TOKEN=<项目级 SourceMap CI Token>

CI Token 在 Dashboard「应用设置」中生成，明文仅显示一次。权限范围（仅限当前项目）：

SourceMap 上传与状态查询
Release 状态查询
Release 基线分析与 quality-check（CI 门禁）

不含噪声规则、告警配置、Issue 处置。之后照常 npm run build，插件在产物写出后扫描 dist/**/*.map 批量上传。

8.2 非 Vite（CLI）

json

{
  "scripts": {
    "build": "webpack --mode production && minisentry-sourcemaps upload --dir dist"
  }
}

8.3 业务线上部署：不要公开 `.map`

build.sourcemap: true 只负责生成 map；堆栈还原靠上传到 Mini Sentry 的私有存储。
不要把 .map 跟 JS 一起发到 CDN / 业务 Nginx（会暴露源码路径，也无必要）。

服务端上传接口仅接受 *.map 或内含 .map 的 *.zip；.js / .exe / .sh 等会被拒绝，内容也会校验非可执行文件魔数且须为 JSON SourceMap。

推荐流水线顺序：

bash

npm run build
# Vite 插件已自动上传；或：minisentry-sourcemaps upload --dir dist ...

# 同步静态资源时排除 map
rsync -avz --delete \
  --exclude '*.map' \
  --exclude '**/*.map' \
  ./dist/ \
  user@server:/var/www/app/

步骤	做什么
构建	生成 `.js` + `.js.map`
上传 Mini Sentry	插件 / CLI 推送全部 `.map`
部署业务站点	只发 `.js` 等资源，排除 `*/.map`

8.4 其它

Dashboard 多选 / zip、或仓库内 Python 脚本 backend/scripts/upload_sourcemaps.py（运维侧）
Issue 详情页打开时自动批量还原堆栈（*.js.map → *.js 匹配）

9. TypeScript

各包自带 dist/index.d.ts，exports.types 已声明，无需 @types/*。

import type { SdkOptions, CapturedEvent, StackFrame } from '@zayn919/minisentry-browser';

10. 与打包器兼容性

工具	支持
Vite	✅
Webpack 5	✅
Rollup / esbuild / Parcel	✅
Webpack 4	需确认已启用 ESM
直接 `<script>` CDN	❌（当前无 UMD 构建；欢迎提需求）

11. 常见问题

Q: 上报 403？
检查 DSN 中的 public_key（路径中 32 位 hex）是否正确，项目是否为 active。

Q: 上报 429？
触发客户端或服务端限流。可调高 maxEventsPerMinute / 项目 rate_limit，或降低 sampleRate。

Q: 上报 413？
payload 过大。SDK 默认会裁剪；也可减小 breadcrumb / extra。

Q: Vue 错误没进 Mini Sentry？
确认调用了 vue3Install(app) / Vue.use(...)，且在 mount 之前。

Q: uni-app 只有 message 没有堆栈？
在 App.vue 的 onError 里调用 getClient()?.onError(err)，或手动 capture({ stack/frames })。

Q: 本地开发跨域？
Ingest 接口需允许浏览器 Origin，或开发时用同源代理。

12. 维护者：构建与发布到 npm

仓库为 npm workspaces monorepo。发布顺序：core → browser → vue3 / vue2 / uniapp。

bash

# 1. 登录（一次性）
npm login

# 2. 确认包名未被占用
npm view @zayn919/minisentry-core version || echo '可用'
npm view @zayn919/minisentry-browser version || echo '可用'

# 3. 根目录安装依赖
npm install

# 4. 构建
npm run build:packages

# 5. 预检（不真正上传）
npm run publish:packages:dry

# 6. 正式发布（public）
npm run publish:packages

# 7. 验证
npm view @zayn919/minisentry-browser version
npm view @zayn919/minisentry-vue3 version

发版前检查：

五个包 version 字段对齐（当前 2.0.0）
依赖使用 ^2.0.0（勿用 workspace:*，否则 npm 消费者无法解析）
tarball 仅含 dist + README.md + LICENSE + package.json
包发布在组织 @zayn919 下（publishConfig.access=public）；发布账号需对该 org 有 publish 权限

版本 bump 示例：

bash

# 在各 packages/*/package.json 同步改 version，再：
npm run publish:packages

13. 相关链接

仓库：gitee.com/zh423328/mini-sentry

Mini Sentry SDK 使用文档 ​

1. 包一览 ​

2. 安装 ​

3. 获取 DSN ​

4. 快速接入 ​

4.1 Browser（原生 JS / TS） ​

4.2 Vue 3 ​

4.3 Vue 2 ​

4.4 uni-app ​

5. 配置项（SdkOptions） ​

6. 手动 API ​

7. 行为说明 ​

8. SourceMap（推荐：构建时自动上传） ​

8.1 Vite（npm run build 自动上传） ​

8.2 非 Vite（CLI） ​

8.3 业务线上部署：不要公开 .map ​

8.4 其它 ​

9. TypeScript ​

10. 与打包器兼容性 ​

11. 常见问题 ​

12. 维护者：构建与发布到 npm ​

13. 相关链接 ​

Mini Sentry SDK 使用文档

1. 包一览

2. 安装

3. 获取 DSN

4. 快速接入

4.1 Browser（原生 JS / TS）

4.2 Vue 3

4.3 Vue 2

4.4 uni-app

5. 配置项（SdkOptions）

6. 手动 API

7. 行为说明

8. SourceMap（推荐：构建时自动上传）

8.1 Vite（`npm run build` 自动上传）

8.2 非 Vite（CLI）

8.3 业务线上部署：不要公开 `.map`

8.4 其它

9. TypeScript

10. 与打包器兼容性

11. 常见问题

12. 维护者：构建与发布到 npm

13. 相关链接