@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.
Files changed (76) hide show
  1. package/CHANGELOG.md +75 -0
  2. package/LICENSE +21 -0
  3. package/README.md +461 -2
  4. package/THIRD_PARTY_NOTICES.md +39 -0
  5. package/dist/bug-tap-screenshot.min.js +10 -0
  6. package/dist/bug-tap-screenshot.min.js.map +1 -0
  7. package/dist/bug-tap-vue.cjs +2 -0
  8. package/dist/bug-tap-vue.cjs.map +1 -0
  9. package/dist/bug-tap-vue.js +106 -0
  10. package/dist/bug-tap-vue.js.map +1 -0
  11. package/dist/bug-tap-vue.min.js +2 -0
  12. package/dist/bug-tap-vue.min.js.map +1 -0
  13. package/dist/bug-tap.cjs +2 -0
  14. package/dist/bug-tap.cjs.map +1 -0
  15. package/dist/bug-tap.js +13 -0
  16. package/dist/bug-tap.js.map +1 -0
  17. package/dist/bug-tap.min.js +508 -0
  18. package/dist/bug-tap.min.js.map +1 -0
  19. package/dist/config.d.ts +14 -0
  20. package/dist/core/body.d.ts +30 -0
  21. package/dist/core/breadcrumbs.d.ts +85 -0
  22. package/dist/core/browser-api-errors.d.ts +55 -0
  23. package/dist/core/byte-buffer.d.ts +43 -0
  24. package/dist/core/collector.d.ts +34 -0
  25. package/dist/core/console-collector.d.ts +23 -0
  26. package/dist/core/env-collector.d.ts +16 -0
  27. package/dist/core/error-collector.d.ts +48 -0
  28. package/dist/core/error-noise.d.ts +43 -0
  29. package/dist/core/network-collector.d.ts +97 -0
  30. package/dist/core/network-record.d.ts +19 -0
  31. package/dist/core/resource-timing.d.ts +28 -0
  32. package/dist/core/ring-buffer.d.ts +22 -0
  33. package/dist/core/selector.d.ts +3 -0
  34. package/dist/core/serialize.d.ts +5 -0
  35. package/dist/core/tongji.d.ts +14 -0
  36. package/dist/core/user.d.ts +9 -0
  37. package/dist/index-BbRyzCzY.cjs +488 -0
  38. package/dist/index-BbRyzCzY.cjs.map +1 -0
  39. package/dist/index-D_ygxzgY.js +4685 -0
  40. package/dist/index-D_ygxzgY.js.map +1 -0
  41. package/dist/index.d.ts +33 -0
  42. package/dist/integrations.d.ts +26 -0
  43. package/dist/panel-mount-BOOHHmMb.js +499 -0
  44. package/dist/panel-mount-BOOHHmMb.js.map +1 -0
  45. package/dist/panel-mount-CjRBibNV.cjs +2 -0
  46. package/dist/panel-mount-CjRBibNV.cjs.map +1 -0
  47. package/dist/screenshot-global.d.ts +14 -0
  48. package/dist/sdk.d.ts +76 -0
  49. package/dist/transport/log-item.d.ts +2 -0
  50. package/dist/transport/offline-queue.d.ts +48 -0
  51. package/dist/transport/payload.d.ts +15 -0
  52. package/dist/transport/transport.d.ts +57 -0
  53. package/dist/transport/upload.d.ts +8 -0
  54. package/dist/types.d.ts +459 -0
  55. package/dist/ui/element-picker.d.ts +51 -0
  56. package/dist/ui/floating-button.d.ts +43 -0
  57. package/dist/ui/icons.d.ts +1 -0
  58. package/dist/ui/panel-mount.d.ts +20 -0
  59. package/dist/ui/panel.vue.d.ts +15 -0
  60. package/dist/ui/screenshot-loader-shared.d.ts +2 -0
  61. package/dist/ui/screenshot-loader.d.ts +14 -0
  62. package/dist/ui/screenshot-loader.iife.d.ts +16 -0
  63. package/dist/ui/screenshot.d.ts +20 -0
  64. package/dist/ui/shadow-host.d.ts +16 -0
  65. package/dist/ui/styles.css.d.ts +1 -0
  66. package/dist/ui/visibility.d.ts +25 -0
  67. package/dist/utils/match.d.ts +2 -0
  68. package/dist/utils/ua.d.ts +6 -0
  69. package/dist/utils/url.d.ts +2 -0
  70. package/dist/vue-global.d.ts +21 -0
  71. package/dist/vue.d.ts +49 -0
  72. package/docs/api.md +257 -0
  73. package/docs/backend-api.md +401 -0
  74. package/docs/bundler.md +122 -0
  75. package/docs/config.md +396 -0
  76. package/package.json +97 -4
@@ -0,0 +1,401 @@
1
+ # 上报接口契约
2
+
3
+ SDK 把用户反馈写入公司日志网关,再由网关落到阿里云 SLS。前端不接触 GitLab、Token 或仓库路径,也不创建 Issue。
4
+
5
+ - 默认地址:`/go/SupportTools/logreport`(同源,无需鉴权)
6
+ - 可通过 `endpoint` 覆盖,支持相对路径与绝对 URL
7
+ - 请求与响应均为 UTF-8 JSON
8
+
9
+ ## 1. 请求
10
+
11
+ ```
12
+ POST {endpoint}
13
+ Content-Type: application/json
14
+
15
+ [ LogItem, ... ]
16
+ ```
17
+
18
+ 一次提交生成一个单元素数组。字段与 `xys-util` 的 `RealTimeReport`、`kachabao` 客户端保持一致。
19
+
20
+ ### LogItem
21
+
22
+ | 字段 | 类型 | 必填 | 说明 |
23
+ |---|---|---|---|
24
+ | `timestamp` | number | 是 | 毫秒时间戳 |
25
+ | `logLevel` | number | 是 | `1` info / `2` warn / `3` error;可用 `transport.logLevel` 强制覆盖,见下文 |
26
+ | `userAgent` | string | 是 | `"H5, " + navigator.userAgent`;取不到时下发 `unknown userAgent` |
27
+ | `url` | string | 是 | 页面 URL,取 `page.url`,为空时回退 `location.href` |
28
+ | `content` | string | 是 | **字符串**,人类可读摘要,见下文 |
29
+ | `traceId` | string | 是 | 32 位字母数字,由 `clientReportId` 去掉非字母数字字符后截断/补 `0` 得到 |
30
+ | `ext` | string | 是 | **字符串**,`JSON.stringify` 后的完整报告;空值用 `""`,不能 `null` |
31
+
32
+ `content` 与 `ext` 都不能传对象。网关按 `string` 反序列化,传对象会导致整批请求失败。
33
+
34
+ ### content 格式
35
+
36
+ ```
37
+ 【Bug反馈】{title} | {description} | project={project} env={environment} release={release} fp={fingerprint} reportId={clientReportId}
38
+ ```
39
+
40
+ - `title` 截断到 200 字符
41
+ - `description` 摘要截断到 500 字符,超出部分以 `…` 结尾
42
+ - 空白字符折叠为单个空格
43
+ - 单行反馈的 `title` 由 `description` 首行派生,两者相同时 `content` 只保留一份(`ext` 里仍是两个字段)
44
+ - `release` 用于关联 sourcemap;`fp` 是后端分组用的稳定指纹(同类异常得到同一个值)
45
+ - `tags` 的前 5 个以 `key=value` 形式拼在 `reportId` 前,便于全文检索
46
+ - 全文检索依赖该字段,标题、描述、project、environment 都会出现在这里
47
+
48
+ ### logLevel 映射
49
+
50
+ | `severity` | `logLevel` |
51
+ |---|---|
52
+ | `normal` | `2` |
53
+ | `serious` / `fatal` / 未填 | `3` |
54
+
55
+ 这是**有损**映射:`serious`、`fatal`、未填都压成 `3`,原始粒度保留在 `ext.severity`。所以 `logLevel` 不是冗余字段,而是给日志平台做告警分级用。
56
+
57
+ 用户主动反馈本质不是运行时告警。若日志平台对 `warn` / `error` 配了告警规则,每次反馈都会推一条。此时用 `transport.logLevel` 强制指定:
58
+
59
+ ```js
60
+ BugTap.init({
61
+ project: 'admin',
62
+ transport: { logLevel: 1 } // 固定在 info,不触发告警
63
+ });
64
+ ```
65
+
66
+ 不填时按上表映射;传入非 `1`/`2`/`3` 的值会被忽略。
67
+
68
+ ### ext 结构
69
+
70
+ ```jsonc
71
+ {
72
+ "project": "demo-project",
73
+ "environment": "production",
74
+ "sdkVersion": "0.1.0",
75
+ "clientReportId": "5f0c2e2a-...",
76
+ "release": "1.2.3+abc1234",
77
+ "fingerprint": "bt-1a2b3c4d",
78
+ // errors[] 里真正的崩溃下标;资源 404 / 手动消息通常排在前面
79
+ "primaryErrorIndex": 0,
80
+
81
+ "title": "导出按钮没有反应",
82
+ "description": "1. 打开订单列表\n2. 点击导出\n3. 无反应",
83
+ "category": "functional",
84
+ "severity": "serious",
85
+ "contact": "zhangsan",
86
+
87
+ "tags": { "tenant": "sh", "feature": "order-export" },
88
+ "extra": { "orderId": "O-20261117-001" },
89
+ "contexts": { "cart": { "count": 3 } },
90
+
91
+ "app": {
92
+ "version": "1.2.3",
93
+ "buildId": "abc1234"
94
+ },
95
+
96
+ "collector": {
97
+ "startedAt": 1730000001200,
98
+ "earlyGapMs": 1200,
99
+ "patched": { "console": true, "fetch": true, "xhr": true, "error": true },
100
+ "counts": { "logs": 12, "errors": 1, "network": 8 }
101
+ },
102
+
103
+ "breadcrumbs": [
104
+ { "t": 1730000005000, "type": "click", "selector": "button#export", "text": "导出订单" },
105
+ { "t": 1730000005500, "type": "input", "selector": "input#date-range" },
106
+ { "t": 1730000006000, "type": "route", "from": "/list", "to": "/detail" },
107
+ { "t": 1730000006500, "type": "http", "method": "POST", "url": "/api/export?type=xlsx", "status": 500, "durationMs": 382, "ref": "n1" },
108
+ { "t": 1730000006900, "type": "visibility", "state": "hidden" },
109
+ { "t": 1730000007000, "type": "error", "message": "TypeError: cannot read properties of null", "count": 1 }
110
+ ],
111
+
112
+ "page": {
113
+ "referrer": "https://admin.example.com/",
114
+ "title": "订单列表"
115
+ },
116
+
117
+ "browser": {
118
+ "userAgent": "Mozilla/5.0 ...",
119
+ "platform": "Win32",
120
+ "browser": "Chrome",
121
+ "browserVersion": "131.0.0.0",
122
+ "os": "Windows",
123
+ "screenWidth": 1920,
124
+ "screenHeight": 1080,
125
+ "viewportWidth": 1280,
126
+ "viewportHeight": 800,
127
+ "dpr": 1.1,
128
+ "device": "1920*1080 @ 1.1x",
129
+ "language": "zh-CN",
130
+ "timezone": "Asia/Shanghai"
131
+ },
132
+
133
+ "user": {
134
+ "id": "u-100",
135
+ "name": "张三"
136
+ },
137
+
138
+ "track": {
139
+ "xid": "abc123",
140
+ "subId": "sub-9",
141
+ "sessionId": "d8f3...32位"
142
+ },
143
+
144
+ "logs": [
145
+ {
146
+ "level": "error",
147
+ "timestamp": 1730000000000,
148
+ "args": ["请求失败", "{status: 500}"],
149
+ "text": "请求失败 {status: 500}"
150
+ }
151
+ ],
152
+
153
+ "errors": [
154
+ {
155
+ "type": "error",
156
+ "message": "TypeError: ...",
157
+ "filename": "https://admin.example.com/assets/app.js",
158
+ "lineno": 120,
159
+ "colno": 8,
160
+ "stack": "TypeError: ...\n at ...",
161
+ "context": { "source": "vue", "info": "render" },
162
+ "timestamp": 1730000000000,
163
+ "count": 1
164
+ },
165
+ {
166
+ "type": "resource",
167
+ "message": "Resource load failed: <img> /assets/missing.png",
168
+ "filename": "/assets/missing.png",
169
+ "timestamp": 1730000000100,
170
+ "count": 1
171
+ }
172
+ ],
173
+
174
+ "network": [
175
+ {
176
+ "id": "n1",
177
+ "type": "fetch",
178
+ "method": "POST",
179
+ "url": "https://api.example.com/order/export",
180
+ "status": 500,
181
+ "ok": false,
182
+ "durationMs": 382,
183
+ "error": null,
184
+ "reqBody": "{\"orderIds\":[1,2,3],\"type\":\"xlsx\"}",
185
+ "resBody": "{\"code\":500,\"message\":\"导出服务超时\"}",
186
+ "contentType": "application/json; charset=utf-8",
187
+ "reqHeaders": { "authorization": "Bearer ...", "x-tenant-id": "sh" },
188
+ "resHeaders": { "x-request-id": "req-8f2c1a", "traceparent": "00-4bf9...-00f0...-01", "x-export-version": "v3" },
189
+ "timing": { "dns": 0, "connect": 12, "ttfb": 340, "download": 30, "total": 382 },
190
+ "timestamp": 1730000000000
191
+ }
192
+ ],
193
+
194
+ "screenshots": [
195
+ {
196
+ "mime": "image/jpeg",
197
+ "url": "https://img.example.com/2026/11/bug-report-xxx.jpg",
198
+ "width": 1280,
199
+ "height": 800,
200
+ "size": 182000,
201
+ "source": "auto",
202
+ "capturedAt": 1730000010000
203
+ }
204
+ ],
205
+
206
+ "networkDropped": {
207
+ "droppedCount": 0, // 单条超预算、未写入采集缓冲的记录数
208
+ "droppedBytes": 0,
209
+ "evictedCount": 3, // 为腾空间被淘汰的旧记录数
210
+ "evictedBytes": 24576,
211
+ "trimmedCount": 0, // 提交前被体积裁剪掉的记录数
212
+ "totalCount": 53, // 丢弃前采集到的总数;null 表示未采集网络
213
+ "sentCount": 50 // 实际进入本次上报的记录数
214
+ }
215
+ }
216
+ ```
217
+
218
+ `networkDropped` 为 `totalCount === sentCount` 且各计数为 0 时,表示网络数据完整。
219
+
220
+ `collect.network=false`(未采集网络)时 `totalCount` 为 `null`、`sentCount` 为 `0`,此时 `network: []` 的含义是「未采集」而不是「页面没发请求」;`content` 末尾会带 `networkDisabled` 标记。
221
+
222
+ `undefined` 字段会被 `JSON.stringify` 丢弃,`logs` / `errors` / `network` 可能为空数组,`screenshots` 可能不存在。
223
+
224
+ 补充约定:
225
+
226
+ - `browser.dpr` 归一化到 2 位小数(`devicePixelRatio` 在缩放场景下会带浮点噪声,如 `1.100000023841858`),`device` 使用同一个归一化值,保证同一设备在日志平台聚合到同一个键
227
+ - `page.url` 与顶层 `url` 相同时不下发(顶层 `url` 的取值就是 `page.url`,为空时才回退 `location.href`);要用页面地址请取顶层 `url`
228
+ - `page.referrer` 与 `page.url` 相同时不下发(刷新页面的常见场景)
229
+ - `errors[].message` 去掉了 `Uncaught ` 前缀(`type` 已标明这是未捕获异常,`stack` 首行也带有错误类型)
230
+ - `errors[].stack` 最多保留 20 帧,`errors[].cause` 透传 `Error.cause`
231
+ - `screenshots[].capturedAt` 是截图时刻:`source: "auto"` 拍的是**打开面板那一刻**,不是错误现场
232
+
233
+ ### 排障字段的语义
234
+
235
+ 这几个字段专门用于判断「数据缺失是没发生,还是没采到」,排查时先看它们:
236
+
237
+ | 字段 | 怎么用 |
238
+ |---|---|
239
+ | `collector.earlyGapMs` | 页面导航到采集启动之间的盲区毫秒数。**大于 0 说明首屏的日志与请求不可回溯**,此时 `logs` / `network` 为空不代表页面没动作 |
240
+ | `collector.patched` | 各项打点当前是否仍生效。业务后来又包了一层 console / fetch 时为 `false`,说明这段数据不可信 |
241
+ | `collector.counts` | 采集到的条数,与 `logs` / `network` 长度一致,便于快速比对 |
242
+ | `collector.breadcrumbEvicted` | 大于 0 说明时间线开头被挤掉,因果链可能不完整 |
243
+ | `app.version` / `app.buildId` | 生产包是压缩产物,没有它就无法把 `lineno` 映射回源码 |
244
+ | `breadcrumbs` | 同一条时间线里的 click / input / route / visibility / 失败请求 / 异常。按 `t` 排序即可还原因果链:点按钮 → 请求 500 → 抛异常。`http` 条目用 `ref` 关联 `network[].id`(记录被裁剪时 `ref` 会被清除并置 `httpError: "[record trimmed]"`) |
245
+ | `screenshots[].capturedAt` | 与 `errors[].timestamp` 对比:auto 截图通常晚于错误,不能当作错误现场 |
246
+
247
+ `earlyGapMs` 大于 0 时,`content` 末尾会带 `earlyGap=Nms`,可在日志平台直接搜出「首屏上下文不完整」的反馈;配置了 `appVersion` / `buildId` 时还会带 `app=` / `build=`。
248
+
249
+ ### breadcrumbs 与 network 的分工
250
+
251
+ 两者刻意保留冗余,不合并:
252
+
253
+ | | `breadcrumbs` | `network` |
254
+ |---|---|---|
255
+ | 范围 | **所有**请求(连续相同请求折叠) | **所有**请求 |
256
+ | 容量模型 | 条数(`maxBreadcrumbs`,默认 100) | 字节预算(`maxNetworkBytes`,默认 512KB) |
257
+ | 内容 | 一行摘要(method / url / status / ref / repeat) | 完整记录,含 `reqBody` / `resBody` |
258
+ | 作用 | 还原因果顺序 | 提供请求内容与「请求压根没发」的证据 |
259
+
260
+ `http` 条目里的 `method` / `url` / `status` 与 `network[]` 同名字段重复是**有意的反规范化**:时间线要能被独立阅读和排序,不能每条都去 `network[]` 里 join。详情(headers、body)只在 `network[]` 里有一份。
261
+
262
+ 两类边界的处理:
263
+
264
+ - 相邻的相同请求(method + url + status 相同)折叠为一条并累加 `repeat`,`ref` 指向最近一次;轮询不会挤掉用户操作
265
+ - 记录被体积裁剪丢弃时,仍保留时间线条目(因果位置不能断),但清掉 `ref` 并置 `httpError: "[record trimmed]"`
266
+ - `collect.network=false` 时时间线也不记 `http`,`ref` 不会出现悬空
267
+
268
+ `network[]` 中的 `reqBody` / `resBody` 只在下述情况出现:
269
+
270
+ - `collect.networkBody` 开启(默认)
271
+ - 响应不是 SSE、不是二进制类型、大小未超过 `maxCloneBytes`
272
+ - clone 未失败(业务尚未读取 body)
273
+ - XHR 的 `responseType` 为 `''` / `text` / `json`
274
+
275
+ body 不做单条截断,而是按 `collect.maxNetworkBytes`(默认 512KB)的总预算保留整条记录,缓冲区满时丢弃最旧的记录。
276
+
277
+ `resHeaders` 只收录白名单响应头(默认 trace 白名单 + `content-type`,可用 `collect.responseHeaders` 追加;`true` 表示全部可读头);`reqHeaders` 由 `collect.requestHeaders` 白名单控制,默认不采。注意 SDK 不做脱敏,配置 `authorization` / `cookie` 时会原样上报。
278
+
279
+ `network[]` 在每个 `LogItem` 内按 `timestamp` 升序排列;分片本身按「失败请求优先」装载,所以跨 `part` 合并时需要自行按 `timestamp` 排序。`part` 字段给出 `{ index, total }`。
280
+
281
+ JS 无法获取 Cookie、HTTP 版本、IP、缓存命中等浏览器内部字段,跨域头也受 CORS 限制,因此这些字段只能还原诊断所需的 HAR 核心信息,不是完整 HAR。
282
+
283
+ `network[].type` 还可能是 `websocket` / `eventsource`:连接建立时先写一条元数据(`ok` 未定),open 时置 `ok=true`,error / close 时更新 `ok`、`status`(close code)与 `error`(`closed (1006: reason)`)。它们没有 `reqBody` / `resBody`。
284
+
285
+ `timing` 来自 `PerformanceResourceTiming`,单位毫秒,各段含义:`dns` 名字解析、`connect` 建立连接(连接复用时为 0)、`ttfb` 请求发出到首字节、`download` 首字节到结束、`total` 整段墙钟时长。跨域且未返回 `Timing-Allow-Origin` 时可能取不到,此时字段缺省。
286
+
287
+ 丢弃情况汇总在 `networkDropped` 中,同时拼进 `content`(`networkDropped=N`),方便在日志平台直接搜到数据不完整的反馈。
288
+
289
+ **一次提交可能是多个 LogItem**:当 `ext` 超过 `transport.maxItemBytes`(默认 800KB)时,请求体数组会包含多条同 `traceId` 的 `LogItem`,`content` 末尾带 `part=1/3`。后端按数组逐条入库即可,`traceId` 相同即属于同一次反馈;`networkDropped` 在每个分片中都相同。
290
+
291
+ 截图正常情况下只有 `url`,没有 `dataBase64`。仅当图片上传失败、降级为内联提交时才会带上 `dataBase64`。
292
+
293
+ ### 请求示例
294
+
295
+ ```bash
296
+ curl -X POST 'https://admin.example.com/go/SupportTools/logreport' \
297
+ -H 'Content-Type: application/json' \
298
+ -d '[{
299
+ "timestamp": 1730000000000,
300
+ "logLevel": 3,
301
+ "userAgent": "H5, Mozilla/5.0 ...",
302
+ "url": "https://admin.example.com/order/list",
303
+ "content": "【Bug反馈】导出按钮没有反应 | 点击导出无响应 | project=demo-project env=production reportId=5f0c2e2a-...",
304
+ "traceId": "5f0c2e2a000000000000000000000000",
305
+ "ext": "{\"project\":\"demo-project\",\"title\":\"导出按钮没有反应\"}"
306
+ }]'
307
+ ```
308
+
309
+ ## 2. 响应
310
+
311
+ ```json
312
+ { "errCode": 0, "errMsg": "" }
313
+ ```
314
+
315
+ | 响应 | SDK 行为 |
316
+ |---|---|
317
+ | `errCode === 0` | 视为成功,成功页展示反馈编号(`clientReportId`) |
318
+ | `errCode` 为其他数字 | 协议失败,展示 `errMsg`,**不重试** |
319
+ | 缺少 `errCode` 或响应不是 JSON | 协议失败,展示固定文案,**不重试** |
320
+ | HTTP 429 / 5xx | 按 `1s / 3s` 退避重试,默认最多 2 次 |
321
+ | 网络错误 / 超时 | 同上重试,超时默认 15s |
322
+ | 其他 4xx | 直接失败,不重试 |
323
+
324
+ 重试沿用同一个 `clientReportId`,便于网关侧去重。网关不回传 `reportId` 或 `issueUrl`;成功页展示的是客户端生成的 `clientReportId`。
325
+
326
+ ## 3. 截图上传
327
+
328
+ 截图不直接内联进日志。提交前 SDK 先调用公司统一图片上传接口,把 base64 换成 URL,再写入 `ext.screenshots[].url`。
329
+
330
+ ```
331
+ POST /platform/file/uploadPicture
332
+ Content-Type: application/x-www-form-urlencoded
333
+ Cookie: 业务域名登录态(credentials: 'include')
334
+
335
+ imgdata=data:image/jpeg;base64,...&bizid=1086&name=bug-report-1730000000000.jpg
336
+
337
+ → 200 { "ret": 0, "errmsg": "", "data": { "url": "https://img.example.com/..." } }
338
+ → 200 { "ret": 非0, "errmsg": "..." }
339
+ ```
340
+
341
+ - 该接口契约与 `actui2` 的 `FileUpload` 一致,`data` 也可能是纯 URL 字符串
342
+ - `bizid` 是必填的业务类型,SDK 默认传 `1086`,可用 `upload.bizId` 覆盖
343
+ - 配置项:`upload.enabled`、`upload.url`、`upload.bizId`、`upload.timeoutMs`
344
+ - 上传失败不阻断提交,SDK 自动降级为内联 base64,并在 `screenshots[].dataBase64` 写入数据
345
+ - 上传接口需与业务页面同源,或由后端配置 CORS 允许 `credentials`
346
+
347
+ ## 4. 体积与裁剪
348
+
349
+ SDK 在发送前对报告做体积控制:
350
+
351
+ - 整份 `BugReport` 的目标上限为 1.5MB(`src/transport/payload.ts` 的 `MAX_JSON_BYTES`)
352
+ - 超限时按 **network body → network → logs → errors → 自动截图 → extra/contexts → elements → breadcrumbs → 手动截图** 的顺序逐步裁剪
353
+ - 元素快照在采集侧已按 `collect.maxElements` 截断、字段限长(selector/path 300 字、text 200 字、attributes 最多 20 项 × 200 字),实际很少触发裁剪;保留该分支用于兜底自定义字段
354
+ - 单个 `LogItem` 的 `ext` 不超过 `transport.maxItemBytes`(默认 800KB),超出时拆成同批多条 `LogItem`
355
+ - `title` / `description` / 环境信息永远保留
356
+ - 截图默认 JPEG、最长边 ≤ 1600、单张 ≤ 400KB,提交前已上传为 URL,不再占用日志体积
357
+
358
+ > **TODO 待确认**:网关与 SLS 实际接受的单条日志大小上限。图片上传失败降级为内联 base64 时仍需关注。
359
+
360
+ ## 5. 隐私与采集范围
361
+
362
+ - **SDK 不做内容脱敏**:console 日志、JS 异常、请求体、响应体、URL 都原样上报,敏感信息由业务侧和后端负责
363
+ - 默认过滤静态资源请求,可按 `privacy.excludeUrls`、`privacy.excludeConsolePatterns` 追加;命中的网络记录整条不采集,命中的日志整条丢弃
364
+ - 表单里用户自己填写的问题描述同样原样上报
365
+ - 如果某类请求包含凭据不应入库,用 `privacy.excludeUrls` 排除,而不是指望前端脱敏
366
+
367
+ ## 6. SLS 展示与筛选
368
+
369
+ 日志写入 SLS 后能否展示、筛选,取决于 LogStore 的索引配置,不取决于请求格式。
370
+
371
+ | 索引配置 | 能力 |
372
+ |---|---|
373
+ | 未建索引 | 只能看原始日志/消费预览,不能查询分析 |
374
+ | 仅全文索引 | 只能按 `content` 里的关键词模糊搜索 |
375
+ | 字段索引 + 类型 | 支持 `logLevel: 3`、`url: "..."`、范围过滤、聚合、排序 |
376
+
377
+ 注意事项:
378
+
379
+ 1. **字段名大小写敏感**,索引名必须与 `LogItem` 完全一致
380
+ 2. **类型必须匹配**,`logLevel` 建 `long` 索引时不能上报字符串
381
+ 3. **`ext` 是字符串**,要按 `ext.xxx` 筛选必须把 `ext` 建成 `json` 类型并配置 json key;否则只能当文本全文搜
382
+ 4. **保留字段不能占用**:`__time__`、`__topic__`、`__source__`;业务 `timestamp` 只是普通字段
383
+ 5. **时间轴**:日志的 `__time__` 若取网关接收时间,展示会与业务 `timestamp` 有偏差
384
+ 6. **中文分词**:`content`、`userAgent` 的文本索引需要配置分词/分隔符,否则只能整段匹配
385
+ 7. **索引成本**:字段越多、文本索引越多,费用越高;高频筛选字段单独建字段索引
386
+
387
+ 如果需要按 `project`、`environment`、`severity` 筛选,建议网关把它们写成顶层字段并建字段索引,而不是只放在 `ext` 里。
388
+
389
+ ## 7. 幂等与去重
390
+
391
+ - 网关当前没有显式幂等键
392
+ - `clientReportId` 同时出现在 `traceId` 与 `ext.clientReportId` 中,可作为去重依据
393
+ - SDK 重试时复用同一个 `clientReportId`
394
+ - 离线补偿队列重放时也使用原 `clientReportId`,包括 `sendBeacon` 兜底路径,可能与正常请求重复投递
395
+ - 如需严格幂等,**必须**在网关侧按 `ext.clientReportId`(或顶层 `traceId`)去重;否则超时重试与队列重放会产生重复日志
396
+
397
+ ## 8. 与旧方案的关系
398
+
399
+ 本文件此前定义的是「自建后端 → 鉴权 → 路由 → GitLab 建 Issue」方案,现已不再使用。旧的 `X-Project-Id`、`X-Report-Id`、`success` / `issueUrl` / `deduplicated` 响应字段均已移除。
400
+
401
+ 如后续要恢复 Issue 能力,应在网关侧根据 `project` 与 `page.url` 路由后自行创建,保持前端契约不变。`ext.fingerprint` 可以直接作为 issue 分组键。
@@ -0,0 +1,122 @@
1
+ # 打包器接入
2
+
3
+ 本 SDK 同时提供 ESM 与 CJS 两种产物,`exports` 里 `import` / `require` 两个条件都覆盖了(与 `@sentry/browser`、`zod` 的做法一致)。两者都把 `vue`、`html2canvas-pro`、`css-selector-generator` 作为 external,交由业务打包器处理。不同打包器与版本需要的配置不同,下面是在真实环境中验证过的组合。
4
+
5
+ ## 结论速查
6
+
7
+ | 打包器 | 开箱可用 | 走哪个条件 | 需要额外配置 |
8
+ |---|---|---|---|
9
+ | Vite 4+ | 是 | `import` | 无 |
10
+ | webpack 5 | 是 | `import` | 无 |
11
+ | Vue CLI 5(webpack 5) | 是 | `import` | 无 |
12
+ | webpack 4 | 需配置 | `require` | 见下(`exports` 字段 + html2canvas 语法) |
13
+ | Vue CLI 4(webpack 4) | 需配置 | `require` | 见下 |
14
+ | Jest / 其他 CJS 运行环境 | 是 | `require` | 无 |
15
+
16
+ > **关于 `vue`**:面板 chunk(`panel-mount-*.js` / `.cjs`)里有 `import 'vue'`,而它是通过动态 import 加载的。
17
+ > 打包器做静态分析时会解析整张 chunk 图,所以 ESM / CJS 接入方**必须安装 `vue`**(与项目版本一致),
18
+ > 即使 `reporter.enabled: false` 也一样。不想引入 Vue 依赖时用 IIFE 产物(已内联 Vue 3 runtime)。
19
+ >
20
+ > 面板用 Vue 3 的 `createApp`,因此 ESM / CJS 产物要求 Vue 3(peer 声明 `>=3.2 <4`)。
21
+ > Vue 2 项目想用反馈面板请走 IIFE 产物;只把 `@xysfe/bug-tap/vue` 当采集插件时可以留在 Vue 2.7。
22
+
23
+ ## webpack 5 / Vite
24
+
25
+ 无需任何配置。
26
+
27
+ 已验证:`import { init } from '@xysfe/bug-tap'` 与 `import BugTapVue from '@xysfe/bug-tap/vue'` 都能直接解析;
28
+ `html2canvas-pro` 与 Vue 会被自动拆成独立 chunk,首屏不加载。
29
+
30
+ ## webpack 4 / Vue CLI 4
31
+
32
+ webpack 4 有两个限制,都需要业务侧配置:
33
+
34
+ ### 限制 1:不支持 `package.json` 的 `exports` 字段
35
+
36
+ `@xysfe/bug-tap/vue` 这类子路径依赖 `exports` 解析,webpack 4 会报
37
+ `Can't resolve '@xysfe/bug-tap/vue'`。
38
+
39
+ **解决**:直接从主入口导入具名导出(webpack 4 无此限制):
40
+
41
+ ```js
42
+ // ❌ webpack 4 下解析失败
43
+ import BugTapVue from '@xysfe/bug-tap/vue';
44
+
45
+ // ✅ 两种打包器都可用
46
+ import { vuePlugin } from '@xysfe/bug-tap';
47
+ app.use(vuePlugin, { router });
48
+ ```
49
+
50
+ 或配置 alias 指到实际文件(webpack 4 只会走 `require` 条件,所以指向 `.cjs`):
51
+
52
+ ```js
53
+ resolve: {
54
+ alias: {
55
+ '@xysfe/bug-tap$': require.resolve('@xysfe/bug-tap/dist/bug-tap.cjs'),
56
+ '@xysfe/bug-tap/vue$': require.resolve('@xysfe/bug-tap/dist/bug-tap-vue.cjs')
57
+ }
58
+ }
59
+ ```
60
+
61
+ ### 限制 2:acorn 不支持 ES2020 语法
62
+
63
+ `html2canvas-pro` 的产物含 `??` 与 `?.`,webpack 4 的解析器(acorn 6)会直接报
64
+ `Module parse failed: Unexpected token`。
65
+
66
+ **解决**:把 html2canvas-pro 及其传递依赖交给 babel 转译。
67
+ 注意 `.babelrc` **默认不作用于 `node_modules`**,必须把 preset 写进 loader options:
68
+
69
+ ```js
70
+ module: {
71
+ rules: [
72
+ {
73
+ test: /node_modules[\\/](html2canvas-pro|css-line-break|text-segmentation|utrie)[\\/]/,
74
+ use: [
75
+ {
76
+ loader: 'babel-loader',
77
+ options: {
78
+ // 关键:babelrc/configFile 关掉,否则 node_modules 内的文件拿不到配置
79
+ babelrc: false,
80
+ configFile: false,
81
+ presets: [['@babel/preset-env', { targets: 'ie 11' }]]
82
+ }
83
+ }
84
+ ]
85
+ }
86
+ ]
87
+ }
88
+ ```
89
+
90
+ 已用 webpack 4.47.0 + babel-loader 8 + `@babel/preset-env` 验证:构建成功,
91
+ `html2canvas` 被拆成独立 chunk。
92
+
93
+ ### 备选:不参与打包
94
+
95
+ 如果不想改 webpack 配置,可以用 CDN 脚本接入,或让截图库走外部脚本:
96
+
97
+ ```js
98
+ BugTap.init({
99
+ project: 'p',
100
+ screenshot: {
101
+ // 配了 scriptUrl 就不再 import('html2canvas-pro'),
102
+ // 改成运行时注入这个脚本(需自行托管 bug-tap-screenshot.min.js)
103
+ scriptUrl: 'https://cdn.example.com/bug-tap/bug-tap-screenshot.min.js'
104
+ }
105
+ });
106
+ ```
107
+
108
+ Webpack 的 `IgnorePlugin` 也能达到类似效果,但需要自己保证 `window.__BugTapHtml2Canvas` 已就绪。
109
+
110
+ ## 关于 `screenshot.scriptUrl`
111
+
112
+ - **IIFE 产物**:不填时按「与主包同目录」推断;主包与截图库不在同一目录、或主包被内联时,必须显式指定
113
+ - **ESM / CJS 产物**:不填时走 `import('html2canvas-pro')`,由打包器按需拆 chunk;填了则改为注入外部脚本(webpack 4 的解法)
114
+
115
+ ## 验证脚本
116
+
117
+ 以下命令会复现上表结论(需要本机已装 Chrome):
118
+
119
+ ```bash
120
+ npm run verify # typecheck + 单测 + 构建 + 产物校验
121
+ npx playwright test # 浏览器端 e2e,含 Vue 3 + vue-router
122
+ ```