@be-link/cls-logger 1.0.11 → 1.0.12

package/README.md

@@ -2,79 +2,86 @@
 
 腾讯云 CLS（`tencentcloud-cls-sdk-js-web` / `tencentcloud-cls-sdk-js-mini`）日志上报封装，支持 Web、H5 和小程序环境，提供统一的调用方式。
 
+## 特性
+
+- 自动环境适配（Web / H5 / 小程序）
+- 内存队列批量上报，减少网络请求
+- 页面关闭时 `sendBeacon` 保证日志不丢失
+- 支持浏览器空闲时上报（`requestIdleCallback`）
+- 错误即时上报，信息日志批量上报
+- 自动采集：请求监控、性能监控、错误监控、行为埋点
+- 失败重试 + 本地缓存兜底
+
 ## 安装
 
 ```bash
 pnpm add @be-link/cls-logger
 ```
 
-> **注意**：
->
-> 1. SDK 内部会自动根据运行环境加载对应的腾讯云 SDK（Web 或小程序），无需手动安装额外依赖。
-> 2. 如果业务对包体积有极致要求，建议使用**分环境引入方式**（见下文）。
+### 依赖说明
 
-## 使用
+| 入口                       | 依赖                                         | 说明                                |
+| -------------------------- | -------------------------------------------- | ----------------------------------- |
+| `@be-link/cls-logger`      | `tencentcloud-cls-sdk-js-web`                | 统一入口，自动适配环境              |
+| `@be-link/cls-logger/web`  | `tencentcloud-cls-sdk-js-web` + `web-vitals` | Web/H5 专用，含 Web Vitals 性能监控 |
+| `@be-link/cls-logger/mini` | `tencentcloud-cls-sdk-js-mini`               | 小程序专用                          |
 
-### 1. 统一引入方式（推荐快速接入）
+> **注意**：所有依赖已内置，无需手动安装。
 
-无需关心运行环境（Web 或 小程序），SDK 内部会自动识别并适配。此方式包含全量逻辑，支持动态加载 SDK。
+## 快速开始
+
+### 1. 统一引入方式（推荐快速接入）
 
 ```ts
 import clsLogger from '@be-link/cls-logger';
 
-// 初始化（建议在应用入口处调用）
 clsLogger.init({
   projectId: 'my-project',
   appId: 'my-app-id',
-  // 默认配置可不传
-  // tencentCloud: {
-  //   endpoint: 'https://ap-shanghai.cls.tencentcs.com',
-  //   topicID: '17475bcd-6315-4b20-859c-e7b087fb3683',
-  // },
   source: 'my-source',
 });
 ```
 
-### 2. 分环境引入方式（推荐生产环境使用）
+### 2. 分环境引入方式（推荐生产环境）
 
-为了获得更小的包体积（Tree Shaking）和更清晰的逻辑，建议根据项目类型引入不同的入口。此方式将物理隔离 Web 和小程序的特有逻辑（如 Web 的 `fetch` 拦截 vs 小程序的 `wx.request` 拦截）。
-
-#### Web / H5 项目：
+#### Web / H5：
 
 ```ts
-// 仅包含 Web 相关逻辑，不再包含小程序代码
 import { clsLogger } from '@be-link/cls-logger/web';
 
 clsLogger.init({
   projectId: 'my-web-project',
-  // tencentCloud: { ... }, // 可选
   source: 'web-source',
 });
 ```
 
-#### 小程序项目：
+#### 小程序：
 
 ```ts
-// 仅包含小程序相关逻辑，不再包含 Web 代码
 import { clsLogger } from '@be-link/cls-logger/mini';
 
 clsLogger.init({
   projectId: 'my-mini-project',
-  appId: 'wx123456789', // 小程序建议传入 appId
-  // tencentCloud: { ... }, // 可选
+  appId: 'wx123456789',
   source: 'mini-source',
 });
 ```
 
-## 常用 API
+## API
 
-### 开发日志
+### 日志方法
 
 ```ts
-// info / warn / error
+// 信息日志（走批量队列）
 clsLogger.info('应用启动', { startUpTime: 120 });
 
-// Error 日志（支持直接传入 Error 对象，自动解析堆栈）
+// 警告日志（走批量队列）
+clsLogger.warn('资源加载慢', { duration: 3000 });
+
+// 错误日志（默认即时上报）
+clsLogger.error('支付失败', { orderId: '123' });
+
+// Error 对象（自动解析堆栈）
 try {
   doSomething();
 } catch (err) {
@@ -82,7 +89,17 @@ try {
 }
 ```
 
-### 自定义埋点 (Track)
+### 即时上报选项
+
+```ts
+// info/warn 强制即时上报
+clsLogger.info('重要事件', { data: 1 }, { immediate: true });
+
+// error 走批量队列（默认是即时上报）
+clsLogger.error('非关键错误', { data: 1 }, { immediate: false });
+```
+
+### 自定义埋点
 
 ```ts
 clsLogger.track('click_event', {
@@ -91,9 +108,7 @@ clsLogger.track('click_event', {
 });
 ```
 
-### 统计埋点 (Stat)
-
-用于简单的计数/分布统计。
+### 统计埋点
 
 ```ts
 clsLogger.stat({
@@ -104,67 +119,395 @@ clsLogger.stat({
 });
 ```
 
-## 功能特性
+## 配置项
+
+### 完整配置示例
+
+```ts
+clsLogger.init({
+  // 基础配置
+  enabled: true, // 是否启用，默认 true
+  projectId: 'my-project', // 项目标识
+  appId: 'wx123456789', // 应用 ID（小程序必填）
+  appVersion: '1.0.0', // 应用版本
+  source: 'my-source', // CLS source
+
+  // 腾讯云 CLS 配置
+  tencentCloud: {
+    endpoint: 'https://ap-shanghai.cls.tencentcs.com',
+    topicID: 'your-topic-id',
+    retry_times: 3,
+  },
+
+  // 批量上报配置
+  batch: {
+    maxSize: 50, // 队列达到此数量立即发送，默认 20
+    intervalMs: 1000, // 定时批量发送间隔，默认 500ms
+    startupDelayMs: 3000, // 启动合并窗口，默认 0（不启用）
+    startupMaxSize: 500, // 启动窗口内的队列阈值，默认 maxSize*10（至少200）
+    useIdleCallback: true, // 使用浏览器空闲时间上报，默认 false
+    idleTimeout: 3000, // 空闲回调超时时间，默认 3000ms
+  },
+
+  // 请求监控配置
+  requestMonitor: {
+    enabled: true, // 是否开启，默认 true
+    sampleRate: 1, // 采样率 0~1，默认 1
+    ignoreUrls: [/localhost/], // 忽略的 URL
+    includeMethod: true, // 是否携带 method，默认 true
+    includeQuery: true, // 是否携带 query，默认 true
+    includeBody: true, // 是否携带 body，默认 true
+    maxParamLength: 2000, // 参数最大长度，默认 2000
+  },
+
+  // 错误监控配置
+  errorMonitor: {
+    enabled: true, // 是否开启，默认 true
+    sampleRate: 1, // 采样率 0~1，默认 1
+    captureResourceError: true, // 是否采集资源加载错误，默认 true
+    maxTextLength: 4000, // stack/message 最大长度，默认 4000
+    dedupeWindowMs: 3000, // 错误去重窗口，默认 3000ms
+    dedupeMaxKeys: 200, // 去重缓存最大 key 数，默认 200
+    ignoreMessages: [
+      // 忽略的错误信息（默认值）
+      'Script error.',
+      'Script error',
+      /^ResizeObserver loop/,
+      'Permission was denied',
+    ],
+  },
+
+  // 性能监控配置
+  performanceMonitor: {
+    enabled: true, // 是否开启，默认 true
+    sampleRate: 1, // 采样率 0~1，默认 1
+    webVitals: true, // 是否采集 Web Vitals（含 TTFB），默认 true
+    resourceTiming: true, // 是否采集资源加载耗时，默认 true
+    ignoreUrls: [/localhost/], // 忽略的资源 URL
+    maxTextLength: 2000, // 性能指标文本最大长度，默认 2000
+  },
+
+  // 行为埋点配置
+  behaviorMonitor: {
+    enabled: true, // 是否开启，默认 true
+    pv: true, // PV 是否开启，默认 true
+    uv: true, // UV 是否开启，默认 true
+    click: true, // 点击是否开启，默认 true
+    sampleRate: 1, // 采样率 0~1，默认 1
+    uvExpireDays: 30, // UV 标识过期天数，默认 30
+    clickTrackIdAttr: 'data-track-id', // 点击元素埋点标识属性名
+    clickMaxTextLength: 120, // 点击文本最大长度，默认 120
+  },
+
+  // 设备信息配置
+  deviceInfo: {
+    enabled: true, // 是否开启，默认 true
+    includeUserAgent: true, // 是否包含 UA，默认 true
+    includeNetwork: true, // 是否包含网络信息，默认 true
+  },
+
+  // 自定义基础字段
+  generateBaseFields: () => ({
+    userId: getUserId(),
+    userName: getUserName(),
+    environment: 'production',
+  }),
+});
+```
+
+## 常见场景配置
+
+### 场景 1：首屏请求过多
+
+页面首次加载时日志请求过多，影响其他请求：
+
+```ts
+clsLogger.init({
+  batch: {
+    startupDelayMs: 3000, // 启动 3 秒内的日志合并发送
+    startupMaxSize: 500, // 启动窗口内允许更多日志积累（防止 maxSize 打断合并）
+    maxSize: 100, // 正常运行时的队列阈值
+    intervalMs: 2000, // 延长批量间隔
+    useIdleCallback: true, // 等待延迟后在浏览器空闲时上报
+  },
+  performanceMonitor: {
+    resourceTiming: false, // 关闭资源监控（首屏资源多时可大幅减少日志量）
+  },
+});
+```
+
+> **说明**：`startupMaxSize` 确保启动窗口内不会因为 `maxSize` 被频繁触发而打断日志合并。
+
+### 场景 2：减少资源监控日志
+
+开发环境资源过多，或生产环境不需要全量资源监控：
+
+```ts
+clsLogger.init({
+  performanceMonitor: {
+    resourceTiming: false, // 关闭资源监控
+    // 或者采样
+    // sampleRate: 0.1,      // 10% 采样
+    // 或者过滤
+    // ignoreUrls: [/localhost/, /node_modules/],
+  },
+});
+```
+
+### 场景 3：过滤无意义的错误
+
+过滤第三方 SDK 的跨域错误：
+
+```ts
+clsLogger.init({
+  errorMonitor: {
+    ignoreMessages: [
+      // 默认规则
+      'Script error.',
+      'Script error',
+      /^ResizeObserver loop/,
+      'Permission was denied',
+      // 自定义规则
+      /火山SDK/,
+      /VolcEngine/,
+      /network error/i,
+    ],
+  },
+});
+```
+
+### 场景 4：高并发场景（直播间）
+
+```ts
+clsLogger.init({
+  batch: {
+    startupDelayMs: 3000, // 启动合并窗口
+    startupMaxSize: 500, // 启动窗口内的队列阈值
+    maxSize: 100, // 正常运行时的队列阈值
+    intervalMs: 2000, // 延长批量间隔
+    useIdleCallback: true, // 空闲时上报，不阻塞主线程
+  },
+  performanceMonitor: {
+    resourceTiming: false, // 关闭资源监控
+  },
+  requestMonitor: {
+    sampleRate: 0.1, // 请求监控采样 10%
+    ignoreUrls: [
+      /heartbeat/i, // 忽略心跳请求
+      /polling/i, // 忽略轮询请求
+      /danmaku|barrage/i, // 忽略弹幕请求
+    ],
+  },
+});
+```
+
+## 最佳实践
 
-### 1. 自动环境适配
+### 1. 批量配置的正确姿势
 
-- **Web / H5**: 自动采集浏览器环境信息（UserAgent、屏幕尺寸、网络状态等）。
-- **小程序**: 自动采集小程序环境信息（系统信息、微信版本、网络类型等）。
+#### `useIdleCallback` 工作原理
 
-### 2. 请求监控 (Request Monitor)
+当 `useIdleCallback: true` 时，SDK 的上报流程为：
 
-默认开启。
+```
+日志产生 → 等待 intervalMs/startupDelayMs → 等待浏览器空闲 → 发送
+                    ↑ 最小等待时间            ↑ 在 idleTimeout 内空闲就发送
+```
 
-- **Web**: 拦截 `fetch` / `XMLHttpRequest`。
-- **小程序**: 拦截 `wx.request` / `wx.cloud.callFunction`。
+**关键点**：
 
-### 3. 性能监控 (Performance Monitor)
+- `intervalMs`/`startupDelayMs` 是**最小等待时间**，保证不会过早发送
+- `idleTimeout` 是空闲等待的**最大时间**，防止浏览器一直繁忙导致日志积压
 
-默认开启。
+#### `startupMaxSize` 的作用
 
-- **Web**: 采集 FCP, LCP, CLS, FID 等 Core Web Vitals 及资源加载耗时。
-- **小程序**: 支持采集页面首屏渲染耗时 (`firstRender`)、路由切换耗时 (`route`) 及启动耗时 (`appLaunch`)。
+启动阶段（`startupDelayMs` 窗口内）日志量通常很大（性能指标、资源加载等），如果 `maxSize` 设置过小，会频繁触发队列满而打断合并：
 
-### 4. 行为埋点 (Behavior Monitor)
+```ts
+// ❌ 错误配置：startupDelayMs 会被 maxSize 打断
+batch: {
+  startupDelayMs: 3000,
+  maxSize: 20,  // 启动期间可能产生 200+ 条日志，会触发 10+ 次发送
+}
+
+// ✅ 正确配置：使用 startupMaxSize 保护启动窗口
+batch: {
+  startupDelayMs: 3000,
+  maxSize: 20,
+  startupMaxSize: 500,  // 启动期间允许更多日志积累
+}
+```
 
-默认开启，支持 PV (Page View) 和 UV (User View) 自动上报。
+### 2. 推荐配置模板
 
-- **UV ID**: 自动生成并持久化。小程序环境下优先尝试使用 `openid`。
-- **点击追踪**: 自动监听点击事件。
-  - **Web**: 识别带 `data-track-id` 的元素。
-    ```html
-    <!-- HTML -->
-    <button data-track-id="submit_btn">提交</button>
-    ```
-  - **小程序**: 识别带 `data-track-id` 的组件（需在 `dataset` 中）。
-    ```html
-    <!-- WXML -->
-    <button data-track-id="submit_btn" bindtap="handleClick">提交</button>
-    ```
+#### 普通 H5 页面
+
+```ts
+clsLogger.init({
+  batch: {
+    startupDelayMs: 2000,
+    startupMaxSize: 300,
+    maxSize: 50,
+    intervalMs: 1000,
+    useIdleCallback: true,
+    idleTimeout: 3000,
+  },
+});
+```
 
-## 高级用法
+#### 首屏性能敏感（电商、活动页）
 
-### 内存队列与批量发送
+```ts
+clsLogger.init({
+  batch: {
+    startupDelayMs: 5000, // 更长的启动窗口
+    startupMaxSize: 500,
+    maxSize: 100,
+    intervalMs: 2000,
+    useIdleCallback: true,
+    idleTimeout: 5000,
+  },
+  performanceMonitor: {
+    sampleRate: 0.3, // 性能监控采样
+  },
+});
+```
 
-SDK 默认开启内存队列，每 500ms 或达到 20 条日志时自动批量上报，以减少网络请求次数。可通过 `batch` 参数配置：
+#### 高频交互页面（直播间、游戏）
 
 ```ts
 clsLogger.init({
   batch: {
-    maxSize: 20,
-    intervalMs: 500,
-    startupDelayMs: 1000, // 启动阶段合并窗口
+    startupDelayMs: 3000,
+    startupMaxSize: 500,
+    maxSize: 100,
+    intervalMs: 3000, // 更长的间隔
+    useIdleCallback: true,
+    idleTimeout: 5000,
+  },
+  performanceMonitor: {
+    resourceTiming: false, // 关闭资源监控
+  },
+  requestMonitor: {
+    sampleRate: 0.1, // 请求监控采样
+    ignoreUrls: [/heartbeat/, /polling/, /danmaku/],
   },
 });
 ```
 
-### 失败重试与本地缓存
+### 3. 日志量优化技巧
+
+| 优化项       | 配置                                       | 效果                      |
+| ------------ | ------------------------------------------ | ------------------------- |
+| 关闭资源监控 | `performanceMonitor.resourceTiming: false` | 减少 80%+ 的 perf 日志    |
+| 性能采样     | `performanceMonitor.sampleRate: 0.1`       | 只采集 10% 用户的性能数据 |
+| 请求采样     | `requestMonitor.sampleRate: 0.1`           | 只采集 10% 的请求日志     |
+| 忽略高频请求 | `requestMonitor.ignoreUrls: [/heartbeat/]` | 过滤心跳等高频请求        |
+| 错误去重     | `errorMonitor.dedupeWindowMs: 5000`        | 5秒内相同错误只上报一次   |
+
+### 4. 常见问题排查
+
+#### 问题：首屏请求过多
+
+**现象**：页面加载时发出 10+ 个日志请求
+
+**排查步骤**：
 
-上报失败的日志会自动进入重试流程（指数退避算法）。若多次重试仍失败，日志会落盘到本地缓存（`localStorage` 或小程序 `Storage`），在下次应用启动时尝试重新上报。
+1. 检查 `startupDelayMs` 是否配置
+2. 检查 `startupMaxSize` 是否足够大（建议 300-500）
+3. 检查 `resourceTiming` 是否需要开启（这是日志量最大的来源）
 
-### 手动注入 SDK
+#### 问题：日志延迟过高
 
-在某些特殊构建环境（如某些不允许动态 require 的小程序框架）下，可以手动注入：
+**现象**：日志上报明显滞后
+
+**排查步骤**：
+
+1. 检查 `useIdleCallback` + `idleTimeout` 配置
+2. 检查 `intervalMs` 是否设置过大
+3. 考虑关闭 `useIdleCallback` 或减小 `idleTimeout`
+
+#### 问题：页面关闭丢日志
+
+**现象**：用户快速关闭页面时日志丢失
+
+**说明**：SDK 已通过 `sendBeacon` 处理此场景，如仍有丢失：
+
+1. 检查日志是否在 `memoryQueue` 中（可能还未触发 flush）
+2. 考虑对关键日志使用 `{ immediate: true }`
+
+## 功能说明
+
+### 1. 批量上报机制
+
+SDK 使用内存队列批量上报日志：
+
+| 触发条件 | 说明                                                    |
+| -------- | ------------------------------------------------------- |
+| 队列满   | 达到 `maxSize`（启动窗口内为 `startupMaxSize`）立即发送 |
+| 定时器   | 每 `intervalMs` 毫秒发送一次                            |
+| 页面关闭 | `visibilitychange` + `pagehide` 触发 `sendBeacon` 发送  |
+| 启动合并 | `startupDelayMs` 窗口内的日志尽量合并                   |
+| 空闲上报 | `useIdleCallback` 开启时，等待浏览器空闲后发送          |
+
+### 2. 即时上报 vs 批量上报
+
+| 方法      | 默认行为 | 说明                                                     |
+| --------- | -------- | -------------------------------------------------------- |
+| `error()` | 即时上报 | 错误需要及时发现，可通过 `{ immediate: false }` 改为批量 |
+| `info()`  | 批量上报 | 可通过 `{ immediate: true }` 改为即时                    |
+| `warn()`  | 批量上报 | 可通过 `{ immediate: true }` 改为即时                    |
+| `track()` | 批量上报 | -                                                        |
+
+### 3. 页面关闭保障
+
+页面关闭时（`visibilitychange` / `pagehide`），SDK 会：
+
+1. 使用 `navigator.sendBeacon` 同步发送队列中的日志
+2. 如果 `sendBeacon` 不可用，将日志缓存到本地存储
+3. 下次启动时自动重试发送缓存的日志
+
+### 4. 失败重试机制
+
+- 上报失败后使用指数退避算法重试
+- 多次重试仍失败，日志落盘到本地缓存
+- 下次应用启动时自动尝试重新上报
+- 本地缓存最多保留 200 条（可配置 `failedCacheMax`）
+
+### 5. 自动采集内容
+
+#### 请求监控
+
+- **Web**: 拦截 `fetch` / `XMLHttpRequest`
+- **小程序**: 拦截 `wx.request` / `wx.cloud.callFunction`
+
+#### 性能监控
+
+- **Web**: 使用 [Google web-vitals](https://github.com/GoogleChrome/web-vitals) 库实现
+  - **FCP** (First Contentful Paint): 首次内容渲染
+  - **LCP** (Largest Contentful Paint): 最大内容渲染（用户交互后自动停止）
+  - **CLS** (Cumulative Layout Shift): 累积布局偏移（5秒会话窗口算法）
+  - **INP** (Interaction to Next Paint): 交互到绘制延迟（替代 FID）
+  - **TTFB** (Time to First Byte): 首字节时间
+  - **资源加载耗时**: PerformanceResourceTiming
+  - 自动处理 BFCache 恢复时的指标重置
+  - 上报数据包含 `rating` 字段：`'good'` | `'needs-improvement'` | `'poor'`
+- **小程序**: 首屏渲染、路由切换、启动耗时
+
+#### 错误监控
+
+- **Web**: `window.onerror`, `unhandledrejection`, 资源加载错误
+- **小程序**: `wx.onError`, `wx.onUnhandledRejection`, `App.onError`
+
+#### 行为埋点
+
+- **PV**: 页面访问
+- **UV**: 用户访问（自动生成持久化 ID）
+- **点击**: 带 `data-track-id` 属性的元素点击
+
+## 手动注入 SDK
+
+在某些特殊构建环境下，可以手动注入 SDK：
 
 ```ts
 import { clsLogger } from '@be-link/cls-logger/mini';
@@ -172,6 +515,25 @@ import * as MiniSdk from 'tencentcloud-cls-sdk-js-mini';
 
 clsLogger.init({
   tencentCloud: { topicID: 'xxx', endpoint: 'xxx' },
-  sdk: MiniSdk, // 手动传入 SDK 实例
+  sdk: MiniSdk,
 });
 ```
+
+## 类型定义
+
+```ts
+import type {
+  ClsLoggerInitOptions,
+  BatchOptions,
+  ReportOptions,
+  RequestMonitorOptions,
+  ErrorMonitorOptions,
+  PerformanceMonitorOptions,
+  BehaviorMonitorOptions,
+  DeviceInfoOptions,
+} from '@be-link/cls-logger';
+```
+
+## License
+
+MIT

package/dist/ClsLoggerCore.d.ts

@@ -1,4 +1,4 @@
-import type { ClsLoggerInitOptions, ErrorMonitorOptions, EnvType, FlatFields, PerformanceMonitorOptions, PutOptions, QueueItem, ReportLog, RequestMonitorOptions, BehaviorMonitorOptions, DeviceInfoOptions } from './types';
+import type { ClsLoggerInitOptions, ErrorMonitorOptions, EnvType, FlatFields, PerformanceMonitorOptions, PutOptions, QueueItem, ReportLog, ReportOptions, RequestMonitorOptions, BehaviorMonitorOptions, DeviceInfoOptions } from './types';
 import type { ClsSdkModule } from './clsSdkTypes';
 /**
  * CLS Logger 核心基类
@@ -38,6 +38,11 @@ export declare abstract class ClsLoggerCore {
     protected batchTimerDueAt: number | null;
     protected initTs: number;
     protected startupDelayMs: number;
+    protected startupMaxSize: number;
+    protected useIdleCallback: boolean;
+    protected idleTimeout: number;
+    protected pendingIdleCallback: number | null;
+    protected visibilityCleanup: (() => void) | null;
     protected failedCacheKey: string;
     protected failedCacheMax: number;
     protected requestMonitorStarted: boolean;
@@ -75,8 +80,24 @@ export declare abstract class ClsLoggerCore {
      * 子类可按需重写（默认检测 wx）
      */
     protected detectEnvType(): EnvType;
-    init(options: ClsLoggerInitOptions): void;
+    init(options: ClsLoggerInitOptions): Promise<boolean>;
     private getBaseFields;
+    /**
+     * 设置页面可见性监听
+     * - visibilitychange: 页面隐藏时使用 sendBeacon 发送队列
+     * - pagehide: 作为移动端 fallback
+     */
+    private setupVisibilityListener;
+    /**
+     * 同步发送内存队列（使用 sendBeacon）
+     * - 用于页面关闭时确保数据发送
+     * - sendBeacon 不可用时降级为缓存到 localStorage
+     */
+    private flushBatchSync;
+    /**
+     * 构建 sendBeacon 的 payload
+     */
+    private buildSendBeaconPayload;
     private startRequestMonitor;
     private startErrorMonitor;
     private startPerformanceMonitor;
@@ -121,10 +142,21 @@ export declare abstract class ClsLoggerCore {
      * 参考《一、概述》：统一上报入口（内存队列 + 批量发送）
      */
     report(log: ReportLog): void;
+    /**
+     * 调度批量发送
+     * - 先使用 setTimeout 保证最小延迟（desiredDelay）
+     * - 若开启 useIdleCallback，在延迟结束后等待浏览器空闲再执行
+     */
+    private scheduleFlush;
+    /**
+     * 取消已调度的批量发送
+     * - 同时清理 setTimeout 和可能的 requestIdleCallback
+     */
+    private cancelScheduledFlush;
     private getDesiredBatchFlushDueAt;
-    info(message: string | Error, data?: FlatFields): void;
-    warn(message: string | Error, data?: FlatFields): void;
-    error(message: string | Error, data?: FlatFields): void;
+    info(message: string | Error, data?: FlatFields, options?: ReportOptions): void;
+    warn(message: string | Error, data?: FlatFields, options?: ReportOptions): void;
+    error(message: string | Error, data?: FlatFields, options?: ReportOptions): void;
     track(trackType: string, data?: FlatFields): void;
     /**
      * 立即发送内存队列

package/dist/ClsLoggerCore.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ClsLoggerCore.d.ts","sourceRoot":"","sources":["../src/ClsLoggerCore.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ClsLoggerCore.d.ts","sourceRoot":"","sources":["../src/ClsLoggerCore.ts"],"names":[],"mappings":"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"}