npm - @be-link/cls-logger - Versions diffs - 1.0.1-beta.21 → 1.0.1-beta.23 - Mend

@be-link/cls-logger 1.0.1-beta.21 → 1.0.1-beta.23

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 (13) hide show

package/README.md +161 -11
package/dist/ClsLoggerCore.d.ts +5 -2
package/dist/ClsLoggerCore.d.ts.map +1 -1
package/dist/index.esm.js +45 -21
package/dist/index.js +45 -21
package/dist/index.umd.js +45 -21
package/dist/mini.esm.js +45 -21
package/dist/mini.js +45 -21
package/dist/types.d.ts +10 -3
package/dist/types.d.ts.map +1 -1
package/dist/web.esm.js +45 -21
package/dist/web.js +45 -21
package/package.json +1 -1

package/README.md CHANGED Viewed

@@ -144,6 +144,7 @@ clsLogger.init({
     maxSize: 50, // 队列达到此数量立即发送，默认 20
     intervalMs: 1000, // 定时批量发送间隔，默认 500ms
     startupDelayMs: 3000, // 启动合并窗口，默认 0（不启用）
+    startupMaxSize: 500, // 启动窗口内的队列阈值，默认 maxSize*10（至少200）
     useIdleCallback: true, // 使用浏览器空闲时间上报，默认 false
     idleTimeout: 3000, // 空闲回调超时时间，默认 3000ms
   },
@@ -224,13 +225,19 @@ clsLogger.init({
 clsLogger.init({
   batch: {
     startupDelayMs: 3000, // 启动 3 秒内的日志合并发送
-    maxSize: 100, // 提高队列阈值
-    intervalMs: 1000, // 延长批量间隔
-    useIdleCallback: true, // 使用浏览器空闲时间上报
+    startupMaxSize: 500, // 启动窗口内允许更多日志积累（防止 maxSize 打断合并）
+    maxSize: 100, // 正常运行时的队列阈值
+    intervalMs: 2000, // 延长批量间隔
+    useIdleCallback: true, // 等待延迟后在浏览器空闲时上报
+  },
+  performanceMonitor: {
+    resourceTiming: false, // 关闭资源监控（首屏资源多时可大幅减少日志量）
   },
 });
 ```
+> **说明**：`startupMaxSize` 确保启动窗口内不会因为 `maxSize` 被频繁触发而打断日志合并。
 ### 场景 2：减少资源监控日志
 开发环境资源过多，或生产环境不需要全量资源监控：
@@ -274,31 +281,174 @@ clsLogger.init({
 ```ts
 clsLogger.init({
   batch: {
-    maxSize: 100, // 提高队列阈值
+    startupDelayMs: 3000, // 启动合并窗口
+    startupMaxSize: 500, // 启动窗口内的队列阈值
+    maxSize: 100, // 正常运行时的队列阈值
     intervalMs: 2000, // 延长批量间隔
-    useIdleCallback: true, // 空闲时上报
+    useIdleCallback: true, // 空闲时上报，不阻塞主线程
   },
   performanceMonitor: {
     resourceTiming: false, // 关闭资源监控
   },
   requestMonitor: {
     sampleRate: 0.1, // 请求监控采样 10%
+    ignoreUrls: [
+      /heartbeat/i, // 忽略心跳请求
+      /polling/i, // 忽略轮询请求
+      /danmaku|barrage/i, // 忽略弹幕请求
+    ],
   },
 });
 ```
+## 最佳实践
+### 1. 批量配置的正确姿势
+#### `useIdleCallback` 工作原理
+当 `useIdleCallback: true` 时，SDK 的上报流程为：
+```
+日志产生 → 等待 intervalMs/startupDelayMs → 等待浏览器空闲 → 发送
+                    ↑ 最小等待时间            ↑ 在 idleTimeout 内空闲就发送
+```
+**关键点**：
+- `intervalMs`/`startupDelayMs` 是**最小等待时间**，保证不会过早发送
+- `idleTimeout` 是空闲等待的**最大时间**，防止浏览器一直繁忙导致日志积压
+#### `startupMaxSize` 的作用
+启动阶段（`startupDelayMs` 窗口内）日志量通常很大（性能指标、资源加载等），如果 `maxSize` 设置过小，会频繁触发队列满而打断合并：
+```ts
+// ❌ 错误配置：startupDelayMs 会被 maxSize 打断
+batch: {
+  startupDelayMs: 3000,
+  maxSize: 20,  // 启动期间可能产生 200+ 条日志，会触发 10+ 次发送
+}
+// ✅ 正确配置：使用 startupMaxSize 保护启动窗口
+batch: {
+  startupDelayMs: 3000,
+  maxSize: 20,
+  startupMaxSize: 500,  // 启动期间允许更多日志积累
+}
+```
+### 2. 推荐配置模板
+#### 普通 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, // 性能监控采样
+  },
+});
+```
+#### 高频交互页面（直播间、游戏）
+```ts
+clsLogger.init({
+  batch: {
+    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+ 个日志请求
+**排查步骤**：
+1. 检查 `startupDelayMs` 是否配置
+2. 检查 `startupMaxSize` 是否足够大（建议 300-500）
+3. 检查 `resourceTiming` 是否需要开启（这是日志量最大的来源）
+#### 问题：日志延迟过高
+**现象**：日志上报明显滞后
+**排查步骤**：
+1. 检查 `useIdleCallback` + `idleTimeout` 配置
+2. 检查 `intervalMs` 是否设置过大
+3. 考虑关闭 `useIdleCallback` 或减小 `idleTimeout`
+#### 问题：页面关闭丢日志
+**现象**：用户快速关闭页面时日志丢失
+**说明**：SDK 已通过 `sendBeacon` 处理此场景，如仍有丢失：
+1. 检查日志是否在 `memoryQueue` 中（可能还未触发 flush）
+2. 考虑对关键日志使用 `{ immediate: true }`
 ## 功能说明
 ### 1. 批量上报机制
 SDK 使用内存队列批量上报日志：
-| 触发条件 | 说明                                                   |
-| -------- | ------------------------------------------------------ |
-| 队列满   | 达到 `maxSize` 立即发送                                |
-| 定时器   | 每 `intervalMs` 毫秒发送一次                           |
-| 页面关闭 | `visibilitychange` + `pagehide` 触发 `sendBeacon` 发送 |
-| 启动合并 | `startupDelayMs` 窗口内的日志尽量合并                  |
+| 触发条件 | 说明                                                    |
+| -------- | ------------------------------------------------------- |
+| 队列满   | 达到 `maxSize`（启动窗口内为 `startupMaxSize`）立即发送 |
+| 定时器   | 每 `intervalMs` 毫秒发送一次                            |
+| 页面关闭 | `visibilitychange` + `pagehide` 触发 `sendBeacon` 发送  |
+| 启动合并 | `startupDelayMs` 窗口内的日志尽量合并                   |
+| 空闲上报 | `useIdleCallback` 开启时，等待浏览器空闲后发送          |
 ### 2. 即时上报 vs 批量上报

package/dist/ClsLoggerCore.d.ts CHANGED Viewed

@@ -38,8 +38,10 @@ 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;
@@ -142,12 +144,13 @@ export declare abstract class ClsLoggerCore {
     report(log: ReportLog): void;
     /**
      * 调度批量发送
-     * - 支持 requestIdleCallback（浏览器空闲时执行）
-     * - 降级为 setTimeout
+     * - 先使用 setTimeout 保证最小延迟（desiredDelay）
+     * - 若开启 useIdleCallback，在延迟结束后等待浏览器空闲再执行
      */
     private scheduleFlush;
     /**
      * 取消已调度的批量发送
+     * - 同时清理 setTimeout 和可能的 requestIdleCallback
      */
     private cancelScheduledFlush;
     private getDesiredBatchFlushDueAt;

package/dist/ClsLoggerCore.d.ts.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"ClsLoggerCore.d.ts","sourceRoot":"","sources":["../src/ClsLoggerCore.ts"],"names":[],"mappings":"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~~IAgFzC~~,OAAO,CAAC,aAAa;IAwBrB;;;;OAIG;IACH,OAAO,CAAC,uBAAuB;IAyB/B;;;;OAIG;IACH,OAAO,CAAC,cAAc;IAyCtB;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAQ9B,OAAO,CAAC,mBAAmB;IAsB3B,OAAO,CAAC,iBAAiB;IASzB,OAAO,CAAC,uBAAuB;IAS/B,OAAO,CAAC,oBAAoB;IAW5B;;;OAGG;IACH,mBAAmB,IAAI,IAAI;IAU3B;;OAEG;IACG,WAAW,IAAI,OAAO,CAAC;QAAE,OAAO,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAA;KAAE,CAAC;IAsB3F;;;;OAIG;IACH,GAAG,CAAC,MAAM,EAAE,UAAU,EAAE,OAAO,GAAE,UAAe,GAAG,IAAI;YA2BzC,QAAQ;IAyBtB;;OAEG;IACH,OAAO,CAAC,IAAI,EAAE,OAAO,EAAE,YAAY,SAAS,EAAE,OAAO,GAAE,UAAe,GAAG,IAAI;IAK7E;;;OAGG;IACH,OAAO,CAAC,MAAM,EAAE,UAAU,EAAE,OAAO,GAAE,UAAe,GAAG,IAAI;IA8B3D;;OAEG;IACH,KAAK,IAAI,IAAI;IAOb;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,IAAI;YAcpB,aAAa;IA6B3B;;OAEG;IACH,MAAM,CAAC,GAAG,EAAE,SAAS,GAAG,IAAI;~~IAkC5B~~;;;;OAIG;IACH,OAAO,CAAC,aAAa;~~IAkBrB;;OAEG~~;IACH,OAAO,CAAC,oBAAoB;~~IAc5B~~,OAAO,CAAC,yBAAyB;IAUjC,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,KAAK,EAAE,IAAI,GAAE,UAAe,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,IAAI;IA6BnF,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,KAAK,EAAE,IAAI,GAAE,UAAe,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,IAAI;IA6BnF,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,KAAK,EAAE,IAAI,GAAE,UAAe,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,IAAI;IA8BpF,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,GAAE,UAAe,GAAG,IAAI;IASrD;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAejC,OAAO,CAAC,iBAAiB;YAmBX,cAAc;IAgC5B,OAAO,CAAC,mBAAmB;IAgB3B,OAAO,CAAC,qBAAqB;IAc7B,WAAW,IAAI,IAAI;~~IAmBnB~~;;OAEG;IACH,IAAI,CAAC,KAAK,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,GAAG,IAAI;CAcjG"}
1	+ {"version":3,"file":"ClsLoggerCore.d.ts","sourceRoot":"","sources":["../src/ClsLoggerCore.ts"],"names":[],"mappings":"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"}

package/dist/index.esm.js CHANGED Viewed

@@ -178,8 +178,10 @@ class ClsLoggerCore {
         this.batchTimerDueAt = null;
         this.initTs = 0;
         this.startupDelayMs = 0;
+        this.startupMaxSize = 0; // 启动窗口内的 maxSize，0 表示使用默认计算值
         this.useIdleCallback = false;
         this.idleTimeout = 3000;
+        this.pendingIdleCallback = null; // requestIdleCallback 的 id
         this.visibilityCleanup = null;
         // 参考文档：失败缓存 + 重试
         this.failedCacheKey = 'cls_failed_logs';
@@ -252,6 +254,8 @@ class ClsLoggerCore {
         this.startupDelayMs = options.batch?.startupDelayMs ?? this.startupDelayMs;
         this.useIdleCallback = options.batch?.useIdleCallback ?? this.useIdleCallback;
         this.idleTimeout = options.batch?.idleTimeout ?? this.idleTimeout;
+        // startupMaxSize：启动窗口内的队列阈值，默认为 maxSize * 10（至少 200）
+        this.startupMaxSize = options.batch?.startupMaxSize ?? Math.max(this.batchMaxSize * 10, 200);
         this.failedCacheKey = options.failedCacheKey ?? this.failedCacheKey;
         this.failedCacheMax = options.failedCacheMax ?? this.failedCacheMax;
         // 预热（避免首条日志触发 import/初始化开销）
@@ -627,11 +631,15 @@ class ClsLoggerCore {
             return;
         }
         this.memoryQueue.push(log);
-        if (this.memoryQueue.length >= this.batchMaxSize) {
+        const now = Date.now();
+        // 判断是否在启动合并窗口内
+        const inStartupWindow = this.startupDelayMs > 0 && now - this.initTs < this.startupDelayMs;
+        // 启动窗口内使用 startupMaxSize，正常情况使用 batchMaxSize
+        const effectiveMaxSize = inStartupWindow ? this.startupMaxSize : this.batchMaxSize;
+        if (this.memoryQueue.length >= effectiveMaxSize) {
             void this.flushBatch();
             return;
         }
-        const now = Date.now();
         const desiredDueAt = this.getDesiredBatchFlushDueAt(now);
         const desiredDelay = Math.max(0, desiredDueAt - now);
         if (!this.batchTimer) {
@@ -648,17 +656,19 @@ class ClsLoggerCore {
     }
     /**
      * 调度批量发送
-     * - 支持 requestIdleCallback（浏览器空闲时执行）
-     * - 降级为 setTimeout
+     * - 先使用 setTimeout 保证最小延迟（desiredDelay）
+     * - 若开启 useIdleCallback，在延迟结束后等待浏览器空闲再执行
      */
     scheduleFlush(desiredDelay) {
         if (this.useIdleCallback && typeof requestIdleCallback !== 'undefined') {
-            // 使用 requestIdleCallback，设置 timeout 保证最终执行
-            const idleId = requestIdleCallback(() => {
-                void this.flushBatch();
-            }, { timeout: Math.max(desiredDelay, this.idleTimeout) });
-            // 存储 idleId 以便清理（类型兼容处理）
-            this.batchTimer = idleId;
+            // 先 setTimeout 保证最小延迟，再 requestIdleCallback 在空闲时执行
+            this.batchTimer = setTimeout(() => {
+                const idleId = requestIdleCallback(() => {
+                    this.pendingIdleCallback = null;
+                    void this.flushBatch();
+                }, { timeout: this.idleTimeout });
+                this.pendingIdleCallback = idleId;
+            }, desiredDelay);
         }
         else {
             this.batchTimer = setTimeout(() => {
@@ -668,22 +678,29 @@ class ClsLoggerCore {
     }
     /**
      * 取消已调度的批量发送
+     * - 同时清理 setTimeout 和可能的 requestIdleCallback
      */
     cancelScheduledFlush() {
-        if (!this.batchTimer)
-            return;
-        try {
-            if (this.useIdleCallback && typeof cancelIdleCallback !== 'undefined') {
-                cancelIdleCallback(this.batchTimer);
-            }
-            else {
+        // 清理 setTimeout
+        if (this.batchTimer) {
+            try {
                 clearTimeout(this.batchTimer);
             }
+            catch {
+                // ignore
+            }
+            this.batchTimer = null;
         }
-        catch {
-            // ignore
+        // 清理可能的 pendingIdleCallback
+        if (this.pendingIdleCallback !== null && typeof cancelIdleCallback !== 'undefined') {
+            try {
+                cancelIdleCallback(this.pendingIdleCallback);
+            }
+            catch {
+                // ignore
+            }
+            this.pendingIdleCallback = null;
         }
-        this.batchTimer = null;
     }
     getDesiredBatchFlushDueAt(nowTs) {
         const start = this.initTs || nowTs;
@@ -896,7 +913,14 @@ class ClsLoggerCore {
         // 先清空，再尝试发送
         writeStringStorage(this.failedCacheKey, JSON.stringify([]));
         this.memoryQueue.unshift(...logs);
-        void this.flushBatch();
+        // 触发定时器而非直接 flush，以尊重 startupDelayMs 配置
+        if (!this.batchTimer) {
+            const now = Date.now();
+            const desiredDueAt = this.getDesiredBatchFlushDueAt(now);
+            const desiredDelay = Math.max(0, desiredDueAt - now);
+            this.batchTimerDueAt = desiredDueAt;
+            this.scheduleFlush(desiredDelay);
+        }
     }
     /**
      * 统计/计数类日志：按字段展开上报（若 data 为空默认 1）

package/dist/index.js CHANGED Viewed

@@ -182,8 +182,10 @@ class ClsLoggerCore {
         this.batchTimerDueAt = null;
         this.initTs = 0;
         this.startupDelayMs = 0;
+        this.startupMaxSize = 0; // 启动窗口内的 maxSize，0 表示使用默认计算值
         this.useIdleCallback = false;
         this.idleTimeout = 3000;
+        this.pendingIdleCallback = null; // requestIdleCallback 的 id
         this.visibilityCleanup = null;
         // 参考文档：失败缓存 + 重试
         this.failedCacheKey = 'cls_failed_logs';
@@ -256,6 +258,8 @@ class ClsLoggerCore {
         this.startupDelayMs = options.batch?.startupDelayMs ?? this.startupDelayMs;
         this.useIdleCallback = options.batch?.useIdleCallback ?? this.useIdleCallback;
         this.idleTimeout = options.batch?.idleTimeout ?? this.idleTimeout;
+        // startupMaxSize：启动窗口内的队列阈值，默认为 maxSize * 10（至少 200）
+        this.startupMaxSize = options.batch?.startupMaxSize ?? Math.max(this.batchMaxSize * 10, 200);
         this.failedCacheKey = options.failedCacheKey ?? this.failedCacheKey;
         this.failedCacheMax = options.failedCacheMax ?? this.failedCacheMax;
         // 预热（避免首条日志触发 import/初始化开销）
@@ -631,11 +635,15 @@ class ClsLoggerCore {
             return;
         }
         this.memoryQueue.push(log);
-        if (this.memoryQueue.length >= this.batchMaxSize) {
+        const now = Date.now();
+        // 判断是否在启动合并窗口内
+        const inStartupWindow = this.startupDelayMs > 0 && now - this.initTs < this.startupDelayMs;
+        // 启动窗口内使用 startupMaxSize，正常情况使用 batchMaxSize
+        const effectiveMaxSize = inStartupWindow ? this.startupMaxSize : this.batchMaxSize;
+        if (this.memoryQueue.length >= effectiveMaxSize) {
             void this.flushBatch();
             return;
         }
-        const now = Date.now();
         const desiredDueAt = this.getDesiredBatchFlushDueAt(now);
         const desiredDelay = Math.max(0, desiredDueAt - now);
         if (!this.batchTimer) {
@@ -652,17 +660,19 @@ class ClsLoggerCore {
     }
     /**
      * 调度批量发送
-     * - 支持 requestIdleCallback（浏览器空闲时执行）
-     * - 降级为 setTimeout
+     * - 先使用 setTimeout 保证最小延迟（desiredDelay）
+     * - 若开启 useIdleCallback，在延迟结束后等待浏览器空闲再执行
      */
     scheduleFlush(desiredDelay) {
         if (this.useIdleCallback && typeof requestIdleCallback !== 'undefined') {
-            // 使用 requestIdleCallback，设置 timeout 保证最终执行
-            const idleId = requestIdleCallback(() => {
-                void this.flushBatch();
-            }, { timeout: Math.max(desiredDelay, this.idleTimeout) });
-            // 存储 idleId 以便清理（类型兼容处理）
-            this.batchTimer = idleId;
+            // 先 setTimeout 保证最小延迟，再 requestIdleCallback 在空闲时执行
+            this.batchTimer = setTimeout(() => {
+                const idleId = requestIdleCallback(() => {
+                    this.pendingIdleCallback = null;
+                    void this.flushBatch();
+                }, { timeout: this.idleTimeout });
+                this.pendingIdleCallback = idleId;
+            }, desiredDelay);
         }
         else {
             this.batchTimer = setTimeout(() => {
@@ -672,22 +682,29 @@ class ClsLoggerCore {
     }
     /**
      * 取消已调度的批量发送
+     * - 同时清理 setTimeout 和可能的 requestIdleCallback
      */
     cancelScheduledFlush() {
-        if (!this.batchTimer)
-            return;
-        try {
-            if (this.useIdleCallback && typeof cancelIdleCallback !== 'undefined') {
-                cancelIdleCallback(this.batchTimer);
-            }
-            else {
+        // 清理 setTimeout
+        if (this.batchTimer) {
+            try {
                 clearTimeout(this.batchTimer);
             }
+            catch {
+                // ignore
+            }
+            this.batchTimer = null;
         }
-        catch {
-            // ignore
+        // 清理可能的 pendingIdleCallback
+        if (this.pendingIdleCallback !== null && typeof cancelIdleCallback !== 'undefined') {
+            try {
+                cancelIdleCallback(this.pendingIdleCallback);
+            }
+            catch {
+                // ignore
+            }
+            this.pendingIdleCallback = null;
         }
-        this.batchTimer = null;
     }
     getDesiredBatchFlushDueAt(nowTs) {
         const start = this.initTs || nowTs;
@@ -900,7 +917,14 @@ class ClsLoggerCore {
         // 先清空，再尝试发送
         writeStringStorage(this.failedCacheKey, JSON.stringify([]));
         this.memoryQueue.unshift(...logs);
-        void this.flushBatch();
+        // 触发定时器而非直接 flush，以尊重 startupDelayMs 配置
+        if (!this.batchTimer) {
+            const now = Date.now();
+            const desiredDueAt = this.getDesiredBatchFlushDueAt(now);
+            const desiredDelay = Math.max(0, desiredDueAt - now);
+            this.batchTimerDueAt = desiredDueAt;
+            this.scheduleFlush(desiredDelay);
+        }
     }
     /**
      * 统计/计数类日志：按字段展开上报（若 data 为空默认 1）

package/dist/index.umd.js CHANGED Viewed

@@ -182,8 +182,10 @@
             this.batchTimerDueAt = null;
             this.initTs = 0;
             this.startupDelayMs = 0;
+            this.startupMaxSize = 0; // 启动窗口内的 maxSize，0 表示使用默认计算值
             this.useIdleCallback = false;
             this.idleTimeout = 3000;
+            this.pendingIdleCallback = null; // requestIdleCallback 的 id
             this.visibilityCleanup = null;
             // 参考文档：失败缓存 + 重试
             this.failedCacheKey = 'cls_failed_logs';
@@ -256,6 +258,8 @@
             this.startupDelayMs = options.batch?.startupDelayMs ?? this.startupDelayMs;
             this.useIdleCallback = options.batch?.useIdleCallback ?? this.useIdleCallback;
             this.idleTimeout = options.batch?.idleTimeout ?? this.idleTimeout;
+            // startupMaxSize：启动窗口内的队列阈值，默认为 maxSize * 10（至少 200）
+            this.startupMaxSize = options.batch?.startupMaxSize ?? Math.max(this.batchMaxSize * 10, 200);
             this.failedCacheKey = options.failedCacheKey ?? this.failedCacheKey;
             this.failedCacheMax = options.failedCacheMax ?? this.failedCacheMax;
             // 预热（避免首条日志触发 import/初始化开销）
@@ -631,11 +635,15 @@
                 return;
             }
             this.memoryQueue.push(log);
-            if (this.memoryQueue.length >= this.batchMaxSize) {
+            const now = Date.now();
+            // 判断是否在启动合并窗口内
+            const inStartupWindow = this.startupDelayMs > 0 && now - this.initTs < this.startupDelayMs;
+            // 启动窗口内使用 startupMaxSize，正常情况使用 batchMaxSize
+            const effectiveMaxSize = inStartupWindow ? this.startupMaxSize : this.batchMaxSize;
+            if (this.memoryQueue.length >= effectiveMaxSize) {
                 void this.flushBatch();
                 return;
             }
-            const now = Date.now();
             const desiredDueAt = this.getDesiredBatchFlushDueAt(now);
             const desiredDelay = Math.max(0, desiredDueAt - now);
             if (!this.batchTimer) {
@@ -652,17 +660,19 @@
         }
         /**
          * 调度批量发送
-         * - 支持 requestIdleCallback（浏览器空闲时执行）
-         * - 降级为 setTimeout
+         * - 先使用 setTimeout 保证最小延迟（desiredDelay）
+         * - 若开启 useIdleCallback，在延迟结束后等待浏览器空闲再执行
          */
         scheduleFlush(desiredDelay) {
             if (this.useIdleCallback && typeof requestIdleCallback !== 'undefined') {
-                // 使用 requestIdleCallback，设置 timeout 保证最终执行
-                const idleId = requestIdleCallback(() => {
-                    void this.flushBatch();
-                }, { timeout: Math.max(desiredDelay, this.idleTimeout) });
-                // 存储 idleId 以便清理（类型兼容处理）
-                this.batchTimer = idleId;
+                // 先 setTimeout 保证最小延迟，再 requestIdleCallback 在空闲时执行
+                this.batchTimer = setTimeout(() => {
+                    const idleId = requestIdleCallback(() => {
+                        this.pendingIdleCallback = null;
+                        void this.flushBatch();
+                    }, { timeout: this.idleTimeout });
+                    this.pendingIdleCallback = idleId;
+                }, desiredDelay);
             }
             else {
                 this.batchTimer = setTimeout(() => {
@@ -672,22 +682,29 @@
         }
         /**
          * 取消已调度的批量发送
+         * - 同时清理 setTimeout 和可能的 requestIdleCallback
          */
         cancelScheduledFlush() {
-            if (!this.batchTimer)
-                return;
-            try {
-                if (this.useIdleCallback && typeof cancelIdleCallback !== 'undefined') {
-                    cancelIdleCallback(this.batchTimer);
-                }
-                else {
+            // 清理 setTimeout
+            if (this.batchTimer) {
+                try {
                     clearTimeout(this.batchTimer);
                 }
+                catch {
+                    // ignore
+                }
+                this.batchTimer = null;
             }
-            catch {
-                // ignore
+            // 清理可能的 pendingIdleCallback
+            if (this.pendingIdleCallback !== null && typeof cancelIdleCallback !== 'undefined') {
+                try {
+                    cancelIdleCallback(this.pendingIdleCallback);
+                }
+                catch {
+                    // ignore
+                }
+                this.pendingIdleCallback = null;
             }
-            this.batchTimer = null;
         }
         getDesiredBatchFlushDueAt(nowTs) {
             const start = this.initTs || nowTs;
@@ -900,7 +917,14 @@
             // 先清空，再尝试发送
             writeStringStorage(this.failedCacheKey, JSON.stringify([]));
             this.memoryQueue.unshift(...logs);
-            void this.flushBatch();
+            // 触发定时器而非直接 flush，以尊重 startupDelayMs 配置
+            if (!this.batchTimer) {
+                const now = Date.now();
+                const desiredDueAt = this.getDesiredBatchFlushDueAt(now);
+                const desiredDelay = Math.max(0, desiredDueAt - now);
+                this.batchTimerDueAt = desiredDueAt;
+                this.scheduleFlush(desiredDelay);
+            }
         }
         /**
          * 统计/计数类日志：按字段展开上报（若 data 为空默认 1）

package/dist/mini.esm.js CHANGED Viewed

@@ -178,8 +178,10 @@ class ClsLoggerCore {
         this.batchTimerDueAt = null;
         this.initTs = 0;
         this.startupDelayMs = 0;
+        this.startupMaxSize = 0; // 启动窗口内的 maxSize，0 表示使用默认计算值
         this.useIdleCallback = false;
         this.idleTimeout = 3000;
+        this.pendingIdleCallback = null; // requestIdleCallback 的 id
         this.visibilityCleanup = null;
         // 参考文档：失败缓存 + 重试
         this.failedCacheKey = 'cls_failed_logs';
@@ -252,6 +254,8 @@ class ClsLoggerCore {
         this.startupDelayMs = options.batch?.startupDelayMs ?? this.startupDelayMs;
         this.useIdleCallback = options.batch?.useIdleCallback ?? this.useIdleCallback;
         this.idleTimeout = options.batch?.idleTimeout ?? this.idleTimeout;
+        // startupMaxSize：启动窗口内的队列阈值，默认为 maxSize * 10（至少 200）
+        this.startupMaxSize = options.batch?.startupMaxSize ?? Math.max(this.batchMaxSize * 10, 200);
         this.failedCacheKey = options.failedCacheKey ?? this.failedCacheKey;
         this.failedCacheMax = options.failedCacheMax ?? this.failedCacheMax;
         // 预热（避免首条日志触发 import/初始化开销）
@@ -627,11 +631,15 @@ class ClsLoggerCore {
             return;
         }
         this.memoryQueue.push(log);
-        if (this.memoryQueue.length >= this.batchMaxSize) {
+        const now = Date.now();
+        // 判断是否在启动合并窗口内
+        const inStartupWindow = this.startupDelayMs > 0 && now - this.initTs < this.startupDelayMs;
+        // 启动窗口内使用 startupMaxSize，正常情况使用 batchMaxSize
+        const effectiveMaxSize = inStartupWindow ? this.startupMaxSize : this.batchMaxSize;
+        if (this.memoryQueue.length >= effectiveMaxSize) {
             void this.flushBatch();
             return;
         }
-        const now = Date.now();
         const desiredDueAt = this.getDesiredBatchFlushDueAt(now);
         const desiredDelay = Math.max(0, desiredDueAt - now);
         if (!this.batchTimer) {
@@ -648,17 +656,19 @@ class ClsLoggerCore {
     }
     /**
      * 调度批量发送
-     * - 支持 requestIdleCallback（浏览器空闲时执行）
-     * - 降级为 setTimeout
+     * - 先使用 setTimeout 保证最小延迟（desiredDelay）
+     * - 若开启 useIdleCallback，在延迟结束后等待浏览器空闲再执行
      */
     scheduleFlush(desiredDelay) {
         if (this.useIdleCallback && typeof requestIdleCallback !== 'undefined') {
-            // 使用 requestIdleCallback，设置 timeout 保证最终执行
-            const idleId = requestIdleCallback(() => {
-                void this.flushBatch();
-            }, { timeout: Math.max(desiredDelay, this.idleTimeout) });
-            // 存储 idleId 以便清理（类型兼容处理）
-            this.batchTimer = idleId;
+            // 先 setTimeout 保证最小延迟，再 requestIdleCallback 在空闲时执行
+            this.batchTimer = setTimeout(() => {
+                const idleId = requestIdleCallback(() => {
+                    this.pendingIdleCallback = null;
+                    void this.flushBatch();
+                }, { timeout: this.idleTimeout });
+                this.pendingIdleCallback = idleId;
+            }, desiredDelay);
         }
         else {
             this.batchTimer = setTimeout(() => {
@@ -668,22 +678,29 @@ class ClsLoggerCore {
     }
     /**
      * 取消已调度的批量发送
+     * - 同时清理 setTimeout 和可能的 requestIdleCallback
      */
     cancelScheduledFlush() {
-        if (!this.batchTimer)
-            return;
-        try {
-            if (this.useIdleCallback && typeof cancelIdleCallback !== 'undefined') {
-                cancelIdleCallback(this.batchTimer);
-            }
-            else {
+        // 清理 setTimeout
+        if (this.batchTimer) {
+            try {
                 clearTimeout(this.batchTimer);
             }
+            catch {
+                // ignore
+            }
+            this.batchTimer = null;
         }
-        catch {
-            // ignore
+        // 清理可能的 pendingIdleCallback
+        if (this.pendingIdleCallback !== null && typeof cancelIdleCallback !== 'undefined') {
+            try {
+                cancelIdleCallback(this.pendingIdleCallback);
+            }
+            catch {
+                // ignore
+            }
+            this.pendingIdleCallback = null;
         }
-        this.batchTimer = null;
     }
     getDesiredBatchFlushDueAt(nowTs) {
         const start = this.initTs || nowTs;
@@ -896,7 +913,14 @@ class ClsLoggerCore {
         // 先清空，再尝试发送
         writeStringStorage(this.failedCacheKey, JSON.stringify([]));
         this.memoryQueue.unshift(...logs);
-        void this.flushBatch();
+        // 触发定时器而非直接 flush，以尊重 startupDelayMs 配置
+        if (!this.batchTimer) {
+            const now = Date.now();
+            const desiredDueAt = this.getDesiredBatchFlushDueAt(now);
+            const desiredDelay = Math.max(0, desiredDueAt - now);
+            this.batchTimerDueAt = desiredDueAt;
+            this.scheduleFlush(desiredDelay);
+        }
     }
     /**
      * 统计/计数类日志：按字段展开上报（若 data 为空默认 1）

package/dist/mini.js CHANGED Viewed

@@ -201,8 +201,10 @@ class ClsLoggerCore {
         this.batchTimerDueAt = null;
         this.initTs = 0;
         this.startupDelayMs = 0;
+        this.startupMaxSize = 0; // 启动窗口内的 maxSize，0 表示使用默认计算值
         this.useIdleCallback = false;
         this.idleTimeout = 3000;
+        this.pendingIdleCallback = null; // requestIdleCallback 的 id
         this.visibilityCleanup = null;
         // 参考文档：失败缓存 + 重试
         this.failedCacheKey = 'cls_failed_logs';
@@ -275,6 +277,8 @@ class ClsLoggerCore {
         this.startupDelayMs = options.batch?.startupDelayMs ?? this.startupDelayMs;
         this.useIdleCallback = options.batch?.useIdleCallback ?? this.useIdleCallback;
         this.idleTimeout = options.batch?.idleTimeout ?? this.idleTimeout;
+        // startupMaxSize：启动窗口内的队列阈值，默认为 maxSize * 10（至少 200）
+        this.startupMaxSize = options.batch?.startupMaxSize ?? Math.max(this.batchMaxSize * 10, 200);
         this.failedCacheKey = options.failedCacheKey ?? this.failedCacheKey;
         this.failedCacheMax = options.failedCacheMax ?? this.failedCacheMax;
         // 预热（避免首条日志触发 import/初始化开销）
@@ -650,11 +654,15 @@ class ClsLoggerCore {
             return;
         }
         this.memoryQueue.push(log);
-        if (this.memoryQueue.length >= this.batchMaxSize) {
+        const now = Date.now();
+        // 判断是否在启动合并窗口内
+        const inStartupWindow = this.startupDelayMs > 0 && now - this.initTs < this.startupDelayMs;
+        // 启动窗口内使用 startupMaxSize，正常情况使用 batchMaxSize
+        const effectiveMaxSize = inStartupWindow ? this.startupMaxSize : this.batchMaxSize;
+        if (this.memoryQueue.length >= effectiveMaxSize) {
             void this.flushBatch();
             return;
         }
-        const now = Date.now();
         const desiredDueAt = this.getDesiredBatchFlushDueAt(now);
         const desiredDelay = Math.max(0, desiredDueAt - now);
         if (!this.batchTimer) {
@@ -671,17 +679,19 @@ class ClsLoggerCore {
     }
     /**
      * 调度批量发送
-     * - 支持 requestIdleCallback（浏览器空闲时执行）
-     * - 降级为 setTimeout
+     * - 先使用 setTimeout 保证最小延迟（desiredDelay）
+     * - 若开启 useIdleCallback，在延迟结束后等待浏览器空闲再执行
      */
     scheduleFlush(desiredDelay) {
         if (this.useIdleCallback && typeof requestIdleCallback !== 'undefined') {
-            // 使用 requestIdleCallback，设置 timeout 保证最终执行
-            const idleId = requestIdleCallback(() => {
-                void this.flushBatch();
-            }, { timeout: Math.max(desiredDelay, this.idleTimeout) });
-            // 存储 idleId 以便清理（类型兼容处理）
-            this.batchTimer = idleId;
+            // 先 setTimeout 保证最小延迟，再 requestIdleCallback 在空闲时执行
+            this.batchTimer = setTimeout(() => {
+                const idleId = requestIdleCallback(() => {
+                    this.pendingIdleCallback = null;
+                    void this.flushBatch();
+                }, { timeout: this.idleTimeout });
+                this.pendingIdleCallback = idleId;
+            }, desiredDelay);
         }
         else {
             this.batchTimer = setTimeout(() => {
@@ -691,22 +701,29 @@ class ClsLoggerCore {
     }
     /**
      * 取消已调度的批量发送
+     * - 同时清理 setTimeout 和可能的 requestIdleCallback
      */
     cancelScheduledFlush() {
-        if (!this.batchTimer)
-            return;
-        try {
-            if (this.useIdleCallback && typeof cancelIdleCallback !== 'undefined') {
-                cancelIdleCallback(this.batchTimer);
-            }
-            else {
+        // 清理 setTimeout
+        if (this.batchTimer) {
+            try {
                 clearTimeout(this.batchTimer);
             }
+            catch {
+                // ignore
+            }
+            this.batchTimer = null;
         }
-        catch {
-            // ignore
+        // 清理可能的 pendingIdleCallback
+        if (this.pendingIdleCallback !== null && typeof cancelIdleCallback !== 'undefined') {
+            try {
+                cancelIdleCallback(this.pendingIdleCallback);
+            }
+            catch {
+                // ignore
+            }
+            this.pendingIdleCallback = null;
         }
-        this.batchTimer = null;
     }
     getDesiredBatchFlushDueAt(nowTs) {
         const start = this.initTs || nowTs;
@@ -919,7 +936,14 @@ class ClsLoggerCore {
         // 先清空，再尝试发送
         writeStringStorage(this.failedCacheKey, JSON.stringify([]));
         this.memoryQueue.unshift(...logs);
-        void this.flushBatch();
+        // 触发定时器而非直接 flush，以尊重 startupDelayMs 配置
+        if (!this.batchTimer) {
+            const now = Date.now();
+            const desiredDueAt = this.getDesiredBatchFlushDueAt(now);
+            const desiredDelay = Math.max(0, desiredDueAt - now);
+            this.batchTimerDueAt = desiredDueAt;
+            this.scheduleFlush(desiredDelay);
+        }
     }
     /**
      * 统计/计数类日志：按字段展开上报（若 data 为空默认 1）

package/dist/types.d.ts CHANGED Viewed

@@ -29,13 +29,20 @@ export interface BatchOptions {
     /**
      * 启动阶段合并窗口（ms）
      * - 目的：减少初始化/首屏阶段（perf/resource 等日志密集期）被 intervalMs 拆成多次上报
-     * - 行为：在该窗口内尽量延迟 flush 到窗口结束（但仍受 maxSize 约束，达到阈值会立即发送）
+     * - 行为：在该窗口内尽量延迟 flush 到窗口结束
      * - 默认：0（不开启）
      */
     startupDelayMs?: number;
+    /**
+     * 启动阶段的 maxSize（启动窗口内生效）
+     * - 目的：防止启动期间日志密集导致 maxSize 被频繁触发而打断 startupDelayMs
+     * - 行为：在 startupDelayMs 窗口内使用此值作为队列阈值
+     * - 默认：maxSize * 10（若未设置则为 200）
+     */
+    startupMaxSize?: number;
     /**
      * 是否使用浏览器空闲时间上报
-     * - 开启后会使用 requestIdleCallback 代替 setTimeout 调度批量发送
+     * - 开启后会先等待 intervalMs/startupDelayMs，然后在浏览器空闲时执行发送
      * - 配合 idleTimeout 使用，保证即使浏览器繁忙也能在超时后发送
      * - 默认：false
      */
@@ -43,7 +50,7 @@ export interface BatchOptions {
     /**
      * 空闲回调超时时间（ms）
      * - 当 useIdleCallback 为 true 时生效
-     * - 即使浏览器繁忙，也会在此时间后强制执行
+     * - 在等待空闲期间，即使浏览器繁忙，也会在此时间后强制执行
      * - 默认：3000
      */
     idleTimeout?: number;

package/dist/types.d.ts.map CHANGED Viewed

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

package/dist/web.esm.js CHANGED Viewed

@@ -179,8 +179,10 @@ class ClsLoggerCore {
         this.batchTimerDueAt = null;
         this.initTs = 0;
         this.startupDelayMs = 0;
+        this.startupMaxSize = 0; // 启动窗口内的 maxSize，0 表示使用默认计算值
         this.useIdleCallback = false;
         this.idleTimeout = 3000;
+        this.pendingIdleCallback = null; // requestIdleCallback 的 id
         this.visibilityCleanup = null;
         // 参考文档：失败缓存 + 重试
         this.failedCacheKey = 'cls_failed_logs';
@@ -253,6 +255,8 @@ class ClsLoggerCore {
         this.startupDelayMs = options.batch?.startupDelayMs ?? this.startupDelayMs;
         this.useIdleCallback = options.batch?.useIdleCallback ?? this.useIdleCallback;
         this.idleTimeout = options.batch?.idleTimeout ?? this.idleTimeout;
+        // startupMaxSize：启动窗口内的队列阈值，默认为 maxSize * 10（至少 200）
+        this.startupMaxSize = options.batch?.startupMaxSize ?? Math.max(this.batchMaxSize * 10, 200);
         this.failedCacheKey = options.failedCacheKey ?? this.failedCacheKey;
         this.failedCacheMax = options.failedCacheMax ?? this.failedCacheMax;
         // 预热（避免首条日志触发 import/初始化开销）
@@ -628,11 +632,15 @@ class ClsLoggerCore {
             return;
         }
         this.memoryQueue.push(log);
-        if (this.memoryQueue.length >= this.batchMaxSize) {
+        const now = Date.now();
+        // 判断是否在启动合并窗口内
+        const inStartupWindow = this.startupDelayMs > 0 && now - this.initTs < this.startupDelayMs;
+        // 启动窗口内使用 startupMaxSize，正常情况使用 batchMaxSize
+        const effectiveMaxSize = inStartupWindow ? this.startupMaxSize : this.batchMaxSize;
+        if (this.memoryQueue.length >= effectiveMaxSize) {
             void this.flushBatch();
             return;
         }
-        const now = Date.now();
         const desiredDueAt = this.getDesiredBatchFlushDueAt(now);
         const desiredDelay = Math.max(0, desiredDueAt - now);
         if (!this.batchTimer) {
@@ -649,17 +657,19 @@ class ClsLoggerCore {
     }
     /**
      * 调度批量发送
-     * - 支持 requestIdleCallback（浏览器空闲时执行）
-     * - 降级为 setTimeout
+     * - 先使用 setTimeout 保证最小延迟（desiredDelay）
+     * - 若开启 useIdleCallback，在延迟结束后等待浏览器空闲再执行
      */
     scheduleFlush(desiredDelay) {
         if (this.useIdleCallback && typeof requestIdleCallback !== 'undefined') {
-            // 使用 requestIdleCallback，设置 timeout 保证最终执行
-            const idleId = requestIdleCallback(() => {
-                void this.flushBatch();
-            }, { timeout: Math.max(desiredDelay, this.idleTimeout) });
-            // 存储 idleId 以便清理（类型兼容处理）
-            this.batchTimer = idleId;
+            // 先 setTimeout 保证最小延迟，再 requestIdleCallback 在空闲时执行
+            this.batchTimer = setTimeout(() => {
+                const idleId = requestIdleCallback(() => {
+                    this.pendingIdleCallback = null;
+                    void this.flushBatch();
+                }, { timeout: this.idleTimeout });
+                this.pendingIdleCallback = idleId;
+            }, desiredDelay);
         }
         else {
             this.batchTimer = setTimeout(() => {
@@ -669,22 +679,29 @@ class ClsLoggerCore {
     }
     /**
      * 取消已调度的批量发送
+     * - 同时清理 setTimeout 和可能的 requestIdleCallback
      */
     cancelScheduledFlush() {
-        if (!this.batchTimer)
-            return;
-        try {
-            if (this.useIdleCallback && typeof cancelIdleCallback !== 'undefined') {
-                cancelIdleCallback(this.batchTimer);
-            }
-            else {
+        // 清理 setTimeout
+        if (this.batchTimer) {
+            try {
                 clearTimeout(this.batchTimer);
             }
+            catch {
+                // ignore
+            }
+            this.batchTimer = null;
         }
-        catch {
-            // ignore
+        // 清理可能的 pendingIdleCallback
+        if (this.pendingIdleCallback !== null && typeof cancelIdleCallback !== 'undefined') {
+            try {
+                cancelIdleCallback(this.pendingIdleCallback);
+            }
+            catch {
+                // ignore
+            }
+            this.pendingIdleCallback = null;
         }
-        this.batchTimer = null;
     }
     getDesiredBatchFlushDueAt(nowTs) {
         const start = this.initTs || nowTs;
@@ -897,7 +914,14 @@ class ClsLoggerCore {
         // 先清空，再尝试发送
         writeStringStorage(this.failedCacheKey, JSON.stringify([]));
         this.memoryQueue.unshift(...logs);
-        void this.flushBatch();
+        // 触发定时器而非直接 flush，以尊重 startupDelayMs 配置
+        if (!this.batchTimer) {
+            const now = Date.now();
+            const desiredDueAt = this.getDesiredBatchFlushDueAt(now);
+            const desiredDelay = Math.max(0, desiredDueAt - now);
+            this.batchTimerDueAt = desiredDueAt;
+            this.scheduleFlush(desiredDelay);
+        }
     }
     /**
      * 统计/计数类日志：按字段展开上报（若 data 为空默认 1）

package/dist/web.js CHANGED Viewed

@@ -202,8 +202,10 @@ class ClsLoggerCore {
         this.batchTimerDueAt = null;
         this.initTs = 0;
         this.startupDelayMs = 0;
+        this.startupMaxSize = 0; // 启动窗口内的 maxSize，0 表示使用默认计算值
         this.useIdleCallback = false;
         this.idleTimeout = 3000;
+        this.pendingIdleCallback = null; // requestIdleCallback 的 id
         this.visibilityCleanup = null;
         // 参考文档：失败缓存 + 重试
         this.failedCacheKey = 'cls_failed_logs';
@@ -276,6 +278,8 @@ class ClsLoggerCore {
         this.startupDelayMs = options.batch?.startupDelayMs ?? this.startupDelayMs;
         this.useIdleCallback = options.batch?.useIdleCallback ?? this.useIdleCallback;
         this.idleTimeout = options.batch?.idleTimeout ?? this.idleTimeout;
+        // startupMaxSize：启动窗口内的队列阈值，默认为 maxSize * 10（至少 200）
+        this.startupMaxSize = options.batch?.startupMaxSize ?? Math.max(this.batchMaxSize * 10, 200);
         this.failedCacheKey = options.failedCacheKey ?? this.failedCacheKey;
         this.failedCacheMax = options.failedCacheMax ?? this.failedCacheMax;
         // 预热（避免首条日志触发 import/初始化开销）
@@ -651,11 +655,15 @@ class ClsLoggerCore {
             return;
         }
         this.memoryQueue.push(log);
-        if (this.memoryQueue.length >= this.batchMaxSize) {
+        const now = Date.now();
+        // 判断是否在启动合并窗口内
+        const inStartupWindow = this.startupDelayMs > 0 && now - this.initTs < this.startupDelayMs;
+        // 启动窗口内使用 startupMaxSize，正常情况使用 batchMaxSize
+        const effectiveMaxSize = inStartupWindow ? this.startupMaxSize : this.batchMaxSize;
+        if (this.memoryQueue.length >= effectiveMaxSize) {
             void this.flushBatch();
             return;
         }
-        const now = Date.now();
         const desiredDueAt = this.getDesiredBatchFlushDueAt(now);
         const desiredDelay = Math.max(0, desiredDueAt - now);
         if (!this.batchTimer) {
@@ -672,17 +680,19 @@ class ClsLoggerCore {
     }
     /**
      * 调度批量发送
-     * - 支持 requestIdleCallback（浏览器空闲时执行）
-     * - 降级为 setTimeout
+     * - 先使用 setTimeout 保证最小延迟（desiredDelay）
+     * - 若开启 useIdleCallback，在延迟结束后等待浏览器空闲再执行
      */
     scheduleFlush(desiredDelay) {
         if (this.useIdleCallback && typeof requestIdleCallback !== 'undefined') {
-            // 使用 requestIdleCallback，设置 timeout 保证最终执行
-            const idleId = requestIdleCallback(() => {
-                void this.flushBatch();
-            }, { timeout: Math.max(desiredDelay, this.idleTimeout) });
-            // 存储 idleId 以便清理（类型兼容处理）
-            this.batchTimer = idleId;
+            // 先 setTimeout 保证最小延迟，再 requestIdleCallback 在空闲时执行
+            this.batchTimer = setTimeout(() => {
+                const idleId = requestIdleCallback(() => {
+                    this.pendingIdleCallback = null;
+                    void this.flushBatch();
+                }, { timeout: this.idleTimeout });
+                this.pendingIdleCallback = idleId;
+            }, desiredDelay);
         }
         else {
             this.batchTimer = setTimeout(() => {
@@ -692,22 +702,29 @@ class ClsLoggerCore {
     }
     /**
      * 取消已调度的批量发送
+     * - 同时清理 setTimeout 和可能的 requestIdleCallback
      */
     cancelScheduledFlush() {
-        if (!this.batchTimer)
-            return;
-        try {
-            if (this.useIdleCallback && typeof cancelIdleCallback !== 'undefined') {
-                cancelIdleCallback(this.batchTimer);
-            }
-            else {
+        // 清理 setTimeout
+        if (this.batchTimer) {
+            try {
                 clearTimeout(this.batchTimer);
             }
+            catch {
+                // ignore
+            }
+            this.batchTimer = null;
         }
-        catch {
-            // ignore
+        // 清理可能的 pendingIdleCallback
+        if (this.pendingIdleCallback !== null && typeof cancelIdleCallback !== 'undefined') {
+            try {
+                cancelIdleCallback(this.pendingIdleCallback);
+            }
+            catch {
+                // ignore
+            }
+            this.pendingIdleCallback = null;
         }
-        this.batchTimer = null;
     }
     getDesiredBatchFlushDueAt(nowTs) {
         const start = this.initTs || nowTs;
@@ -920,7 +937,14 @@ class ClsLoggerCore {
         // 先清空，再尝试发送
         writeStringStorage(this.failedCacheKey, JSON.stringify([]));
         this.memoryQueue.unshift(...logs);
-        void this.flushBatch();
+        // 触发定时器而非直接 flush，以尊重 startupDelayMs 配置
+        if (!this.batchTimer) {
+            const now = Date.now();
+            const desiredDueAt = this.getDesiredBatchFlushDueAt(now);
+            const desiredDelay = Math.max(0, desiredDueAt - now);
+            this.batchTimerDueAt = desiredDueAt;
+            this.scheduleFlush(desiredDelay);
+        }
     }
     /**
      * 统计/计数类日志：按字段展开上报（若 data 为空默认 1）

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@be-link/cls-logger",
-  "version": "1.0.1-beta.21",
+  "version": "1.0.1-beta.23",
   "description": "@be-link cls-logger - 腾讯云 CLS 日志上报封装",
   "homepage": "https://github.com/snowmountain-top/be-link",
   "author": "zhuiyi",