@xysfe/bug-tap 0.0.0-stage → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +75 -0
- package/LICENSE +21 -0
- package/README.md +461 -2
- package/THIRD_PARTY_NOTICES.md +39 -0
- package/dist/bug-tap-screenshot.min.js +10 -0
- package/dist/bug-tap-screenshot.min.js.map +1 -0
- package/dist/bug-tap-vue.cjs +2 -0
- package/dist/bug-tap-vue.cjs.map +1 -0
- package/dist/bug-tap-vue.js +106 -0
- package/dist/bug-tap-vue.js.map +1 -0
- package/dist/bug-tap-vue.min.js +2 -0
- package/dist/bug-tap-vue.min.js.map +1 -0
- package/dist/bug-tap.cjs +2 -0
- package/dist/bug-tap.cjs.map +1 -0
- package/dist/bug-tap.js +13 -0
- package/dist/bug-tap.js.map +1 -0
- package/dist/bug-tap.min.js +508 -0
- package/dist/bug-tap.min.js.map +1 -0
- package/dist/config.d.ts +14 -0
- package/dist/core/body.d.ts +30 -0
- package/dist/core/breadcrumbs.d.ts +85 -0
- package/dist/core/browser-api-errors.d.ts +55 -0
- package/dist/core/byte-buffer.d.ts +43 -0
- package/dist/core/collector.d.ts +34 -0
- package/dist/core/console-collector.d.ts +23 -0
- package/dist/core/env-collector.d.ts +16 -0
- package/dist/core/error-collector.d.ts +48 -0
- package/dist/core/error-noise.d.ts +43 -0
- package/dist/core/network-collector.d.ts +97 -0
- package/dist/core/network-record.d.ts +19 -0
- package/dist/core/resource-timing.d.ts +28 -0
- package/dist/core/ring-buffer.d.ts +22 -0
- package/dist/core/selector.d.ts +3 -0
- package/dist/core/serialize.d.ts +5 -0
- package/dist/core/tongji.d.ts +14 -0
- package/dist/core/user.d.ts +9 -0
- package/dist/index-BbRyzCzY.cjs +488 -0
- package/dist/index-BbRyzCzY.cjs.map +1 -0
- package/dist/index-D_ygxzgY.js +4685 -0
- package/dist/index-D_ygxzgY.js.map +1 -0
- package/dist/index.d.ts +33 -0
- package/dist/integrations.d.ts +26 -0
- package/dist/panel-mount-BOOHHmMb.js +499 -0
- package/dist/panel-mount-BOOHHmMb.js.map +1 -0
- package/dist/panel-mount-CjRBibNV.cjs +2 -0
- package/dist/panel-mount-CjRBibNV.cjs.map +1 -0
- package/dist/screenshot-global.d.ts +14 -0
- package/dist/sdk.d.ts +76 -0
- package/dist/transport/log-item.d.ts +2 -0
- package/dist/transport/offline-queue.d.ts +48 -0
- package/dist/transport/payload.d.ts +15 -0
- package/dist/transport/transport.d.ts +57 -0
- package/dist/transport/upload.d.ts +8 -0
- package/dist/types.d.ts +459 -0
- package/dist/ui/element-picker.d.ts +51 -0
- package/dist/ui/floating-button.d.ts +43 -0
- package/dist/ui/icons.d.ts +1 -0
- package/dist/ui/panel-mount.d.ts +20 -0
- package/dist/ui/panel.vue.d.ts +15 -0
- package/dist/ui/screenshot-loader-shared.d.ts +2 -0
- package/dist/ui/screenshot-loader.d.ts +14 -0
- package/dist/ui/screenshot-loader.iife.d.ts +16 -0
- package/dist/ui/screenshot.d.ts +20 -0
- package/dist/ui/shadow-host.d.ts +16 -0
- package/dist/ui/styles.css.d.ts +1 -0
- package/dist/ui/visibility.d.ts +25 -0
- package/dist/utils/match.d.ts +2 -0
- package/dist/utils/ua.d.ts +6 -0
- package/dist/utils/url.d.ts +2 -0
- package/dist/vue-global.d.ts +21 -0
- package/dist/vue.d.ts +49 -0
- package/docs/api.md +257 -0
- package/docs/backend-api.md +401 -0
- package/docs/bundler.md +122 -0
- package/docs/config.md +396 -0
- package/package.json +97 -4
package/docs/config.md
ADDED
|
@@ -0,0 +1,396 @@
|
|
|
1
|
+
# 配置项
|
|
2
|
+
|
|
3
|
+
## 示例
|
|
4
|
+
|
|
5
|
+
```js
|
|
6
|
+
window.BugTapConfig = {
|
|
7
|
+
project: 'project-a',
|
|
8
|
+
environment: 'production',
|
|
9
|
+
// 业务构建标识:生产包是压缩产物,没有它就无法把 stack 行号映射回源码
|
|
10
|
+
appVersion: '1.2.3',
|
|
11
|
+
buildId: 'abc1234',
|
|
12
|
+
// 符号化标识;默认由 appVersion + buildId 组合
|
|
13
|
+
release: '1.2.3+abc1234',
|
|
14
|
+
debug: false,
|
|
15
|
+
|
|
16
|
+
reporter: {
|
|
17
|
+
enabled: true,
|
|
18
|
+
position: 'bottom-right',
|
|
19
|
+
theme: 'auto',
|
|
20
|
+
text: '反馈',
|
|
21
|
+
zIndex: 2147483000
|
|
22
|
+
},
|
|
23
|
+
|
|
24
|
+
collect: {
|
|
25
|
+
console: true,
|
|
26
|
+
error: true,
|
|
27
|
+
network: true,
|
|
28
|
+
networkBody: true,
|
|
29
|
+
realtime: true,
|
|
30
|
+
resourceErrors: true,
|
|
31
|
+
environment: true,
|
|
32
|
+
trackIds: true,
|
|
33
|
+
breadcrumbs: true,
|
|
34
|
+
maxBreadcrumbs: 100,
|
|
35
|
+
maxConsoleLogs: 100,
|
|
36
|
+
maxNetworkRecords: 200,
|
|
37
|
+
maxNetworkBytes: 524288,
|
|
38
|
+
maxCloneBytes: 262144,
|
|
39
|
+
requestHeaders: ['authorization', 'x-tenant-id'],
|
|
40
|
+
responseHeaders: ['x-export-version'],
|
|
41
|
+
maxElements: 5,
|
|
42
|
+
eventListenerErrors: true
|
|
43
|
+
},
|
|
44
|
+
|
|
45
|
+
privacy: {
|
|
46
|
+
excludeUrls: [/\/health$/, '/internal/ping'],
|
|
47
|
+
excludeConsolePatterns: [/^debug:/]
|
|
48
|
+
},
|
|
49
|
+
|
|
50
|
+
screenshot: {
|
|
51
|
+
enabled: true,
|
|
52
|
+
auto: true,
|
|
53
|
+
quality: 0.8,
|
|
54
|
+
maxWidth: 1600,
|
|
55
|
+
maxSizeKB: 400
|
|
56
|
+
},
|
|
57
|
+
|
|
58
|
+
transport: {
|
|
59
|
+
timeoutMs: 15000,
|
|
60
|
+
retries: 2,
|
|
61
|
+
headers: { 'X-Client': 'admin-web' },
|
|
62
|
+
offline: { enabled: true, ttlMs: 86400000, maxItems: 20 },
|
|
63
|
+
maxReportsPerSession: 0
|
|
64
|
+
},
|
|
65
|
+
|
|
66
|
+
upload: {
|
|
67
|
+
enabled: true,
|
|
68
|
+
url: '/platform/file/uploadPicture',
|
|
69
|
+
bizId: '1086',
|
|
70
|
+
timeoutMs: 30000
|
|
71
|
+
}
|
|
72
|
+
};
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
## 顶层字段
|
|
76
|
+
|
|
77
|
+
| 字段 | 类型 | 默认 | 说明 |
|
|
78
|
+
|---|---|---|---|
|
|
79
|
+
| `project` | string | — | **必填**。写入日志与 `content` 的 project 字段 |
|
|
80
|
+
| `endpoint` | string | `/go/SupportTools/logreport` | 上报地址,支持绝对或相对 URL,末尾斜杠会被去掉 |
|
|
81
|
+
| `environment` | string | `production` | 环境标识,透传给后端 |
|
|
82
|
+
| `appVersion` | string | `''` | 业务版本号,写入 `ext.app.version` 与 `content` 的 `app=` |
|
|
83
|
+
| `buildId` | string | `''` | 业务构建号(commit 短哈希等),写入 `ext.app.buildId` 与 `content` 的 `build=` |
|
|
84
|
+
| `release` | string | 由 `appVersion` + `buildId` 派生 | 符号化标识,写入 `ext.release` 与 `content` 的 `release=`;sourcemap 上传端按它索引 |
|
|
85
|
+
| `debug` | boolean | `false` | 只控制 SDK 自身告警,不影响采集 |
|
|
86
|
+
| `user` | object \| function | — | 登录用户信息,随每条上报写入 `ext.user`,见下节 |
|
|
87
|
+
| `filtering` | object | — | 错误噪声过滤,见「filtering」 |
|
|
88
|
+
| `hooks` | object | — | `beforeSend` / `beforeBreadcrumb`,见「hooks」 |
|
|
89
|
+
|
|
90
|
+
### user
|
|
91
|
+
|
|
92
|
+
带上「是谁反馈的」,方便在日志平台按账号定位。传对象与传函数都支持:
|
|
93
|
+
|
|
94
|
+
```js
|
|
95
|
+
// 方式一:初始化时传入静态信息
|
|
96
|
+
window.BugTapConfig = {
|
|
97
|
+
project: 'admin',
|
|
98
|
+
user: { id: 'u-100', name: '张三', tenant: 'sh' }
|
|
99
|
+
};
|
|
100
|
+
|
|
101
|
+
// 方式二:传函数,每次提交时求值,自动拿到最新登录态
|
|
102
|
+
window.BugTapConfig = {
|
|
103
|
+
project: 'admin',
|
|
104
|
+
user: () => {
|
|
105
|
+
const store = window.__APP_STORE__;
|
|
106
|
+
return store && store.user ? { id: store.user.id, name: store.user.name } : null;
|
|
107
|
+
}
|
|
108
|
+
};
|
|
109
|
+
|
|
110
|
+
// 方式三:登录 / 退出后运行时更新
|
|
111
|
+
BugTap.setUser({ id: 'u-200', name: '李四' });
|
|
112
|
+
BugTap.setUser(null); // 清空,之后的上报不再带 user
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
约束:
|
|
116
|
+
|
|
117
|
+
- 只保留单层标量字段(string / number / boolean),嵌套对象、数组、null 会被丢弃,值统一转成字符串- 单个值截断到 200 字符,最多 30 个字段
|
|
118
|
+
- 函数形式求值抛错时按「无用户信息」处理,不影响上报
|
|
119
|
+
- `content` 摘要里会带上 `user={id}`(依次回退 `name` → `userId` → `account`),可直接在日志平台全文检索
|
|
120
|
+
- 用户信息**不做脱敏**(它本来就是要定位人的);如果传了手机号之类的字段,建议自行取舍
|
|
121
|
+
|
|
122
|
+
## reporter
|
|
123
|
+
|
|
124
|
+
| 字段 | 类型 | 默认 | 说明 |
|
|
125
|
+
|---|---|---|---|
|
|
126
|
+
| `enabled` | boolean | `true` | 是否显示悬浮按钮。关闭后 `openReporter()` 无效 |
|
|
127
|
+
| `position` | `'bottom-right' \| 'bottom-left'` | `bottom-right` | 悬浮按钮位置 |
|
|
128
|
+
| `theme` | `'light' \| 'dark' \| 'auto'` | `auto` | 面板与按钮主题;`auto` 跟随系统 |
|
|
129
|
+
| `text` | string | `反馈` | 按钮文字,最多 20 字符 |
|
|
130
|
+
| `zIndex` | number | `2147483000` | 宿主 z-index |
|
|
131
|
+
|
|
132
|
+
### reporter.visibility
|
|
133
|
+
|
|
134
|
+
悬浮按钮支持拖动、自动贴边、按条件显隐、手动关闭。按钮使用内置 SVG 图标(气泡 + 感叹号),不依赖字体或外部资源。
|
|
135
|
+
|
|
136
|
+
| 字段 | 类型 | 默认 | 说明 |
|
|
137
|
+
|---|---|---|---|
|
|
138
|
+
| `mode` | `'always' \| 'triggered'` | `always` | `always` 始终展示;`triggered` 只在 URL 或 localStorage 命中时展示 |
|
|
139
|
+
| `queryParam` | string | `bugtap` | URL 参数名,普通 query 与 hash 路由都支持 |
|
|
140
|
+
| `queryValue` | string | `1` | 参数值;设为空字符串表示参数存在即生效。`1` 和 `true` 视为等价 |
|
|
141
|
+
| `closable` | boolean | `true` | 面板底部是否显示「不再显示」入口 |
|
|
142
|
+
|
|
143
|
+
**关闭入口**在反馈面板底部左侧,文字为「不再显示」,点击后隐藏悬浮按钮并清除 localStorage 标记。按钮上不再有独立的关闭图标,避免误触。
|
|
144
|
+
|
|
145
|
+
`always` 与 `triggered` 两种模式都会尊重用户的关闭选择:
|
|
146
|
+
|
|
147
|
+
1. URL 带 `?bugtap=1` → 展示按钮,并写入 `localStorage['bug-tap-enabled'] = '1'`(可用来重新打开已关闭的入口)
|
|
148
|
+
2. URL 显式写 `?bugtap=0` → 隐藏,不改动已有 localStorage
|
|
149
|
+
3. 用户点「不再显示」→ 隐藏按钮,并在 localStorage 写入 `'0'`;刷新后仍然隐藏
|
|
150
|
+
4. 没有 URL 参数且未被关闭时:`always` 模式展示;`triggered` 模式仅在 localStorage 为 `'1'` 时展示
|
|
151
|
+
|
|
152
|
+
示例:
|
|
153
|
+
|
|
154
|
+
```js
|
|
155
|
+
window.BugTapConfig = {
|
|
156
|
+
project: 'demo',
|
|
157
|
+
reporter: {
|
|
158
|
+
visibility: { mode: 'triggered', queryParam: 'debug_feedback', closable: true }
|
|
159
|
+
}
|
|
160
|
+
};
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
访问 `https://your.site/page?debug_feedback=1` 打开按钮,之后同域页面默认都显示,直到用户点关闭。
|
|
164
|
+
|
|
165
|
+
按钮可拖动,松手后自动吸附到最近的左右边缘,位置保存在 `localStorage['bug-tap-fab-position']`,恢复位置时会按当前视口高度重新夹紧,小屏上不会被顶出可视区。
|
|
166
|
+
|
|
167
|
+
## collect
|
|
168
|
+
|
|
169
|
+
| 字段 | 类型 | 默认 | 说明 |
|
|
170
|
+
|---|---|---|---|
|
|
171
|
+
| `console` | boolean | `true` | 采集 `console.log/info/warn/error/debug/trace/assert`;连续相同的行折叠为一条并累加 `count` |
|
|
172
|
+
| `error` | boolean | `true` | 采集 `window.onerror`、`unhandledrejection`,以及 `setTimeout`/`setInterval`/`requestAnimationFrame` / 事件监听回调里的异常 |
|
|
173
|
+
| `network` | boolean | `true` | 采集 fetch / XHR 的 method、URL、status、耗时、失败原因 |
|
|
174
|
+
| `networkBody` | boolean | `true` | 采集请求体与响应体;关闭后 `reqBody`/`resBody` 不出现 |
|
|
175
|
+
| `realtime` | boolean | `true` | 采集 WebSocket / EventSource 的 open / error / close(close code 与 reason) |
|
|
176
|
+
| `resourceErrors` | boolean | `true` | img / script / link / video 等资源加载失败记入 `errors[]`,`type: "resource"` |
|
|
177
|
+
| `trackIds` | boolean | `true` | 带上 tongji 的 `xid` / `subId` / `sessionId`,见「跟踪标识」 |
|
|
178
|
+
| `breadcrumbs` | boolean | `true` | 记录操作时间线(点击 / 输入 / 路由 / 可见性 / 失败请求 / 异常),写入 `ext.breadcrumbs` |
|
|
179
|
+
| `maxBreadcrumbs` | number | `100` | 时间线容量,1–200;默认值与 Sentry、Rollbar 一致 |
|
|
180
|
+
| `environment` | boolean | `true` | 采集 URL、UA、视口、屏幕等信息 |
|
|
181
|
+
| `maxConsoleLogs` | number | `100` | 1–500 |
|
|
182
|
+
| `maxNetworkRecords` | number | `200` | 1–500 |
|
|
183
|
+
| `maxErrors` | number | `50` | 异常条数上限,1–200 |
|
|
184
|
+
| `maxNetworkBytes` | number | `524288` | 所有网络记录(含 body)的总字节预算,8192–8000000;超出时从最旧的整条记录开始丢弃,不切分记录 |
|
|
185
|
+
| `maxCloneBytes` | number | `262144` | 单个响应超过该字节数不 clone,只记状态,1024–5000000 |
|
|
186
|
+
| `requestHeaders` | `string[] \| boolean` | `[]` | 请求头采集白名单,名称不区分大小写;`true` 表示全部。**默认不采,且不做脱敏**,配置 `authorization` / `cookie` 会原样上报 |
|
|
187
|
+
| `responseHeaders` | `string[] \| boolean` | trace 白名单 + `content-type` | 追加响应头白名单;`true` 表示全部可读头。跨域未暴露的头拿不到 |
|
|
188
|
+
| `maxElements` | number | `5` | 单次反馈最多关联的元素快照数,1–20;超出时保留最近添加的 |
|
|
189
|
+
| `eventListenerErrors` | boolean | `true` | 是否包装 `EventTarget.prototype.addEventListener` 采集回调异常;大型页面可关掉,只保留定时器来源标注 |
|
|
190
|
+
|
|
191
|
+
请求体/响应体不做单条截断,而是按 `maxNetworkBytes` 的总预算整体保留:缓冲区满了就丢最旧的整条记录,留下的每条数据都是完整的。若单条记录本身就超过总预算,则不写入该条并计数丢弃。
|
|
192
|
+
|
|
193
|
+
实际读取时仍受 `maxCloneBytes` 约束:超过该值的请求体/响应体只读到上限并追加 `…[truncated]`,避免一条超大 body 把整条记录撑过总预算而连元数据一起被丢弃。
|
|
194
|
+
|
|
195
|
+
`maxCloneBytes` 还会与 `transport.maxItemBytes` 对齐:单条记录最多同时带 `reqBody` 与 `resBody`,二者的读取上限被夹到 `(maxItemBytes - 32KB) / 2`。默认配置(256KB / 800KB)下不触发;只有在把 `maxCloneBytes` 调大到接近或超过 `maxItemBytes` 时才生效,防止单条 `ext` 越过网关上限。
|
|
196
|
+
|
|
197
|
+
请求体/响应体的读取始终是旁路行为:clone 失败(body 已被业务消费)、SSE、二进制响应、超大响应都会自动跳过,不影响业务请求。
|
|
198
|
+
|
|
199
|
+
### 操作时间线
|
|
200
|
+
|
|
201
|
+
`collect.breadcrumbs` 默认开启,记录最近 `maxBreadcrumbs` 条(默认 100)事件,写入 `ext.breadcrumbs`。设计参照 Sentry breadcrumbs、Rollbar telemetry、Bugsnag breadcrumbs:**所有事件进同一条时间线**,按 `t` 排序即可还原因果链。
|
|
202
|
+
|
|
203
|
+
| 类型 | 触发 | 字段 |
|
|
204
|
+
|---|---|---|
|
|
205
|
+
| `click` | 页面点击(捕获阶段) | `selector`(id > data-testid > name > class 的简化选择器)、`text`(前 40 字) |
|
|
206
|
+
| `input` | `change` 事件 | 只记 `selector`,**绝不记输入值**;`password` / `hidden` 直接跳过 |
|
|
207
|
+
| `route` | `pushState` / `replaceState` / `popstate` / `hashchange` | `from`、`to`(path + query) |
|
|
208
|
+
| `visibility` | `visibilitychange` | `state` |
|
|
209
|
+
| `http` | **所有**网络请求(`ok` / status / error 三项决定成功或失败) | `method`、`url`、`status`、`durationMs`、`httpError`、`ref`、`repeat` |
|
|
210
|
+
| `error` | 捕获到异常 | `message`、`count` |
|
|
211
|
+
| `manual` | `BugTap.addBreadcrumb()` | `message`、`data` |
|
|
212
|
+
|
|
213
|
+
约定:
|
|
214
|
+
|
|
215
|
+
- `http` 记录**所有**请求,只存一行摘要;完整记录(含 `reqBody` / `resBody`)在 `network[]`,通过 `ref` 关联
|
|
216
|
+
- **连续相同请求自动折叠**:method + url + status 相同的相邻请求合并为一条并累加 `repeat`,`ref` 指向最近一次。轮询不会吃光时间线容量,`GET /api/heartbeat 200` 连续 100 次只占 1 条(约 100 字节)
|
|
217
|
+
- 折叠只针对「相邻」的相同请求:中间插入任意其他事件就会重新起一条,避免把不同时段的行为混为一谈
|
|
218
|
+
- URL 只保留 `pathname + search`,不记域名
|
|
219
|
+
- 连续相同的 click / route / visibility 也会去重,不刷屏;SDK 自身 UI 产生的交互不计入
|
|
220
|
+
- 带随机参数、折叠不住的轮询用 `privacy.excludeBreadcrumbUrls` 排除
|
|
221
|
+
- 容量满后丢最旧,`ext.collector.breadcrumbEvicted > 0` 表示时间线开头不完整,此时 `content` 会带 `timelineEvicted=N`
|
|
222
|
+
- 100 条全量时间线约 12KB;即使全开也远小于 `maxNetworkBytes` 的 512KB 预算
|
|
223
|
+
- 报告体积超限时,时间线在 `network` / `logs` / `errors` / `screenshots` 之后才参与裁剪,且保留最近 10 条作为下限
|
|
224
|
+
|
|
225
|
+
### 采集器健康状态
|
|
226
|
+
|
|
227
|
+
`ext.collector` 始终上报,用于区分「页面没发生」和「没采到」:
|
|
228
|
+
|
|
229
|
+
| 字段 | 说明 |
|
|
230
|
+
|---|---|
|
|
231
|
+
| `startedAt` | 采集器启动时刻(毫秒时间戳) |
|
|
232
|
+
| `earlyGapMs` | 页面导航到采集启动之间的盲区时长。**大于 0 表示首屏日志与请求不可回溯** |
|
|
233
|
+
| `patched` | `console` / `fetch` / `xhr` / `error` 打点当前是否仍生效;业务后来又包一层时为 `false` |
|
|
234
|
+
| `counts` | 各类采集条数 |
|
|
235
|
+
| `breadcrumbLimit` / `breadcrumbEvicted` | 时间线容量与被挤掉的条数;`evicted > 0` 说明开头不完整 |
|
|
236
|
+
|
|
237
|
+
`earlyGapMs` 大于 0 时会同时拼进 `content`(`earlyGap=Nms`)。
|
|
238
|
+
|
|
239
|
+
SDK 越早引入,`earlyGapMs` 越小。推荐同步 `<script>` 或 module 预加载,避免首屏上下文缺失。
|
|
240
|
+
|
|
241
|
+
### 跟踪标识
|
|
242
|
+
|
|
243
|
+
`collect.trackIds` 默认开启,提交时取业务侧已有的 tongji 身份,写入 `ext.track` 与 `content`:
|
|
244
|
+
|
|
245
|
+
| 字段 | 来源 | 说明 |
|
|
246
|
+
|---|---|---|
|
|
247
|
+
| `xid` | `window.tongji.getXid()` | 用户唯一标识 |
|
|
248
|
+
| `subId` | `window.tongji.getSubId()` | 牛保子账号 id,非牛保域名不返回 |
|
|
249
|
+
| `sessionId` | `window.tongji.getSessionId()` | 会话标识,同时以 `si=` 拼进 `content` |
|
|
250
|
+
|
|
251
|
+
取值顺序(与 `D:\project\web\component\src\js\tongji.js` 的 `getXid` / `getSubId` / `getSessionId` 完全对齐):
|
|
252
|
+
|
|
253
|
+
1. 页面上有 `window.tongji` 就直接用它
|
|
254
|
+
2. `window.tongji` 不存在、返回空值或抛错时,用 `src/core/tongji.ts` 内的复刻实现兜底
|
|
255
|
+
|
|
256
|
+
复刻实现的规则:
|
|
257
|
+
|
|
258
|
+
- `xid`:默认读 cookie `xxid`;`cps.*.(xinhulu|cxmuc).com` 与 `*.kachabao(100).com` 读 `cps_xxid`;`niubao.*` 与 `*.(niubao100|baichuan100).com` 读 `niubao_xxid`
|
|
259
|
+
- `subId`:仅牛保域名读 cookie `niubao_subid`,其余返回空
|
|
260
|
+
- `sessionId`:localStorage 的 `__mcl_session_track__` 与 cookie `_xys_s_id` 双向同步,都没有时生成 32 位随机串;有效期与 tongji 一致(26280000 分钟)
|
|
261
|
+
|
|
262
|
+
不想要这些标识时设 `collect: { trackIds: false }`。
|
|
263
|
+
|
|
264
|
+
## privacy
|
|
265
|
+
|
|
266
|
+
SDK **不做内容脱敏**,`privacy` 只用来缩小采集范围。日志、异常、请求体、响应体都会原样上报,敏感信息的处理由业务侧和后端负责。
|
|
267
|
+
|
|
268
|
+
| 字段 | 类型 | 默认 | 说明 |
|
|
269
|
+
|---|---|---|---|
|
|
270
|
+
| `excludeUrls` | `(string \| RegExp)[]` | `[]` | 在默认静态资源过滤(js/css/图片/字体/媒体等)之上追加;字符串按 URL 包含匹配,命中则整条网络记录不采集 |
|
|
271
|
+
| `excludeConsolePatterns` | `(string \| RegExp)[]` | `[]` | 命中则丢弃该条日志;字符串按包含匹配 |
|
|
272
|
+
| `excludeBreadcrumbUrls` | `(string \| RegExp)[]` | `[]` | 命中则不记 `http` 面包屑,但**不影响** `network[]` 的完整记录。用于屏蔽带随机参数的轮询(如 `/poll?t=123`),这类请求无法靠「相邻相同」折叠 |
|
|
273
|
+
|
|
274
|
+
如果需要避免采集到带凭据的请求,用 `excludeUrls` 把它们排除,例如:
|
|
275
|
+
|
|
276
|
+
```js
|
|
277
|
+
privacy: {
|
|
278
|
+
excludeUrls: [/\/api\/auth\//, '/api/pay'],
|
|
279
|
+
excludeConsolePatterns: [/^debug:/]
|
|
280
|
+
}
|
|
281
|
+
```
|
|
282
|
+
|
|
283
|
+
## screenshot
|
|
284
|
+
|
|
285
|
+
| 字段 | 类型 | 默认 | 说明 |
|
|
286
|
+
|---|---|---|---|
|
|
287
|
+
| `enabled` | boolean | `true` | 关闭后不截图,也不显示截图操作 |
|
|
288
|
+
| `auto` | boolean | `true` | 打开面板时自动截图 |
|
|
289
|
+
| `quality` | number | `0.8` | JPEG 质量,0.1–1 |
|
|
290
|
+
| `maxWidth` | number | `1600` | 输出最长边 |
|
|
291
|
+
| `maxSizeKB` | number | `400` | 单张上限,超出会自动降质量、降分辨率 |
|
|
292
|
+
| `scriptUrl` | string | `''` | 截图库地址。`''` 表示按「与主包同目录」推断;支持相对路径与绝对 URL。ESM / CJS 产物下配了它就不再 `import('html2canvas-pro')`,改为注入外部脚本 |
|
|
293
|
+
|
|
294
|
+
**什么时候必须配 `scriptUrl`**:
|
|
295
|
+
|
|
296
|
+
- 主包与 `bug-tap-screenshot.min.js` 不在同一目录
|
|
297
|
+
- 主包被内联进 HTML,或经 `/assets/index-xxxx.js` 这类动态文件名加载,`document.currentScript` 推断不到原始地址
|
|
298
|
+
- 主包被业务打包器合并进自己的 chunk
|
|
299
|
+
|
|
300
|
+
地址解析顺序:`scriptUrl` → 主包同目录 → 当前目录下的文件名。相对路径按当前页面 URL 解析。
|
|
301
|
+
|
|
302
|
+
## transport
|
|
303
|
+
|
|
304
|
+
| 字段 | 类型 | 默认 | 说明 |
|
|
305
|
+
|---|---|---|---|
|
|
306
|
+
| `timeoutMs` | number | `15000` | 单次请求超时,1000–60000 |
|
|
307
|
+
| `retries` | number | `2` | 仅网络错误、429、5xx 重试;4xx 不重试 |
|
|
308
|
+
| `headers` | Record<string,string> | `{}` | 追加到上报请求头 |
|
|
309
|
+
| `maxItemBytes` | number | `800000` | 单条 LogItem 的 ext 上限,超出拆成多条同批提交 |
|
|
310
|
+
| `totalTimeoutMs` | number | `30000` | 整次提交的总时长上限(含重试与退避),3000–60000 |
|
|
311
|
+
| `maxConcurrent` | number | `10` | 同时进行中的提交数上限,超出立即返回「正在提交中」,1–50 |
|
|
312
|
+
| `logLevel` | `1 \| 2 \| 3` | 按 severity 映射 | 强制指定 LogItem 的 `logLevel`。用户主动反馈不是运行时告警,设为 `1` 可避免触发日志平台的 warn/error 告警规则 |
|
|
313
|
+
| `offline.enabled` | boolean | `true` | 提交最终失败时写入本地补偿队列(IndexedDB),恢复后自动重放 |
|
|
314
|
+
| `offline.ttlMs` | number | 24h | 待发记录保留时长 |
|
|
315
|
+
| `offline.maxItems` | number | `20` | 最多保留多少条待发记录 |
|
|
316
|
+
| `maxReportsPerSession` | number | `0` | 每会话最多成功提交多少次,0 表示不限制 |
|
|
317
|
+
|
|
318
|
+
### 重试与限流
|
|
319
|
+
|
|
320
|
+
- 429 响应会读 `Retry-After`(秒数或 HTTP 日期),按服务端给出的节奏等待;没有该头时退回指数退避(1s → 3s,带随机抖动)
|
|
321
|
+
- 整次提交有 `totalTimeoutMs` 上限:剩余预算不够再等一轮时直接返回超时,不会让用户一直看到「提交中…」
|
|
322
|
+
- 单次请求超时会被剩余总预算进一步夹紧
|
|
323
|
+
- 请求带 `keepalive`(仅在待发总量 ≤ 60KB 且并发 < 15 时开启,与浏览器 64KiB 总量限制对齐)。总量按 **UTF-8 字节**计算,不是 JS 字符数
|
|
324
|
+
|
|
325
|
+
### 离线补偿队列
|
|
326
|
+
|
|
327
|
+
提交在重试后仍然失败(网络错误 / 超时 / 429 / 5xx)时,SDK 把这批 `LogItem` JSON 原样写入 IndexedDB:
|
|
328
|
+
|
|
329
|
+
- 主键是 `clientReportId`,同一条反馈重复入队只保留一份
|
|
330
|
+
- 默认保留 24 小时、最多 20 条(`transport.offline`)
|
|
331
|
+
- 下次初始化、`online` 事件、`visibilitychange` 或手动 `BugTap.flush()` 时重放
|
|
332
|
+
- 页面隐藏时用 `sendBeacon` 兜底(单条 ≤ 60KB)
|
|
333
|
+
- 协议错误 / 4xx 不进入队列(重发也不会成功);重放时被 4xx 拒绝的条目会被删除
|
|
334
|
+
|
|
335
|
+
因此弱网提交对用户表现为「已保存,恢复后自动提交」,而不是要求重复填写。
|
|
336
|
+
|
|
337
|
+
## filtering
|
|
338
|
+
|
|
339
|
+
错误噪声过滤,语义对齐 Sentry 的 `eventFilters`。
|
|
340
|
+
|
|
341
|
+
| 字段 | 类型 | 默认 | 说明 |
|
|
342
|
+
|---|---|---|---|
|
|
343
|
+
| `ignoreErrors` | `Array<string \| RegExp>` | `[]` | 消息命中即不采集(字符串按包含,正则按 `test`) |
|
|
344
|
+
| `denyUrls` | `Array<string \| RegExp>` | `[]` | 命中**抛出点脚本地址**即不采集 |
|
|
345
|
+
| `allowUrls` | `Array<string \| RegExp>` | `[]` | 非空时必须命中脚本地址,否则不采集 |
|
|
346
|
+
| `disableErrorDefaults` | boolean | `false` | 关闭内置默认表(`Script error.`、ResizeObserver 等 10 条) |
|
|
347
|
+
|
|
348
|
+
`denyUrls` / `allowUrls` 比的是异常栈里**抛出点脚本的地址**,不是页面地址——同一个页面里第三方 SDK 抛的错可以据此精确过滤。用户配置的规则排在内置默认表之前,`disableErrorDefaults` 只关内置表。
|
|
349
|
+
|
|
350
|
+
## hooks
|
|
351
|
+
|
|
352
|
+
业务侧介入点,语义对齐 Sentry 的 `beforeSend` / `beforeBreadcrumb`。返回 `null` 表示丢弃,返回值替换原数据;钩子抛错时按「不修改」放行,不会因为业务 bug 丢掉整条反馈。
|
|
353
|
+
|
|
354
|
+
```ts
|
|
355
|
+
{
|
|
356
|
+
hooks: {
|
|
357
|
+
// 提交前改写或丢弃整份报告;支持返回 Promise
|
|
358
|
+
beforeSend(report) {
|
|
359
|
+
if (report.description.includes('内部测试')) return null;
|
|
360
|
+
report.title = `[${report.environment}] ${report.title}`;
|
|
361
|
+
return report;
|
|
362
|
+
},
|
|
363
|
+
// 逐条改写或丢弃时间线条目
|
|
364
|
+
beforeBreadcrumb(crumb) {
|
|
365
|
+
return crumb.url?.includes('/poll') ? null : crumb;
|
|
366
|
+
}
|
|
367
|
+
}
|
|
368
|
+
}
|
|
369
|
+
```
|
|
370
|
+
|
|
371
|
+
`beforeBreadcrumb` 在去重之前执行,被改写后的条目才参与「相邻相同」判断。
|
|
372
|
+
|
|
373
|
+
`beforeSend` 允许返回 Promise;异步钩子只影响提交链路,`getReport()` 是同步接口,遇到 Promise 会明确抛错。
|
|
374
|
+
|
|
375
|
+
## upload
|
|
376
|
+
|
|
377
|
+
提交前把截图上传成 URL,避免 base64 撑大日志。
|
|
378
|
+
|
|
379
|
+
| 字段 | 类型 | 默认 | 说明 |
|
|
380
|
+
|---|---|---|---|
|
|
381
|
+
| `enabled` | boolean | `true` | 关闭后截图仍以 base64 内联在 `ext.screenshots` |
|
|
382
|
+
| `url` | string | `/platform/file/uploadPicture` | 公司统一图片上传接口,契约同 `actui2` FileUpload |
|
|
383
|
+
| `bizId` | string | `'1086'` | 透传给上传接口的 `bizid`(业务类型,接口必填) |
|
|
384
|
+
| `timeoutMs` | number | `30000` | 上传超时,1000–120000 |
|
|
385
|
+
|
|
386
|
+
上传失败会自动降级为内联 base64,不阻断报告提交。上传请求带 `credentials: 'include'`,需要业务域名下已有登录态。
|
|
387
|
+
|
|
388
|
+
## 运行时修改
|
|
389
|
+
|
|
390
|
+
`BugTap.setConfig(patch)` 会:
|
|
391
|
+
|
|
392
|
+
1. 深合并配置并重新校验
|
|
393
|
+
2. 若 `collect` / `privacy` / `endpoint` 变化,重建采集器(**已采集的缓冲会清空**)
|
|
394
|
+
3. 重建上报 UI(已打开的面板会关闭)
|
|
395
|
+
|
|
396
|
+
仅修改 `reporter.text`、`screenshot` 等字段时,采集缓冲保留。
|
package/package.json
CHANGED
|
@@ -1,6 +1,99 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@xysfe/bug-tap",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.1.1",
|
|
4
|
+
"description": "可嵌入网页的调试与 Bug 上报 SDK:独立悬浮上报入口,自动采集 Console、JS 异常、Network 与环境信息",
|
|
5
|
+
"repository": {
|
|
6
|
+
"type": "git",
|
|
7
|
+
"url": "git+ssh://git@gitlab.xinhulu.com/mucfe/bugtap.git"
|
|
8
|
+
},
|
|
9
|
+
"homepage": "https://gitlab.xinhulu.com/mucfe/bugtap",
|
|
10
|
+
"bugs": {
|
|
11
|
+
"url": "https://gitlab.xinhulu.com/mucfe/bugtap/-/issues"
|
|
12
|
+
},
|
|
13
|
+
"type": "module",
|
|
14
|
+
"main": "./dist/bug-tap.cjs",
|
|
15
|
+
"module": "./dist/bug-tap.js",
|
|
16
|
+
"types": "./dist/index.d.ts",
|
|
17
|
+
"unpkg": "./dist/bug-tap.min.js",
|
|
18
|
+
"jsdelivr": "./dist/bug-tap.min.js",
|
|
19
|
+
"exports": {
|
|
20
|
+
".": {
|
|
21
|
+
"types": "./dist/index.d.ts",
|
|
22
|
+
"import": "./dist/bug-tap.js",
|
|
23
|
+
"require": "./dist/bug-tap.cjs"
|
|
24
|
+
},
|
|
25
|
+
"./global": {
|
|
26
|
+
"types": "./dist/index.d.ts",
|
|
27
|
+
"default": "./dist/bug-tap.min.js"
|
|
28
|
+
},
|
|
29
|
+
"./vue": {
|
|
30
|
+
"types": "./dist/vue.d.ts",
|
|
31
|
+
"import": "./dist/bug-tap-vue.js",
|
|
32
|
+
"require": "./dist/bug-tap-vue.cjs"
|
|
33
|
+
},
|
|
34
|
+
"./package.json": "./package.json"
|
|
35
|
+
},
|
|
36
|
+
"files": [
|
|
37
|
+
"dist",
|
|
38
|
+
"docs",
|
|
39
|
+
"README.md",
|
|
40
|
+
"CHANGELOG.md",
|
|
41
|
+
"THIRD_PARTY_NOTICES.md",
|
|
42
|
+
"LICENSE"
|
|
43
|
+
],
|
|
44
|
+
"scripts": {
|
|
45
|
+
"build": "vite build --mode iife && vite build --mode iife-screenshot && vite build --mode iife-plugins && vite build --mode esm && vite build --mode esm-vue && vite build --mode cjs && vite build --mode cjs-vue && vue-tsc --emitDeclarationOnly --declaration --outDir dist",
|
|
46
|
+
"dev": "vite",
|
|
47
|
+
"dev:lib": "vite build --mode iife --watch",
|
|
48
|
+
"typecheck": "vue-tsc --noEmit",
|
|
49
|
+
"test": "vitest run",
|
|
50
|
+
"test:watch": "vitest",
|
|
51
|
+
"test:e2e": "playwright test",
|
|
52
|
+
"mock": "node demo/mock-server.mjs",
|
|
53
|
+
"check:dist": "node scripts/check-dist.mjs",
|
|
54
|
+
"verify": "npm run typecheck && npm test && npm run build && npm run check:dist",
|
|
55
|
+
"prepublishOnly": "npm run build && npm run check:dist"
|
|
56
|
+
},
|
|
57
|
+
"keywords": [
|
|
58
|
+
"bug-tap",
|
|
59
|
+
"feedback",
|
|
60
|
+
"debug",
|
|
61
|
+
"console",
|
|
62
|
+
"network",
|
|
63
|
+
"screenshot"
|
|
64
|
+
],
|
|
65
|
+
"license": "MIT",
|
|
66
|
+
"engines": {
|
|
67
|
+
"node": ">=18"
|
|
68
|
+
},
|
|
69
|
+
"dependencies": {
|
|
70
|
+
"css-selector-generator": "^3.9.4",
|
|
71
|
+
"html2canvas-pro": "^1.6.7"
|
|
72
|
+
},
|
|
73
|
+
"peerDependencies": {
|
|
74
|
+
"vue": ">=3.2 <4"
|
|
75
|
+
},
|
|
76
|
+
"peerDependenciesMeta": {
|
|
77
|
+
"vue": {
|
|
78
|
+
"optional": true
|
|
79
|
+
}
|
|
80
|
+
},
|
|
81
|
+
"devDependencies": {
|
|
82
|
+
"@playwright/test": "^1.65.0",
|
|
83
|
+
"@types/node": "^22.0.0",
|
|
84
|
+
"@vitejs/plugin-vue": "^6.0.11",
|
|
85
|
+
"jsdom": "^25.0.1",
|
|
86
|
+
"react": "^18.3.1",
|
|
87
|
+
"react-dom": "^18.3.1",
|
|
88
|
+
"typescript": "^5.7.0",
|
|
89
|
+
"vite": "^7.3.7",
|
|
90
|
+
"vitest": "^3.2.4",
|
|
91
|
+
"vue": "^3.5.45",
|
|
92
|
+
"vue-router": "^4.6.5",
|
|
93
|
+
"vue-tsc": "^2.2.12",
|
|
94
|
+
"vue2": "npm:vue@^2.7.16"
|
|
95
|
+
},
|
|
96
|
+
"publishConfig": {
|
|
97
|
+
"access": "public"
|
|
98
|
+
}
|
|
99
|
+
}
|