@be-link/cls-logger 1.0.1-beta.0 → 1.0.1-beta.10

package/dist/index.umd.js

@@ -1,8 +1,8 @@
 (function (global, factory) {
-    typeof exports === 'object' && typeof module !== 'undefined' ? factory(exports, require('tencentcloud-cls-sdk-js-web')) :
-    typeof define === 'function' && define.amd ? define(['exports', 'tencentcloud-cls-sdk-js-web'], factory) :
-    (global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global.BeLinkClsLogger = {}, global.tencentcloudClsSdkJsWeb));
-})(this, (function (exports, tencentcloudClsSdkJsWeb) { 'use strict';
+    typeof exports === 'object' && typeof module !== 'undefined' ? factory(exports) :
+    typeof define === 'function' && define.amd ? define(['exports'], factory) :
+    (global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global.BeLinkClsLogger = {}));
+})(this, (function (exports) { 'use strict';
 
     function isPlainObject(value) {
         return Object.prototype.toString.call(value) === '[object Object]';
@@ -138,6 +138,10 @@
     }
 
     const DEFAULT_IGNORE$1 = ['cls.tencentcs.com', /\/cls\//i];
+    function isClsSendingNow() {
+        const g = globalThis;
+        return (g.__beLinkClsLoggerSendingCount__ ?? 0) > 0;
+    }
     function shouldIgnoreUrl$1(url, ignoreUrls) {
         for (const rule of ignoreUrls) {
             if (typeof rule === 'string') {
@@ -215,6 +219,9 @@
         w.__beLinkClsLoggerFetchInstalled__ = true;
         w.__beLinkClsLoggerRawFetch__ = w.fetch;
         w.fetch = async (input, init) => {
+            // 避免 CLS SDK 上报请求被 requestMonitor 捕获后递归上报（尤其在跨域失败时会“上报失败→再上报”）
+            if (isClsSendingNow())
+                return w.__beLinkClsLoggerRawFetch__(input, init);
             let url = '';
             let method = '';
             let body = undefined;
@@ -304,6 +311,9 @@
             return rawOpen.apply(this, args);
         };
         XHR.prototype.send = function (...args) {
+            // CLS SDK 发起上报时：跳过监控，避免递归上报
+            if (isClsSendingNow())
+                return rawSend.apply(this, args);
             const startTs = Date.now();
             try {
                 const method = String(this.__beLinkClsLoggerMethod__ ?? 'GET');
@@ -530,6 +540,8 @@
     }
 
     const DEFAULT_MAX_TEXT = 4000;
+    const DEFAULT_DEDUPE_WINDOW_MS = 3000;
+    const DEFAULT_DEDUPE_MAX_KEYS = 200;
     function truncate$2(s, maxLen) {
         if (!s)
             return s;
@@ -555,7 +567,17 @@
     function normalizeErrorLike(err, maxTextLength) {
         if (err && typeof err === 'object') {
             const anyErr = err;
-            const message = truncate$2(String(anyErr.message ?? anyErr.toString?.() ?? ''), maxTextLength);
+            let rawMsg = anyErr.message;
+            if (!rawMsg) {
+                const str = anyErr.toString?.();
+                if (!str || str === '[object Object]') {
+                    rawMsg = stringifyLogValue(anyErr);
+                }
+                else {
+                    rawMsg = str;
+                }
+            }
+            const message = truncate$2(String(rawMsg ?? ''), maxTextLength);
             const name = truncate$2(String(anyErr.name ?? ''), 200);
             const stack = truncate$2(String(anyErr.stack ?? ''), maxTextLength);
             return { message, name, stack };
@@ -563,6 +585,54 @@
         const message = truncate$2(stringifyLogValue(err), maxTextLength);
         return { message, name: '', stack: '' };
     }
+    function createDedupeGuard(options) {
+        const cache = new Map(); // key -> lastReportAt
+        const maxKeys = Math.max(0, options.dedupeMaxKeys);
+        const windowMs = Math.max(0, options.dedupeWindowMs);
+        function touch(key, now) {
+            // refresh insertion order
+            if (cache.has(key))
+                cache.delete(key);
+            cache.set(key, now);
+            if (maxKeys > 0) {
+                while (cache.size > maxKeys) {
+                    const first = cache.keys().next().value;
+                    if (!first)
+                        break;
+                    cache.delete(first);
+                }
+            }
+        }
+        return (key) => {
+            if (!key)
+                return true;
+            if (windowMs <= 0 || maxKeys === 0)
+                return true;
+            const now = Date.now();
+            const last = cache.get(key);
+            if (typeof last === 'number' && now - last < windowMs)
+                return false;
+            touch(key, now);
+            return true;
+        };
+    }
+    function buildErrorKey(type, payload) {
+        // 使用最核心、最稳定的字段构造签名，避免把瞬态字段（如 time）带入导致失效
+        const parts = [
+            type,
+            String(payload.source ?? ''),
+            String(payload.pagePath ?? ''),
+            String(payload.message ?? ''),
+            String(payload.errorName ?? ''),
+            String(payload.stack ?? ''),
+            String(payload.filename ?? ''),
+            String(payload.lineno ?? ''),
+            String(payload.colno ?? ''),
+            String(payload.tagName ?? ''),
+            String(payload.resourceUrl ?? ''),
+        ];
+        return parts.join('|');
+    }
     function installBrowserErrorMonitor(report, options) {
         if (typeof window === 'undefined')
             return;
@@ -570,6 +640,7 @@
         if (w.__beLinkClsLoggerErrorInstalled__)
             return;
         w.__beLinkClsLoggerErrorInstalled__ = true;
+        const shouldReport = createDedupeGuard(options);
         window.addEventListener('error', (event) => {
             try {
                 if (!sampleHit$1(options.sampleRate))
@@ -592,6 +663,8 @@
                         if (e.stack)
                             payload.stack = e.stack;
                     }
+                    if (!shouldReport(buildErrorKey(options.reportType, payload)))
+                        return;
                     report(options.reportType, payload);
                     return;
                 }
@@ -603,6 +676,8 @@
                     payload.source = 'resource.error';
                     payload.tagName = tagName;
                     payload.resourceUrl = truncate$2(url, 2000);
+                    if (!shouldReport(buildErrorKey(options.reportType, payload)))
+                        return;
                     report(options.reportType, payload);
                 }
             }
@@ -623,6 +698,8 @@
                     errorName: e.name,
                     stack: e.stack,
                 };
+                if (!shouldReport(buildErrorKey(options.reportType, payload)))
+                    return;
                 report(options.reportType, payload);
             }
             catch {
@@ -635,6 +712,7 @@
         if (g.__beLinkClsLoggerMpErrorInstalled__)
             return;
         g.__beLinkClsLoggerMpErrorInstalled__ = true;
+        const shouldReport = createDedupeGuard(options);
         const wxAny = globalThis.wx;
         // wx.* 事件（兼容在 App 已经创建后的场景）
         try {
@@ -643,10 +721,16 @@
                     try {
                         if (!sampleHit$1(options.sampleRate))
                             return;
-                        report(options.reportType, {
+                        const e = normalizeErrorLike(msg, options.maxTextLength);
+                        const payload = {
                             source: 'wx.onError',
-                            message: truncate$2(String(msg ?? ''), options.maxTextLength),
-                        });
+                            message: e.message,
+                            errorName: e.name,
+                            stack: e.stack,
+                        };
+                        if (!shouldReport(buildErrorKey(options.reportType, payload)))
+                            return;
+                        report(options.reportType, payload);
                     }
                     catch {
                         // ignore
@@ -664,12 +748,15 @@
                         if (!sampleHit$1(options.sampleRate))
                             return;
                         const e = normalizeErrorLike(res?.reason, options.maxTextLength);
-                        report(options.reportType, {
+                        const payload = {
                             source: 'wx.onUnhandledRejection',
                             message: e.message,
                             errorName: e.name,
                             stack: e.stack,
-                        });
+                        };
+                        if (!shouldReport(buildErrorKey(options.reportType, payload)))
+                            return;
+                        report(options.reportType, payload);
                     }
                     catch {
                         // ignore
@@ -691,10 +778,15 @@
                     next.onError = function (...args) {
                         try {
                             if (sampleHit$1(options.sampleRate)) {
-                                report(options.reportType, {
+                                const e = normalizeErrorLike(args?.[0], options.maxTextLength);
+                                const payload = {
                                     source: 'App.onError',
-                                    message: truncate$2(String(args?.[0] ?? ''), options.maxTextLength),
-                                });
+                                    message: e.message,
+                                    errorName: e.name,
+                                    stack: e.stack,
+                                };
+                                if (shouldReport(buildErrorKey(options.reportType, payload)))
+                                    report(options.reportType, payload);
                             }
                         }
                         catch {
@@ -710,12 +802,14 @@
                             if (sampleHit$1(options.sampleRate)) {
                                 const reason = args?.[0]?.reason ?? args?.[0];
                                 const e = normalizeErrorLike(reason, options.maxTextLength);
-                                report(options.reportType, {
+                                const payload = {
                                     source: 'App.onUnhandledRejection',
                                     message: e.message,
                                     errorName: e.name,
                                     stack: e.stack,
-                                });
+                                };
+                                if (shouldReport(buildErrorKey(options.reportType, payload)))
+                                    report(options.reportType, payload);
                             }
                         }
                         catch {
@@ -744,6 +838,8 @@
             sampleRate: raw.sampleRate ?? 1,
             captureResourceError: raw.captureResourceError ?? true,
             maxTextLength: raw.maxTextLength ?? DEFAULT_MAX_TEXT,
+            dedupeWindowMs: raw.dedupeWindowMs ?? DEFAULT_DEDUPE_WINDOW_MS,
+            dedupeMaxKeys: raw.dedupeMaxKeys ?? DEFAULT_DEDUPE_MAX_KEYS,
         };
         if (isMiniProgramEnv()) {
             installMiniProgramErrorMonitor(report, options);
@@ -994,140 +1090,58 @@
             }
         }
     }
-    function wrapMiniProgramRouteApi(report, reportType, apiName, options) {
-        const wxAny = globalThis.wx;
-        if (!wxAny || typeof wxAny[apiName] !== 'function')
-            return;
-        const flagKey = `__beLinkClsLoggerMpRouteWrapped__${apiName}`;
-        if (wxAny[flagKey])
-            return;
-        wxAny[flagKey] = true;
-        const raw = wxAny[apiName].bind(wxAny);
-        wxAny[apiName] = (opts) => {
-            const start = Date.now();
-            const url = opts?.url ? String(opts.url) : '';
-            const wrapCb = (cb, success) => {
-                return (...args) => {
-                    try {
-                        if (sampleHit(options.sampleRate)) {
-                            report(reportType, {
-                                metric: 'route',
-                                api: apiName,
-                                url,
-                                duration: Date.now() - start,
-                                success: success ? 1 : 0,
-                                error: success ? '' : truncate$1(stringifyLogValue(args?.[0]), options.maxTextLength),
-                                unit: 'ms',
-                            });
-                        }
-                    }
-                    catch {
-                        // ignore
-                    }
-                    if (typeof cb === 'function')
-                        return cb(...args);
-                    return undefined;
-                };
-            };
-            const next = { ...(opts ?? {}) };
-            next.success = wrapCb(next.success, true);
-            next.fail = wrapCb(next.fail, false);
-            return raw(next);
-        };
-    }
-    function installMiniProgramPageRenderMonitor(report, reportType, options) {
-        const g = globalThis;
-        if (typeof g.Page !== 'function')
-            return;
-        if (g.__beLinkClsLoggerPageWrapped__)
-            return;
-        g.__beLinkClsLoggerPageWrapped__ = true;
-        const rawPage = g.Page;
-        g.Page = (pageOptions) => {
-            const next = { ...(pageOptions ?? {}) };
-            const rawOnLoad = next.onLoad;
-            const rawOnReady = next.onReady;
-            next.onLoad = function (...args) {
-                try {
-                    this.__beLinkClsLoggerPageLoadTs__ = Date.now();
-                }
-                catch {
-                    // ignore
-                }
-                if (typeof rawOnLoad === 'function')
-                    return rawOnLoad.apply(this, args);
-                return undefined;
-            };
-            next.onReady = function (...args) {
-                try {
-                    const start = this.__beLinkClsLoggerPageLoadTs__;
-                    if (typeof start === 'number' && sampleHit(options.sampleRate)) {
-                        report(reportType, {
-                            metric: 'page-render',
-                            route: this?.route ? String(this.route) : '',
-                            duration: Date.now() - start,
-                            unit: 'ms',
-                        });
-                    }
-                }
-                catch {
-                    // ignore
-                }
-                if (typeof rawOnReady === 'function')
-                    return rawOnReady.apply(this, args);
-                return undefined;
-            };
-            return rawPage(next);
-        };
-    }
     function installMiniProgramPerformanceMonitor(report, options) {
         const g = globalThis;
+        const ctx = g.wx || g.Taro;
+        if (!ctx || typeof ctx.getPerformance !== 'function')
+            return;
         if (g.__beLinkClsLoggerMpPerfInstalled__)
             return;
         g.__beLinkClsLoggerMpPerfInstalled__ = true;
-        // 路由切换耗时（用 API 回调近似）
-        for (const apiName of ['navigateTo', 'redirectTo', 'switchTab', 'reLaunch']) {
-            try {
-                wrapMiniProgramRouteApi(report, options.reportType, apiName, options);
-            }
-            catch {
-                // ignore
-            }
-        }
-        // 页面渲染耗时（onLoad -> onReady）
-        try {
-            installMiniProgramPageRenderMonitor(report, options.reportType, options);
-        }
-        catch {
-            // ignore
-        }
-        // wx.getPerformance()（若可用，尝试读取已有 entries）
         try {
-            const wxAny = globalThis.wx;
-            if (wxAny && typeof wxAny.getPerformance === 'function') {
-                const perf = wxAny.getPerformance();
-                if (perf && isPlainObject(perf)) {
-                    // 不同基础库实现差异较大：尽量容错
-                    setTimeout(() => {
-                        try {
-                            if (!sampleHit(options.sampleRate))
-                                return;
-                            const entries = typeof perf.getEntries === 'function'
-                                ? perf.getEntries()
-                                : typeof perf.getEntriesByType === 'function'
-                                    ? perf.getEntriesByType('navigation')
-                                    : [];
+            const perf = ctx.getPerformance();
+            if (!perf || typeof perf.createObserver !== 'function')
+                return;
+            const observer = perf.createObserver((entryList) => {
+                try {
+                    const entries = entryList.getEntries();
+                    for (const entry of entries) {
+                        if (!sampleHit(options.sampleRate))
+                            continue;
+                        // Page Render: firstRender
+                        if (entry.entryType === 'render' && entry.name === 'firstRender') {
                             report(options.reportType, {
-                                metric: 'mp-performance',
-                                entries: truncate$1(stringifyLogValue(entries), options.maxTextLength),
+                                metric: 'page-render',
+                                duration: entry.duration,
+                                pagePath: entry.path || '',
+                                unit: 'ms',
                             });
                         }
-                        catch {
-                            // ignore
+                        // Route Switch: route
+                        else if (entry.entryType === 'navigation' && entry.name === 'route') {
+                            report(options.reportType, {
+                                metric: 'route',
+                                duration: entry.duration,
+                                pagePath: entry.path || '',
+                                unit: 'ms',
+                            });
                         }
-                    }, 0);
+                        // App Launch: appLaunch (Cold)
+                        else if (entry.entryType === 'navigation' && entry.name === 'appLaunch') {
+                            report(options.reportType, {
+                                metric: 'app-launch',
+                                duration: entry.duration,
+                                launchType: 'cold',
+                                unit: 'ms',
+                            });
+                        }
+                    }
                 }
-            }
+                catch {
+                    // ignore
+                }
+            });
+            observer.observe({ entryTypes: ['navigation', 'render'] });
         }
         catch {
             // ignore
@@ -1451,7 +1465,7 @@
                 const tag = (el.tagName || '').toLowerCase();
                 const trackId = getAttr(el, clickTrackIdAttr);
                 // 过滤无效点击：白名单 tag + 没有 trackId
-                if (clickWhiteList.includes(tag) && !trackId)
+                if (clickWhiteList.includes(tag) || !trackId)
                     return;
                 void uvStatePromise.then(({ uvId, meta }) => {
                     if (destroyed)
@@ -1492,8 +1506,12 @@
                     g.Page = function patchedPage(conf) {
                         const originalOnShow = conf?.onShow;
                         conf.onShow = function (...args) {
-                            if (pvEnabled)
-                                reportPv(getPagePath());
+                            if (pvEnabled) {
+                                const pagePath = getPagePath();
+                                if (pagePath?.length > 0) {
+                                    reportPv(pagePath);
+                                }
+                            }
                             return typeof originalOnShow === 'function' ? originalOnShow.apply(this, args) : undefined;
                         };
                         // 点击：wrap 页面 methods（bindtap 等会调用到这里的 handler）
@@ -1820,9 +1838,29 @@
         };
     }
 
-    class ClsLogger {
+    function enterClsSendingGuard() {
+        const g = globalThis;
+        const next = (g.__beLinkClsLoggerSendingCount__ ?? 0) + 1;
+        g.__beLinkClsLoggerSendingCount__ = next;
+        return () => {
+            const cur = g.__beLinkClsLoggerSendingCount__ ?? 0;
+            g.__beLinkClsLoggerSendingCount__ = cur > 0 ? cur - 1 : 0;
+        };
+    }
+    /**
+     * CLS Logger 核心基类
+     * - 负责所有上报、队列、监控逻辑
+     * - 不包含具体的 SDK 加载实现（由子类负责）
+     * - 这样可以把 web/mini 的 SDK 依赖彻底解耦到子入口
+     */
+    class ClsLoggerCore {
         constructor() {
+            this.sdk = null;
+            this.sdkPromise = null;
+            this.sdkOverride = null;
+            this.sdkLoaderOverride = null;
             this.client = null;
+            this.clientPromise = null;
             this.topicId = null;
             this.endpoint = 'ap-shanghai.cls.tencentcs.com';
             this.retryTimes = 10;
@@ -1841,6 +1879,9 @@
             this.batchMaxSize = 20;
             this.batchIntervalMs = 500;
             this.batchTimer = null;
+            this.batchTimerDueAt = null;
+            this.initTs = 0;
+            this.startupDelayMs = 0;
             // 参考文档：失败缓存 + 重试
             this.failedCacheKey = 'cls_failed_logs';
             this.failedCacheMax = 200;
@@ -1850,7 +1891,22 @@
             this.behaviorMonitorStarted = false;
             this.behaviorMonitorCleanup = null;
         }
+        /**
+         * 子类可按需重写（默认检测 wx）
+         */
+        detectEnvType() {
+            const g = globalThis;
+            // 微信、支付宝、字节跳动、UniApp 等小程序环境通常都有特定全局变量
+            if ((g.wx && typeof g.wx.getSystemInfoSync === 'function') ||
+                (g.my && typeof g.my.getSystemInfoSync === 'function') ||
+                (g.tt && typeof g.tt.getSystemInfoSync === 'function') ||
+                (g.uni && typeof g.uni.getSystemInfoSync === 'function')) {
+                return 'miniprogram';
+            }
+            return 'browser';
+        }
         init(options) {
+            this.initTs = Date.now();
             const topicId = options?.tencentCloud?.topicID ?? options?.topic_id ?? options?.topicID ?? this.topicId ?? null;
             const endpoint = options?.tencentCloud?.endpoint ?? options?.endpoint ?? this.endpoint;
             const retryTimes = options?.tencentCloud?.retry_times ?? options?.retry_times ?? this.retryTimes;
@@ -1860,25 +1916,46 @@
                 console.warn('ClsLogger.init 没有传 topicID/topic_id');
                 return;
             }
+            const nextEnvType = options.envType ?? this.detectEnvType();
+            // envType/endpoint/retryTimes 变化时：重置 client（以及可能的 sdk）
+            const envChanged = nextEnvType !== this.envType;
+            const endpointChanged = endpoint !== this.endpoint;
+            const retryChanged = retryTimes !== this.retryTimes;
+            if (envChanged || endpointChanged || retryChanged) {
+                this.client = null;
+                this.clientPromise = null;
+            }
+            if (envChanged) {
+                this.sdk = null;
+                this.sdkPromise = null;
+            }
             this.topicId = topicId;
             this.endpoint = endpoint;
             this.retryTimes = retryTimes;
             this.source = source;
+            this.userId = options.userId ?? this.userId;
+            this.userName = options.userName ?? this.userName;
             this.projectId = options.projectId ?? this.projectId;
             this.projectName = options.projectName ?? this.projectName;
             this.appId = options.appId ?? this.appId;
             this.appVersion = options.appVersion ?? this.appVersion;
-            this.envType = options.envType ?? this.detectEnvType();
+            this.envType = nextEnvType;
+            // 可选：外部注入 SDK（优先级：sdkLoader > sdk）
+            this.sdkLoaderOverride = options.sdkLoader ?? this.sdkLoaderOverride;
+            this.sdkOverride = options.sdk ?? this.sdkOverride;
             this.userGenerateBaseFields = options.generateBaseFields ?? this.userGenerateBaseFields;
             this.autoGenerateBaseFields = createAutoDeviceInfoBaseFields(this.envType, options.deviceInfo);
             this.storageKey = options.storageKey ?? this.storageKey;
             this.batchSize = options.batchSize ?? this.batchSize;
             this.batchMaxSize = options.batch?.maxSize ?? this.batchMaxSize;
             this.batchIntervalMs = options.batch?.intervalMs ?? this.batchIntervalMs;
+            this.startupDelayMs = options.batch?.startupDelayMs ?? this.startupDelayMs;
             this.failedCacheKey = options.failedCacheKey ?? this.failedCacheKey;
             this.failedCacheMax = options.failedCacheMax ?? this.failedCacheMax;
-            // 预热 client
-            this.getInstance();
+            // 预热（避免首条日志触发 import/初始化开销）
+            void this.getInstance().catch(() => {
+                // ignore
+            });
             // 启动时尝试发送失败缓存
             this.flushFailed();
             // 初始化后立即启动请求监听
@@ -1903,7 +1980,7 @@
             try {
                 const userRaw = this.userGenerateBaseFields ? this.userGenerateBaseFields() : undefined;
                 if (userRaw && isPlainObject(userRaw))
-                    user = normalizeFlatFields(userRaw, 'generateBaseFields');
+                    user = normalizeFlatFields({ ...userRaw }, 'generateBaseFields');
             }
             catch {
                 user = undefined;
@@ -1982,20 +2059,29 @@
             this.behaviorMonitorCleanup = null;
             this.behaviorMonitorStarted = false;
         }
-        getInstance() {
+        /**
+         * 获取 CLS client（按环境懒加载 SDK）
+         */
+        async getInstance() {
             if (this.client)
                 return this.client;
-            this.client = new tencentcloudClsSdkJsWeb.AsyncClient({
-                endpoint: this.endpoint,
-                retry_times: this.retryTimes,
+            if (this.clientPromise)
+                return this.clientPromise;
+            this.clientPromise = this.loadSdk()
+                .then(({ AsyncClient }) => {
+                const client = new AsyncClient({
+                    endpoint: this.endpoint,
+                    retry_times: this.retryTimes,
+                });
+                this.client = client;
+                return client;
+            })
+                .catch((err) => {
+                // 失败后允许下次重试
+                this.clientPromise = null;
+                throw err;
             });
-            return this.client;
-        }
-        detectEnvType() {
-            const wxAny = globalThis.wx;
-            if (wxAny && typeof wxAny.getSystemInfoSync === 'function')
-                return 'miniprogram';
-            return 'browser';
+            return this.clientPromise;
         }
         /**
          * 直接上报：埋点入参必须是一维（扁平）Object
@@ -2021,16 +2107,33 @@
                 appVersion: this.appVersion || undefined,
                 ...normalizedFields,
             });
-            const client = this.getInstance();
-            const logGroup = new tencentcloudClsSdkJsWeb.LogGroup('127.0.0.1');
+            // 同步 API：内部异步发送，避免把网络异常冒泡到业务（尤其小程序）
+            void this.putAsync(finalFields).catch(() => {
+                // ignore
+            });
+        }
+        async putAsync(finalFields) {
+            if (!this.topicId)
+                return;
+            const sdk = await this.loadSdk();
+            const client = await this.getInstance();
+            const logGroup = new sdk.LogGroup('127.0.0.1');
             logGroup.setSource(this.source);
-            const log = new tencentcloudClsSdkJsWeb.Log(Date.now());
+            const log = new sdk.Log(Date.now());
             for (const key of Object.keys(finalFields)) {
                 log.addContent(key, stringifyLogValue(finalFields[key]));
             }
             logGroup.addLog(log);
-            const request = new tencentcloudClsSdkJsWeb.PutLogsRequest(this.topicId, logGroup);
-            client.PutLogs(request);
+            const request = new sdk.PutLogsRequest(this.topicId, logGroup);
+            const exit = enterClsSendingGuard();
+            let p;
+            try {
+                p = client.PutLogs(request);
+            }
+            finally {
+                exit();
+            }
+            await p;
         }
         /**
          * 直接上报：把 data 序列化后放入指定 key（默认 “日志内容”）
@@ -2089,11 +2192,19 @@
                 console.warn('ClsLogger.putBatch：未初始化 topic_id');
                 return;
             }
-            const client = this.getInstance();
-            const logGroup = new tencentcloudClsSdkJsWeb.LogGroup('127.0.0.1');
+            void this.putBatchAsync(queue).catch(() => {
+                // ignore
+            });
+        }
+        async putBatchAsync(queue) {
+            if (!this.topicId)
+                return;
+            const sdk = await this.loadSdk();
+            const client = await this.getInstance();
+            const logGroup = new sdk.LogGroup('127.0.0.1');
             logGroup.setSource(this.source);
             for (const item of queue) {
-                const log = new tencentcloudClsSdkJsWeb.Log(item.time);
+                const log = new sdk.Log(item.time);
                 const data = item.data ?? {};
                 for (const key of Object.keys(data)) {
                     log.addContent(key, stringifyLogValue(data[key]));
@@ -2102,8 +2213,16 @@
             }
             if (logGroup.getLogs().length === 0)
                 return;
-            const request = new tencentcloudClsSdkJsWeb.PutLogsRequest(this.topicId, logGroup);
-            client.PutLogs(request);
+            const request = new sdk.PutLogsRequest(this.topicId, logGroup);
+            const exit = enterClsSendingGuard();
+            let p;
+            try {
+                p = client.PutLogs(request);
+            }
+            finally {
+                exit();
+            }
+            await p;
         }
         /**
          * 参考《一、概述》：统一上报入口（内存队列 + 批量发送）
@@ -2121,11 +2240,39 @@
                 void this.flushBatch();
                 return;
             }
+            const now = Date.now();
+            const desiredDueAt = this.getDesiredBatchFlushDueAt(now);
+            const desiredDelay = Math.max(0, desiredDueAt - now);
             if (!this.batchTimer) {
+                this.batchTimerDueAt = desiredDueAt;
+                this.batchTimer = setTimeout(() => {
+                    void this.flushBatch();
+                }, desiredDelay);
+                return;
+            }
+            // 启动合并窗口内：如果当前 timer 会“更早”触发，则延后到窗口结束，尽量减少多次发送
+            if (this.batchTimerDueAt !== null && this.batchTimerDueAt < desiredDueAt) {
+                try {
+                    clearTimeout(this.batchTimer);
+                }
+                catch {
+                    // ignore
+                }
+                this.batchTimerDueAt = desiredDueAt;
                 this.batchTimer = setTimeout(() => {
                     void this.flushBatch();
-                }, this.batchIntervalMs);
+                }, desiredDelay);
+            }
+        }
+        getDesiredBatchFlushDueAt(nowTs) {
+            const start = this.initTs || nowTs;
+            const startupDelay = Number.isFinite(this.startupDelayMs) ? Math.max(0, this.startupDelayMs) : 0;
+            if (startupDelay > 0) {
+                const end = start + startupDelay;
+                if (nowTs < end)
+                    return end;
             }
+            return nowTs + this.batchIntervalMs;
         }
         info(message, data = {}) {
             const payload = normalizeFlatFields({ message, ...data }, 'info');
@@ -2156,6 +2303,7 @@
                 clearTimeout(this.batchTimer);
                 this.batchTimer = null;
             }
+            this.batchTimerDueAt = null;
             if (this.memoryQueue.length === 0)
                 return;
             const logs = [...this.memoryQueue];
@@ -2181,18 +2329,19 @@
                 appId: this.appId || undefined,
                 appVersion: this.appVersion || undefined,
                 // 保证“一维字段”：业务数据以 JSON 字符串形式落到 CLS
-                data: stringifyLogValue(mergedData),
+                ...mergedData,
             };
         }
         async sendReportLogs(logs) {
             if (!this.topicId)
                 return;
-            const client = this.getInstance();
-            const logGroup = new tencentcloudClsSdkJsWeb.LogGroup('127.0.0.1');
+            const sdk = await this.loadSdk();
+            const client = await this.getInstance();
+            const logGroup = new sdk.LogGroup('127.0.0.1');
             logGroup.setSource(this.source);
             for (const item of logs) {
                 const fields = this.buildReportFields(item);
-                const log = new tencentcloudClsSdkJsWeb.Log(fields.timestamp);
+                const log = new sdk.Log(fields.timestamp);
                 for (const key of Object.keys(fields)) {
                     if (key === 'timestamp')
                         continue;
@@ -2200,8 +2349,17 @@
                 }
                 logGroup.addLog(log);
             }
-            const request = new tencentcloudClsSdkJsWeb.PutLogsRequest(this.topicId, logGroup);
-            await client.PutLogs(request);
+            const request = new sdk.PutLogsRequest(this.topicId, logGroup);
+            // 只在“发起网络请求”的同步阶段打标记，避免 requestMonitor 监控 CLS 上报请求导致递归
+            const exit = enterClsSendingGuard();
+            let p;
+            try {
+                p = client.PutLogs(request);
+            }
+            finally {
+                exit();
+            }
+            await p;
         }
         retrySendReportLogs(logs, retryCount) {
             if (retryCount > this.retryTimes) {
@@ -2267,6 +2425,146 @@
         }
     }
 
+    function readGlobal(key) {
+        try {
+            const g = globalThis;
+            return g[key] ?? null;
+        }
+        catch {
+            return null;
+        }
+    }
+    function tryRequire(moduleName) {
+        try {
+            // 说明：
+            // - ESM 构建（exports.import/module）里通常不存在模块作用域的 require
+            // - 一些小程序运行时/构建链路会把 require 挂到 globalThis 上
+            // 因此这里同时探测“模块作用域 require”与 “globalThis.require”
+            // eslint-disable-next-line @typescript-eslint/no-implied-eval
+            const localReq = (typeof require === 'function' ? require : null);
+            const globalReq = readGlobal('require');
+            const candidates = [localReq, globalReq].filter((fn) => typeof fn === 'function');
+            for (const fn of candidates) {
+                try {
+                    return fn(moduleName);
+                }
+                catch {
+                    // continue
+                }
+            }
+            return null;
+        }
+        catch {
+            return null;
+        }
+    }
+
+    /**
+     * 兼容版 ClsLogger（默认入口）
+     * - 保留了自动识别环境 + 动态 import 的逻辑
+     * - 如果业务想瘦身，建议改用 @be-link/cls-logger/web 或 /mini
+     */
+    class ClsLogger extends ClsLoggerCore {
+        async loadSdk() {
+            if (this.sdk)
+                return this.sdk;
+            if (this.sdkPromise)
+                return this.sdkPromise;
+            const normalizeSdk = (m) => {
+                const mod = (m?.default && m.default.AsyncClient ? m.default : m);
+                if (mod?.AsyncClient && mod?.Log && mod?.LogGroup && mod?.PutLogsRequest) {
+                    return {
+                        AsyncClient: mod.AsyncClient,
+                        Log: mod.Log,
+                        LogGroup: mod.LogGroup,
+                        PutLogsRequest: mod.PutLogsRequest,
+                    };
+                }
+                return null;
+            };
+            // 1) 外部注入的 loader（最高优先级）
+            if (this.sdkLoaderOverride) {
+                try {
+                    const loaded = await this.sdkLoaderOverride();
+                    const sdk = normalizeSdk(loaded);
+                    if (sdk) {
+                        this.sdk = sdk;
+                        return sdk;
+                    }
+                }
+                catch {
+                    // ignore and fallback
+                }
+            }
+            // 2) 外部直接注入的 sdk
+            if (this.sdkOverride) {
+                const sdk = normalizeSdk(this.sdkOverride);
+                if (sdk) {
+                    this.sdk = sdk;
+                    return sdk;
+                }
+            }
+            const isMini = this.envType === 'miniprogram';
+            // 3) 尝试 require / 全局变量
+            // Mini Program: 尝试直接 require
+            if (isMini) {
+                const reqMod = tryRequire('tencentcloud-cls-sdk-js-mini');
+                const reqSdk = normalizeSdk(reqMod);
+                if (reqSdk) {
+                    this.sdk = reqSdk;
+                    return reqSdk;
+                }
+            }
+            else {
+                // Web: 优先读全局变量 (UMD)
+                const g = readGlobal('tencentcloudClsSdkJsWeb');
+                const sdk = normalizeSdk(g);
+                if (sdk) {
+                    this.sdk = sdk;
+                    return sdk;
+                }
+                // Web: 尝试 require
+                const reqMod = tryRequire('tencentcloud-cls-sdk-js-web');
+                const reqSdk = normalizeSdk(reqMod);
+                if (reqSdk) {
+                    this.sdk = reqSdk;
+                    return reqSdk;
+                }
+            }
+            // 4) 动态 import
+            // 使用字符串字面量，确保 Bundler 能正确识别并进行 Code Splitting
+            if (isMini) {
+                this.sdkPromise = import('tencentcloud-cls-sdk-js-mini')
+                    .then((m) => {
+                    const sdk = normalizeSdk(m);
+                    if (!sdk)
+                        throw new Error(`ClsLogger.loadSdk: invalid sdk module for mini`);
+                    this.sdk = sdk;
+                    return sdk;
+                })
+                    .catch((err) => {
+                    this.sdkPromise = null;
+                    throw err;
+                });
+            }
+            else {
+                this.sdkPromise = import('tencentcloud-cls-sdk-js-web')
+                    .then((m) => {
+                    const sdk = normalizeSdk(m);
+                    if (!sdk)
+                        throw new Error(`ClsLogger.loadSdk: invalid sdk module for web`);
+                    this.sdk = sdk;
+                    return sdk;
+                })
+                    .catch((err) => {
+                    this.sdkPromise = null;
+                    throw err;
+                });
+            }
+            return this.sdkPromise;
+        }
+    }
+
     const clsLogger = new ClsLogger();
 
     exports.ClsLogger = ClsLogger;