@xysfe/bug-tap 0.0.0-stage → 0.1.0

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 +69 -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-BBRuTNvo.js +4685 -0
  38. package/dist/index-BBRuTNvo.js.map +1 -0
  39. package/dist/index-DCLLRJxX.cjs +488 -0
  40. package/dist/index-DCLLRJxX.cjs.map +1 -0
  41. package/dist/index.d.ts +33 -0
  42. package/dist/integrations.d.ts +26 -0
  43. package/dist/panel-mount-Dia21VuZ.cjs +2 -0
  44. package/dist/panel-mount-Dia21VuZ.cjs.map +1 -0
  45. package/dist/panel-mount-mAOg572s.js +499 -0
  46. package/dist/panel-mount-mAOg572s.js.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
package/CHANGELOG.md ADDED
@@ -0,0 +1,69 @@
1
+ # Changelog
2
+
3
+ 本项目遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/) 与语义化版本。
4
+
5
+ ## [0.1.0] - 2026-11-18
6
+
7
+ ### Added
8
+
9
+ - 产物拆分:IIFE 主包不再内联截图库,首次截图时按需加载 `bug-tap-screenshot.min.js`(首屏 121KB → 71KB gzip)
10
+ - 主包不再静态依赖 Vue:面板改为动态 import,ESM 纯采集场景产物中不含 Vue 实现
11
+ - 新增 CJS 产物 `dist/bug-tap.cjs` / `dist/bug-tap-vue.cjs`,`exports` 补齐 `require` 条件,webpack 4 / Jest 等 CJS 消费方可直接 `require()`(与 `@sentry/browser`、`zod` 的双产物做法一致)
12
+ - 新增 `@xysfe/bug-tap/vue` 插件入口:单入口同时支持 Vue 2 / Vue 3(形态由 `app.use` / `Vue.use` 决定),零依赖、约 1KB
13
+ - 反馈面板新增「重新截图」按钮;自动截图以缩略图展示并带「自动」角标
14
+ - 插件传 `router` 时接管路由记录并摘掉主包 history 补丁,修复一次导航记两遍
15
+ - 新增 `BugTap.disableRouteCapture()`,供框架路由集成显式接管导航
16
+ - 新增 Vue 3 + vue-router demo(`demo/vue3/`)与对应 e2e project
17
+ - 新增 `screenshot.scriptUrl`:IIFE 截图库地址可配置,不再只能靠「与主包同目录」推断
18
+ - 主入口新增 `vuePlugin` 具名导出,解决 webpack 4 不认 `exports` 字段导致的子路径解析失败
19
+ - `docs/bundler.md`:Vite / webpack 5 / webpack 4 / Vue CLI 4·5 的实测接入说明
20
+
21
+ - 业务上下文 API:`setTag` / `setExtra` / `setContext`,随报告写入 `ext.tags` / `ext.extra` / `ext.contexts`
22
+ - 主动采集 API:`captureException` / `captureMessage` / `addBreadcrumb`
23
+ - `flush()`:手动重放本地补偿队列
24
+ - `createClient()`:为微前端 / 多子应用创建独立实例
25
+ - React 19 全局错误回调:`reactErrorHandlers`
26
+ - 资源加载失败(img/script/link)进入 `errors[]`,`type: "resource"`
27
+ - WebSocket / EventSource 生命周期采集,`network[].type` 支持 `websocket` / `eventsource`
28
+ - 提交失败写入 IndexedDB 补偿队列,页面恢复后自动重放;页面隐藏时用 `sendBeacon` 兜底
29
+ - `<script data-project="..." data-endpoint="...">` 零配置接入
30
+ - 报告新增 `release` 与 `fingerprint`,供 sourcemap 符号化与后端分组
31
+ - `collect.realtime` / `collect.resourceErrors` / `collect.maxElements` / `collect.eventListenerErrors`
32
+ - `collect.requestHeaders` / `collect.responseHeaders`:可配置请求头、响应头白名单(默认不采请求头,不做脱敏)
33
+ - 网络记录在每个 LogItem 内按 `timestamp` 升序排列;拆包时带 `part: { index, total }`
34
+ - Vue/React 集成接入全局 API:`BugTap.reactErrorHandlers()`,React 上报 componentStack
35
+ - 复杂故障现场 demo:`demo/scenario.html` 与 `test/e2e/ai-scenario.spec.ts`
36
+ - `transport.offline`(TTL / 容量)与 `transport.maxReportsPerSession`
37
+ - `hooks.beforeSend` 支持返回 Promise(`getReport()` 仍只接受同步钩子)
38
+ - `collector.patched` 增加 `websocket` / `eventsource` 状态
39
+ - CI:typecheck / unit / build / dist 校验与体积预算
40
+
41
+ ### Changed
42
+
43
+ - `main` 改为指向 `dist/bug-tap.cjs`,`module` 指向 ESM 入口,`exports` 的 `types` / `import` / `require` 三个条件齐备
44
+ - `./global` 子路径补上 `types` 条件,TS 用户引入 IIFE 入口时也能拿到声明
45
+ - `keepalive` 预算按 UTF-8 字节计算,修复中文报告误判
46
+ - 体积裁剪顺序:自动截图 → 业务 extra/contexts → 元素快照 → 时间线 → 手动截图
47
+ - `elements` 按 `collect.maxElements` 截断,字段长度受限
48
+ - 反馈面板:Tab 焦点陷阱、关闭后焦点还原、`aria-live` 状态提示
49
+ - 包元数据补充 `repository` / `homepage` / `bugs` / `./package.json` 导出
50
+
51
+ ### Removed
52
+
53
+ - `SubmitResponse.issueUrl` / `SubmitResponse.deduplicated`(网关并未返回,属死字段)
54
+
55
+ ### Fixed
56
+
57
+ - `init()` 遇到非法配置(缺 project、endpoint 非 http/https)时返回 `null` 且不占用单例,修复「首次配置写错后再也无法初始化」的问题
58
+ - Vue 插件在无 `window` 环境(SSR / Nuxt / Worker)安装时不再抛 `ReferenceError`,按「未初始化」静默跳过
59
+ - `setExtra` / `setContext` 在写入时做有界深拷贝,环引用(Vue reactive / store)不再让整条提交因 `JSON.stringify` 失败
60
+ - `Transport.send` 捕获序列化异常并转成可读的 protocol 错误,不再把原始 JSON 报错抛给用户
61
+ - 面板异步加载期间重复点击不再创建第二个 Vue 应用(`panelLoading` 现在是复用句柄,并在挂载回调里做并发兜底)
62
+ - EventSource 重连成功后清除上次的 `error`,避免已恢复的连接被永久判为失败请求
63
+ - 手动面包屑去重时比较 `data`,连续两条同 message 不同载荷的 `addBreadcrumb` 不再被吞掉
64
+ - `HooksConfig.beforeSend` 类型补上 `Promise` 返回,异步钩子的文档与类型契约一致
65
+ - IndexedDB 写入失败时退回内存并参与 `peek()`,不再出现「显示已保存但两边都没有」
66
+ - 体积裁剪的 elements / breadcrumbs 改回增量记账,避免每丢一条就序列化整份 1.5MB 报告
67
+ - 拆包时 elements 只挂在能放下它的那一页,不再从每个分片的预算里重复扣除
68
+ - `frameUrlOf` 与 `firstFrameOf` 合并为单一帧扫描实现,消除行为分叉
69
+ - 清理面板工厂类型与截图库注入点两处死代码
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 xinhulu
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,462 @@
1
- # Temporary Holding Version
1
+ # @xysfe/bug-tap
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ 可嵌入任意网页的调试与 Bug 上报 SDK。一行 `<script>` 引入后:
4
+
5
+ - 右下角出现**独立的「反馈」悬浮按钮**,不依赖调试面板是否开启
6
+ - 自动采集 Console、JS 异常、Network、页面环境
7
+ - 打开面板时自动生成当前视口截图(DOM 渲染式)
8
+ - 用户填写问题后提交到公司日志网关(默认同源 `/go/SupportTools/logreport`),由网关落盘到阿里云 SLS
9
+
10
+ ## 快速开始
11
+
12
+ ### CDN 一行接入
13
+
14
+ ```html
15
+ <script>
16
+ window.BugTapConfig = {
17
+ project: 'project-a',
18
+ environment: 'production',
19
+ reporter: { enabled: true, position: 'bottom-right', theme: 'auto' }
20
+ };
21
+ </script>
22
+ <script src="https://cdn.example.com/bug-tap.min.js"></script>
23
+ ```
24
+
25
+ 也支持 data 属性零配置接入(`window.BugTapConfig` 优先):
26
+
27
+ ```html
28
+ <script
29
+ src="https://cdn.example.com/bug-tap.min.js"
30
+ data-project="project-a"
31
+ data-environment="production"
32
+ data-endpoint="/go/SupportTools/logreport"
33
+ data-app-version="1.2.3"
34
+ data-build-id="abc1234"
35
+ ></script>
36
+ ```
37
+
38
+ `window.BugTap` 在脚本执行后立即可用。
39
+
40
+ ### npm
41
+
42
+ ```bash
43
+ npm i @xysfe/bug-tap
44
+ ```
45
+
46
+ ```js
47
+ import { init } from '@xysfe/bug-tap';
48
+
49
+ init({
50
+ project: 'project-a',
51
+ environment: 'production'
52
+ });
53
+ ```
54
+
55
+ ESM / CJS 构建把 `vue`、`html2canvas-pro`、`css-selector-generator` 作为外部依赖,不打进包里;CDN 的 IIFE 产物已全部内联,不需要额外脚本。
56
+
57
+ **按需加载截图库**:`html2canvas-pro` 约 260KB,只在用户点开面板需要截图时才用到。SDK 内部用动态 `import()` 引入,npm 场景下业务打包器会自动拆成独立 chunk。实测业务侧构建产物:首屏 SDK chunk 约 127KB,截图 chunk 260KB 按需加载——用户从不反馈时这段代码永远不会下载。
58
+
59
+ ## 配置
60
+
61
+ ```ts
62
+ interface BugTapConfig {
63
+ project: string; // 必填,写入上报日志的 project 字段
64
+ endpoint?: string; // 默认 /go/SupportTools/logreport,一般不用填
65
+ environment?: string; // 默认 production
66
+ appVersion?: string; // 业务版本号,写入 ext.app,用于定位源码
67
+ buildId?: string; // 业务构建号(commit 短哈希等)
68
+ user?: UserInfo | (() => UserInfo | null | undefined); // 登录用户信息,见「用户信息」
69
+ debug?: boolean; // 默认 false,仅控制 SDK 自身告警
70
+
71
+ reporter?: {
72
+ enabled?: boolean; // 默认 true
73
+ position?: 'bottom-right' | 'bottom-left';
74
+ theme?: 'light' | 'dark' | 'auto'; // 默认 auto
75
+ text?: string; // 悬浮按钮文字,默认「反馈」
76
+ zIndex?: number; // 默认 2147483000
77
+ visibility?: {
78
+ mode?: 'always' | 'triggered'; // 默认 always
79
+ queryParam?: string; // 默认 bugtap
80
+ queryValue?: string; // 默认 1
81
+ closable?: boolean; // 默认 true
82
+ };
83
+ };
84
+
85
+ collect?: {
86
+ console?: boolean; // 默认 true
87
+ error?: boolean; // 默认 true
88
+ network?: boolean; // 默认 true
89
+ networkBody?: boolean; // 默认 true,采集请求体与响应体
90
+ realtime?: boolean; // 默认 true,采集 WebSocket / EventSource
91
+ resourceErrors?: boolean; // 默认 true,资源加载失败记入 errors[]
92
+ environment?: boolean; // 默认 true
93
+ trackIds?: boolean; // 默认 true,带上 tongji 的 xid/subId/sessionId
94
+ breadcrumbs?: boolean; // 默认 true,记录操作时间线
95
+ maxBreadcrumbs?: number; // 默认 100,上限 200(与 Sentry / Rollbar 一致)
96
+ maxConsoleLogs?: number; // 默认 100,上限 500
97
+ maxNetworkRecords?: number; // 默认 200,上限 500
98
+ maxErrors?: number; // 默认 50,上限 200
99
+ maxNetworkBytes?: number; // 默认 524288,网络记录总字节预算
100
+ maxCloneBytes?: number; // 默认 262144,超过不 clone 响应
101
+ requestHeaders?: string[] | boolean; // 默认 [],请求头白名单;true 表示全部
102
+ responseHeaders?: string[] | boolean; // 默认 trace 白名单 + content-type;true 表示全部
103
+ maxElements?: number; // 默认 5,单次反馈最多关联的元素快照数
104
+ eventListenerErrors?: boolean; // 默认 true;大型页面可关掉 EventTarget 包装
105
+ };
106
+
107
+ privacy?: {
108
+ excludeUrls?: Array<string | RegExp>; // 在默认静态资源过滤之上追加
109
+ excludeConsolePatterns?: Array<string | RegExp>;
110
+ excludeBreadcrumbUrls?: Array<string | RegExp>; // 只屏蔽 http 面包屑,不影响 network[]
111
+ };
112
+
113
+ filtering?: {
114
+ ignoreErrors?: Array<string | RegExp>; // 消息命中即不采集
115
+ denyUrls?: Array<string | RegExp>; // 按抛出点脚本地址过滤
116
+ allowUrls?: Array<string | RegExp>; // 非空时必须命中
117
+ disableErrorDefaults?: boolean; // 关闭内置噪声表(Script error / ResizeObserver 等)
118
+ };
119
+
120
+ hooks?: {
121
+ beforeSend?(report: BugReport): BugReport | null | Promise<BugReport | null>; // 支持异步
122
+ beforeBreadcrumb?(crumb: Breadcrumb): Breadcrumb | null; // 返回 null 丢弃
123
+ };
124
+
125
+ screenshot?: {
126
+ enabled?: boolean; // 默认 true
127
+ auto?: boolean; // 默认 true,打开面板时自动截图
128
+ quality?: number; // 默认 0.8
129
+ maxWidth?: number; // 默认 1600
130
+ maxSizeKB?: number; // 默认 400
131
+ scriptUrl?: string; // 截图库地址;不填按「与主包同目录」推断
132
+ };
133
+
134
+ transport?: {
135
+ timeoutMs?: number; // 默认 15000
136
+ retries?: number; // 默认 2,仅网络错误 / 429 / 5xx 重试
137
+ headers?: Record<string, string>;
138
+ maxItemBytes?: number; // 默认 800000,超出拆成多条 LogItem 同批提交
139
+ totalTimeoutMs?: number; // 默认 30000,整次提交的总时长上限(含重试)
140
+ maxConcurrent?: number; // 默认 10,进行中提交数上限,超出立即返回「正在提交中」
141
+ logLevel?: 1 | 2 | 3; // 强制 logLevel;不填按 severity 映射
142
+ offline?: { // 提交失败后的本地补偿队列
143
+ enabled?: boolean; // 默认 true
144
+ ttlMs?: number; // 默认 24h
145
+ maxItems?: number; // 默认 20
146
+ };
147
+ maxReportsPerSession?: number; // 默认 0(不限制)
148
+ };
149
+
150
+ upload?: {
151
+ enabled?: boolean; // 默认 true,提交前把截图上传成 URL
152
+ url?: string; // 默认 /platform/file/uploadPicture
153
+ bizId?: string; // 默认 '1008',上传接口要求的业务类型
154
+ timeoutMs?: number; // 默认 30000
155
+ };
156
+ }
157
+ ```
158
+
159
+ 完整说明见 [docs/config.md](docs/config.md)。
160
+
161
+ ## 全局 API
162
+
163
+ ```ts
164
+ BugTap.init(config?) // 手动初始化;自动初始化失败时使用
165
+ BugTap.createClient(config) // 创建独立实例(微前端 / 多子应用)
166
+ BugTap.open() // 打开反馈面板
167
+ BugTap.close() // 关闭反馈面板
168
+ BugTap.openReporter() // 同 open()
169
+ BugTap.closeReporter() // 同 close()
170
+ BugTap.setConfig(patch) // 运行时修改配置(会重建 UI 与采集器)
171
+ BugTap.setUser(user | null) // 运行时更新登录用户信息,下次提交生效
172
+ BugTap.setTag(key, value) // 业务标签,写入 ext.tags
173
+ BugTap.setExtra(key, value) // 结构化上下文,写入 ext.extra
174
+ BugTap.setContext(name, obj) // 分组上下文,写入 ext.contexts
175
+ BugTap.addBreadcrumb(crumb) // 主动写一条时间线
176
+ BugTap.captureException(err) // 主动记录异常,进入下一次反馈
177
+ BugTap.captureMessage(msg) // 主动记录消息,进入下一次反馈
178
+ BugTap.flush() // 立即重放本地补偿队列,返回成功条数
179
+ BugTap.destroy() // 还原所有 hook、移除 UI、清理监听
180
+ BugTap.getReport() // 取当前采集到的报告(不含截图)
181
+ BugTap.version
182
+ ```
183
+
184
+ Vue / React 集成:
185
+
186
+ ```js
187
+ // ── Vue:一个入口同时支持 Vue 2 / Vue 3,形态由调用方式决定 ──
188
+ // Vue 3
189
+ import BugTapVue from '@xysfe/bug-tap/vue';
190
+ createApp(App).use(router).use(BugTapVue, { router }).mount('#app');
191
+
192
+ // Vue 2
193
+ import BugTapVue from '@xysfe/bug-tap/vue';
194
+ Vue.use(BugTapVue, { router });
195
+ new Vue({ router }).$mount('#app');
196
+
197
+ // CDN:先引入 bug-tap-vue.min.js,再用 window.BugTapVue
198
+ app.use(window.BugTapVue, { router });
199
+
200
+ // ── React ──
201
+ createRoot(el, BugTap.reactErrorHandlers()); // React 19
202
+ BugTap.captureException(error, { source: 'react', componentStack: info.componentStack }); // React 18 ErrorBoundary
203
+ ```
204
+
205
+ Vue 插件做了什么:
206
+
207
+ - 挂 `Vue.config.errorHandler` / `app.config.errorHandler`,链式保留业务原有处理
208
+ - 上报 `source: "vue"`、`info`、`component`(组件名)与当前路由
209
+ - 传了 `router` 时改用 `router.afterEach` 记路由面包屑,并**摘掉主包的 history 补丁**,避免一次导航记两遍
210
+ - 导航失败(懒加载 chunk 404、守卫抛错)记成 `errors[]`,附 `from` / `to`
211
+
212
+ **Vue 2 的适用范围**:插件本身零依赖、不做版本嗅探,Vue 2.7 可以正常 `Vue.use` 并采集异常与路由。
213
+ 但反馈面板用的是 Vue 3 的 `createApp`,而 ESM / CJS 产物把 `vue` 作为 external——Vue 2 项目接入这两个产物时,
214
+ 面板会在 `createApp is not a function` 处失败。Vue 2 项目请用 IIFE 产物(已内联 Vue 3 runtime,面板可用),
215
+ 只把插件当采集入口时才能用 `@xysfe/bug-tap/vue`。
216
+
217
+ React 19 回调会带上 `componentStack`。
218
+
219
+ `captureException` / `captureMessage` 只写入本地缓冲,随下一次用户反馈一起提交,不会单独发请求。
220
+
221
+ `setExtra` / `setContext` 在写入时就做有界深拷贝:环引用替换为 `[Circular]`,深度 ≤ 6 层、每个对象最多 50 个键,getter 抛错时跳过该键。因此传入 Vue reactive 或 store 对象不会让提交因 `JSON.stringify` 失败。
222
+
223
+ 完整说明见 [docs/api.md](docs/api.md)。
224
+
225
+ ## 采集范围
226
+
227
+ | 类型 | 内容 | 默认上限 |
228
+ |---|---|---|
229
+ | Console | log / info / warn / error / debug / trace / assert,保留原始输出行为;连续相同行折叠并累加 `count` | 100 条 |
230
+ | JS 异常 | `window.onerror`、`unhandledrejection`、定时器 / 事件监听回调(标注 `[setTimeout]` 等来源),1s 内同签名去重;内置噪声表默认过滤 | 50 条 |
231
+ | 资源错误 | img / script / link / video 等加载失败,`type: "resource"`,记录标签与地址 | 50 条(共享 errors) |
232
+ | Network | fetch / XHR 的 method、URL、status、耗时分解、失败原因、trace 响应头、请求体、响应体、可选请求头/响应头 | 200 条 / 512KB |
233
+ | 长连接 | WebSocket / EventSource 的 open / error / close,close code 与 reason | 200 条(共享 network) |
234
+ | 环境 | URL、referrer、标题、UA、浏览器/OS、屏幕与视口、DPR、`device`(`1920*1080 @ 1.1x`)、语言、时区 | — |
235
+ | 用户 | 由 `user` 配置注入,写进 `ext.user` 与 `content` 的 `user=` | — |
236
+ | 业务上下文 | `setTag` / `setExtra` / `setContext` 写入 `ext.tags` / `ext.extra` / `ext.contexts` | tags 5 条进 content |
237
+ | 跟踪标识 | tongji 的 `xid` / `subId` / `sessionId`,写进 `ext.track` 与 `content` 的 `xid=` / `si=` | — |
238
+ | 操作时间线 | click / input / route / visibility / 全部请求 / 异常 / 手动条目,写进 `ext.breadcrumbs`;连续相同请求折叠,可还原因果链 | 100 条 |
239
+ | 采集健康 | `ext.collector`:启动时刻、首屏盲区 `earlyGapMs`、打点是否仍生效、各类条数 | — |
240
+ | 截图 | 当前视口,JPEG,最长边 ≤ 1600,单张 ≤ 400KB,带 `capturedAt` | 1 张 |
241
+
242
+ **请求体 / 响应体的采集边界**(`collect.networkBody`,默认开启):
243
+
244
+ - 不做单条 body 截断,改为按 `maxNetworkBytes`(默认 512KB)的总字节预算整体保留
245
+ - 预算满了从最旧的整条记录开始丢弃,留在缓冲区里的每条数据都是完整的
246
+ - 单条记录本身超过总预算时不写入,不做切分
247
+ - 响应超过 `maxCloneBytes`(默认 256KB)不 clone,只记状态
248
+ - `text/event-stream` 不 clone,避免业务流卡住
249
+ - 图片 / 视频 / 音频 / 字体 / octet-stream / zip / pdf / wasm 等二进制不读内容
250
+ - fetch 传 `Request` 对象时按 `maxCloneBytes` 流式限读请求体,超限截断并标记
251
+ - XHR 只读 `responseType` 为 `''`/`text`/`json` 的响应,按 `maxCloneBytes` 截断;`blob`/`arraybuffer` 只记类型
252
+ - FormData 里的文件只记 `name/size/type`,不读内容
253
+ - 响应没有 `content-length`(chunked / HTTP/2)时按 `maxCloneBytes` 流式限读,不会把超大响应整个读进内存
254
+ - 流式响应(如长轮询)先记元数据,body 读到或超限后再补写,不会因流未结束而丢失整条记录
255
+ - XHR 被业务 `abort()` 时记为取消,不当作网络错误,也不进入「失败请求优先」分片
256
+ - **SDK 不做内容脱敏**:日志、异常、请求体、响应体、URL 全部原样上报,需要排除的用 `privacy.excludeUrls` / `privacy.excludeConsolePatterns`
257
+
258
+ **提交时的裁剪顺序**(`src/transport/payload.ts`):
259
+
260
+ 1. 先丢成功请求的 body,元数据全部保留
261
+ 2. 再丢失败请求的 body
262
+ 3. 再从最旧的开始整条丢弃网络记录
263
+ 4. 然后丢 console 日志、异常
264
+ 5. 再丢自动截图(用户手动上传的图先保留)
265
+ 6. 再按 key 从旧到新丢 `extra` / `contexts`
266
+ 7. 再从旧到新丢元素快照
267
+ 8. 时间线减半,保留最近 10 条
268
+ 9. 最后放弃手动截图
269
+
270
+ **上报分包**:单条 `LogItem` 的 `ext` 超过 `transport.maxItemBytes`(默认 800KB)时,自动拆成多条 `LogItem` 放在同一个 POST 数组里提交,`content` 会追加 `part=1/3` 标记。失败请求优先进入前面的分片。
271
+
272
+ **离线补偿**:提交最终失败(断网、超时、429、5xx)时,SDK 会把这批 `LogItem` 原样写入 IndexedDB(主键 `clientReportId`,默认保留 24h / 20 条)。下次进入页面、`online` 事件触发或调用 `BugTap.flush()` 时自动重放;页面隐藏时还会用 `sendBeacon` 兜底。因此弱网下用户看到的是「已保存」,而不是「提交失败」。
273
+
274
+ **数据完整性**:`ext.networkDropped` 记录网络数据的丢失情况——
275
+
276
+ ```json
277
+ { "droppedCount": 0, "droppedBytes": 0, "evictedCount": 3, "evictedBytes": 24576, "trimmedCount": 0, "totalCount": 53, "sentCount": 50 }
278
+ ```
279
+
280
+ - `dropped*`:单条超总预算、未写入缓冲
281
+ - `evicted*`:为腾空间被淘汰的旧记录
282
+ - `trimmedCount`:提交前被体积裁剪掉
283
+ - `totalCount === sentCount` 且各计数为 0 表示完整
284
+ - `totalCount: null` 表示未采集网络(`collect.network=false`),此时 `network: []` 不代表页面没发请求,`content` 会带 `networkDisabled`
285
+ - 同时拼进 `content`(`networkDropped=3`),可在日志平台直接搜出数据不完整的反馈
286
+
287
+ **排障字段**:数据为空时,先看下面几个字段再判断「页面没发生」还是「没采到」——
288
+
289
+ - `ext.collector.earlyGapMs` > 0:页面导航到采集启动之间有盲区,首屏的日志与请求不可回溯,此时空数组不代表页面没动作。同时拼进 `content`(`earlyGap=1200ms`)
290
+ - `ext.collector.patched`:某项为 `false` 说明打点已被后来者覆盖,这段数据不可信
291
+ - `ext.app`:`appVersion` / `buildId`,生产包压缩后靠它把 `lineno` 映射回源码
292
+ - `ext.breadcrumbs`:同一条时间线(点击 / 输入 / 路由 / 全部请求 / 异常),按 `t` 排序即可还原因果链;相邻相同请求折叠为一条并累加 `repeat`,`http` 条目用 `ref` 关联 `network[].id`;`collector.breadcrumbEvicted > 0` 表示开头不完整
293
+ - `ext.screenshots[].capturedAt`:auto 截图拍的是「打开面板那一刻」,通常晚于错误发生时间,不能当作错误现场
294
+
295
+ SDK 越早引入,`earlyGapMs` 越小;推荐同步 `<script>` 或 module 预加载。
296
+
297
+ 采集失败永远不会影响业务页面:所有包装器内部 `try/catch`,并原样透传原函数的参数、返回值和异常。
298
+
299
+ ## 截图说明
300
+
301
+ 截图使用 [html2canvas-pro](https://github.com/yorickshan/html2canvas-pro) 对 DOM 做**重绘**,不是操作系统级像素截图:
302
+
303
+ - 打开面板时自动生成(`screenshot.auto=false` 时不生成),可点「重新截图」重拍或手动上传图片
304
+ - 自动截图会在表单里显示缩略图并带「自动」角标,重新截图会覆盖上一张
305
+ - 提交时先调用公司图片上传接口换成 URL,报告里只带 `url`,不再内联 base64
306
+ - 上传失败自动降级为内联 base64,不阻断提交
307
+ - 截图前会隐藏 SDK 自身 UI
308
+ - `canvas`、`video`、`iframe`、跨域图片可能空白或缺失
309
+ - `position: fixed`、`filter/backdrop-filter`、部分 `clip-path` 有偏差
310
+ - 只截当前视口,不截整页
311
+ - 失败时降级为「无截图」,表单仍可提交
312
+ - 关闭面板即丢弃本轮自动截图,重新打开会重新截,不会复用上一张
313
+
314
+ ## 上报契约
315
+
316
+ 前端只向上报接口发数据,**不包含 GitLab 地址、Token 或仓库路径**。默认走公司日志网关,同源调用,无需鉴权:
317
+
318
+ ```
319
+ POST {endpoint} // 默认 /go/SupportTools/logreport
320
+ Content-Type: application/json
321
+
322
+ [ { LogItem } ] // 数组;通常 1 个元素,超出 maxItemBytes 时会拆成多个(同一 traceId)
323
+
324
+ LogItem {
325
+ timestamp: number // 毫秒
326
+ logLevel: 1 | 2 | 3 // info / warn / error;severity=normal 为 2,其余为 3;可用 transport.logLevel 覆盖
327
+ userAgent: string // "H5, " + UA
328
+ url: string // 页面 URL
329
+ content: string // 可读摘要:标题、描述前 500 字、project/env/release/fingerprint/reportId;含 earlyGap 标记
330
+ traceId: string // clientReportId 去分隔符后取 32 位
331
+ ext: string // JSON.stringify 的完整报告(含 collector / app / breadcrumbs / tags / extra / contexts)
332
+ }
333
+
334
+ → 200 { errCode: 0, errMsg: "" }
335
+ → 200 { errCode: 非0, errMsg } // 协议失败,不重试
336
+ → 429 / 5xx // 退避重试
337
+ ```
338
+
339
+ `content` 是字符串,不能传对象;结构化数据统一 `JSON.stringify` 后放 `ext`。日志平台能否按字段筛选取决于 LogStore 的索引配置,见 [docs/backend-api.md](docs/backend-api.md)。
340
+
341
+ ## 打包器兼容性
342
+
343
+ | 打包器 | 开箱可用 | 说明 |
344
+ |---|---|---|
345
+ | Vite 4+ | 是 | 走 `import` 条件 |
346
+ | webpack 5 / Vue CLI 5 | 是 | 走 `import` 条件 |
347
+ | webpack 4 / Vue CLI 4 | 需配置 | 走 `require` 条件;子路径用主入口具名导出;html2canvas 需 babel 转译 |
348
+ | Jest / CJS `require` | 是 | 走 `require` 条件,产物为 `dist/bug-tap.cjs` |
349
+
350
+ `exports` 里 `import` 与 `require` 两个条件都提供了,因此 ESM 与 CJS 消费者都能直接解析
351
+ (与 `@sentry/browser`、`zod` 的做法一致)。webpack 4 的限制与配置示例见 [docs/bundler.md](docs/bundler.md)。
352
+
353
+ ## 本地开发
354
+
355
+ ```bash
356
+ npm install
357
+ npm run build # 产出 dist/bug-tap.min.js(IIFE)、bug-tap.js(ESM)、d.ts、sourcemap
358
+
359
+ # 终端 1
360
+ npm run mock # http://127.0.0.1:8787/plain.html
361
+
362
+ # 终端 2
363
+ npm test # vitest 单测
364
+ npm run test:e2e # playwright(默认使用本机 Chrome,channel=chrome)
365
+ ```
366
+
367
+ Demo:
368
+
369
+ - `/plain.html`:原生 HTML,带 Console / 异常 / 失败 fetch / 失败 XHR
370
+ - `/vue.html`:Vue 2.7
371
+ - `/react.html`:React 18
372
+ - `/csp.html`:服务端下发 `script-src 'self'; style-src 'self'`,验证 CSP 兼容
373
+
374
+ Mock 服务端提供:
375
+
376
+ - `POST /go/SupportTools/logreport`,接收 `LogItem[]`,支持 `?fail=500`、`?delay=2000`
377
+ - `GET /__reports`、`DELETE /__reports` 查看/清空收到的报告
378
+
379
+ ## 构建产物与体积
380
+
381
+ | 产物 | 用途 | 原始 | gzip |
382
+ |---|---|---|---|
383
+ | `dist/bug-tap.min.js` | CDN 主包:采集 + UI(含 Vue 3 runtime),**不含截图库** | 约 207 KB | 约 71 KB |
384
+ | `dist/bug-tap-screenshot.min.js` | 截图库,首次截图时从同目录按需加载 | 约 206 KB | 约 50 KB |
385
+ | `dist/bug-tap-vue.min.js` | CDN 的 Vue 2/3 插件(零依赖) | 约 2 KB | 约 0.9 KB |
386
+ | `dist/bug-tap.js` | ESM 入口(薄壳),按需加载面板与截图 chunk | 约 0.3 KB | 约 0.2 KB |
387
+ | `dist/bug-tap-vue.js` | ESM 的 Vue 2/3 插件(零依赖) | 约 3 KB | 约 1.0 KB |
388
+ | `dist/bug-tap.cjs` | CJS 入口(薄壳),供 `require()` 消费方 | 约 0.5 KB | 约 0.3 KB |
389
+ | `dist/bug-tap-vue.cjs` | CJS 的 Vue 2/3 插件(零依赖) | 约 2 KB | 约 0.9 KB |
390
+ | `dist/index.d.ts` / `dist/vue.d.ts` | 类型声明入口 | — | — |
391
+
392
+ **首屏体积从 121KB 降到 71KB**:截图库(50KB)拆成独立脚本,从不反馈的用户不下载它。
393
+
394
+ **截图库地址**:IIFE 产物默认从「与主包同目录」加载 `bug-tap-screenshot.min.js`。整包一起部署时无需配置;
395
+ 主包被内联、经 `/assets/xxx.js` 之类动态文件名加载、或截图库单独走另一条 CDN 时,用
396
+ `screenshot.scriptUrl` 指定绝对地址或相对路径。ESM / CJS 产物默认走 `import('html2canvas-pro')`,
397
+ 配了 `scriptUrl` 则改为注入外部脚本(webpack 4 的解法)。
398
+
399
+ **关于 `vue` 依赖**:Vue 只出现在面板 chunk(`panel-mount-*.js`)里,而面板是动态 import 的。
400
+ 但打包器会对整个 chunk 图做静态分析——只要代码路径上存在 `import('./ui/panel-mount')`,
401
+ `vue` 就必须能解析到。所以接入本包的 ESM / CJS 产物时需要安装 `vue`(与项目版本一致);
402
+ `reporter.enabled: false` 的纯采集场景也一样。不想引入 Vue 依赖时用 IIFE 产物,它已内联 Vue 3 runtime。
403
+
404
+ `npm run check:dist` 会校验产物完整性、依赖边界(主包不含截图库 / 插件不含 Vue)与 gzip 预算。
405
+
406
+ ## 发布前校验
407
+
408
+ ```bash
409
+ npm run verify # typecheck + test + build + check:dist
410
+ ```
411
+
412
+ `prepublishOnly` 会重新构建并校验 `dist/index.d.ts` 是否存在,避免发布出没有类型声明的包。CI 配置见 `.gitlab-ci.yml`。
413
+
414
+ ## 目录结构
415
+
416
+ ```
417
+ src/
418
+ ├── index.ts # 全局初始化、window.BugTap
419
+ ├── sdk.ts # 生命周期与模块编排
420
+ ├── config.ts # 默认值、校验、深合并
421
+ ├── types.ts # 对外类型
422
+ ├── core/
423
+ │ ├── collector.ts # 采集器编排
424
+ │ ├── console-collector.ts # console hook
425
+ │ ├── error-collector.ts # 全局异常
426
+ │ ├── network-collector.ts # fetch / XHR hook
427
+ │ ├── env-collector.ts # 环境信息
428
+ │ ├── ring-buffer.ts # 定长环形缓冲
429
+ │ ├── serialize.ts # 安全序列化
430
+ │ ├── user.ts # 用户信息解析
431
+ │ └── tongji.ts # xid / subId / sessionId(优先 window.tongji,含复刻)
432
+ ├── transport/
433
+ │ ├── payload.ts # BugReport 组装与体积裁剪
434
+ │ └── transport.ts # 超时 / 重试 / 幂等
435
+ ├── ui/
436
+ │ ├── shadow-host.ts # Shadow DOM 宿主与主题
437
+ │ ├── floating-button.ts # 悬浮按钮
438
+ │ ├── panel.vue # 反馈表单(Vue 单文件组件)
439
+ │ ├── panel-mount.ts # 面板挂载封装
440
+ │ ├── element-picker.ts # 页面元素拾取
441
+ │ ├── visibility.ts # 按钮显隐规则
442
+ │ ├── icons.ts # 内置图标
443
+ │ ├── screenshot.ts # 自动截图 / 图片压缩
444
+ │ └── styles.css.ts # 样式字符串
445
+ └── utils/ua.ts # 轻量 UA 解析
446
+ ```
447
+
448
+ ## 已知限制
449
+
450
+ - 页面在 SDK 加载之前产生的 Console / 异常无法补录;请把脚本放在业务脚本之前
451
+ - 页面如果覆盖 `console` / `fetch` / `XMLHttpRequest`,可能覆盖掉 SDK 的 hook;`destroy()` 之后再次初始化可恢复
452
+ - 截图是 DOM 重绘,复杂页面可能有偏差
453
+ - 会话不持久化;刷新页面后采集缓冲清空(补偿队列除外,它存在 IndexedDB)
454
+ - 暂不包含会话回放、截图标注、内容脱敏;需要时由业务侧在 `beforeSend` 里处理
455
+ - ESM / CJS 产物把 `vue` 作为 peer dependency(反馈面板用 Vue 渲染,面板 chunk 是静态 import,打包器必须能解析到);非 Vue 项目直接用 IIFE 产物即可
456
+ - 多实例 `createClient()` 会各自包装全局 API,每个实例都会采集一份,按需使用
457
+ - 需要还原 HAR 时,`network[]` 已包含 method / URL / status / 请求体 / 响应体 / 可选请求头响应头 / 耗时分解;但 JS 拿不到 Cookie、HTTP 版本、IP、缓存命中等浏览器内部字段,跨域头也受 CORS 限制,不等同于完整 HAR
458
+ - sourcemap 解析在网关 / 查询端完成,SDK 只负责上报 `release` 与 `buildId`
459
+
460
+ ## 许可证
461
+
462
+ 本项目 MIT。第三方依赖声明见 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。
@@ -0,0 +1,39 @@
1
+ # Third-Party Notices
2
+
3
+ 本项目分发两种产物,内联的第三方代码不同:
4
+
5
+ - **CDN 产物**:`dist/bug-tap.min.js` 内联 Vue 3 runtime 与 css-selector-generator;`dist/bug-tap-screenshot.min.js` 内联 html2canvas-pro。`dist/bug-tap-vue.min.js` 为零依赖插件。
6
+ - **ESM 产物**:`dist/bug-tap.js` 把以下依赖全部作为 external,由使用方的打包器解析。
7
+
8
+ ## 运行时依赖
9
+
10
+ | 依赖 | 版本 | 许可证 | 项目地址 |
11
+ |---|---|---|---|
12
+ | html2canvas-pro | 1.6.7 | MIT | https://github.com/yorickshan/html2canvas-pro |
13
+ | css-selector-generator | 3.9.4 | MIT | https://github.com/rubensworks/css-selector-generator.js |
14
+ | vue(optional peer) | 3.x | MIT | https://github.com/vuejs/core |
15
+
16
+ ## html2canvas-pro 的传递依赖
17
+
18
+ CDN 的截图库产物会一并内联以下代码:
19
+
20
+ | 依赖 | 版本 | 许可证 | 项目地址 |
21
+ |---|---|---|---|
22
+ | css-line-break | 2.1.0 | MIT | https://github.com/niklasvh/css-line-break |
23
+ | text-segmentation | 1.0.3 | MIT | https://github.com/niklasvh/text-segmentation |
24
+ | utrie | 1.0.2 | MIT | https://github.com/niklasvh/utrie |
25
+
26
+ ## 说明
27
+
28
+ - 以上依赖均为 MIT 许可证,未修改其源码。
29
+ - `bug-tap-vue.min.js` 与 `bug-tap-vue.js` 不引入任何 Vue 实现,只通过鸭子类型访问 `config.errorHandler` 与 `router.afterEach`。
30
+ - 开发期依赖(vite、vitest、playwright、jsdom、typescript、vue-router 等)不进入分发产物。
31
+ - 若以 ESM 方式分发并依赖使用方的打包器,最终产物中的许可证义务由使用方一并承担。
32
+
33
+ ## MIT License 摘要
34
+
35
+ Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
36
+
37
+ The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
38
+
39
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.