@be-link/cls-logger 1.0.1-beta.3 → 1.0.1-beta.5

package/dist/ClsLogger.d.ts

@@ -1,7 +1,9 @@
-import { AsyncClient } from 'tencentcloud-cls-sdk-js-web';
 import type { ClsLoggerInitOptions, FlatFields, PutOptions, QueueItem, ReportLog } from './types';
 export declare class ClsLogger {
+    private sdk;
+    private sdkPromise;
     private client;
+    private clientPromise;
     private topicId;
     private endpoint;
     private retryTimes;
@@ -42,7 +44,15 @@ export declare class ClsLogger {
      * - 如需重启：可再次调用 init（或自行调用 init 后的默认启动逻辑）
      */
     stopBehaviorMonitor(): void;
-    getInstance(): AsyncClient;
+    /**
+     * 获取 CLS client（按环境懒加载 SDK）
+     * - browser: 优先走 UMD 全局变量 `tencentcloudClsSdkJsWeb`
+     * - miniprogram: 优先走 require（webpack/taro 可解析），否则 fallback import()
+     */
+    getInstance(): Promise<{
+        PutLogs: (request: unknown) => Promise<unknown> | unknown;
+    }>;
+    private loadSdk;
     private detectEnvType;
     /**
      * 直接上报：埋点入参必须是一维（扁平）Object
@@ -50,6 +60,7 @@ export declare class ClsLogger {
      * - 最终会把 fields 展开成 CLS 的 content（key/value 都会转成 string）
      */
     put(fields: FlatFields, options?: PutOptions): void;
+    private putAsync;
     /**
      * 直接上报：把 data 序列化后放入指定 key（默认 “日志内容”）
      */
@@ -67,6 +78,7 @@ export declare class ClsLogger {
      * 批量上报（每条 item.data 展开为 log content）
      */
     putBatch(queue: QueueItem[]): void;
+    private putBatchAsync;
     /**
      * 参考《一、概述》：统一上报入口（内存队列 + 批量发送）
      */

package/dist/ClsLogger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ClsLogger.d.ts","sourceRoot":"","sources":["../src/ClsLogger.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ClsLogger.d.ts","sourceRoot":"","sources":["../src/ClsLogger.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,oBAAoB,EAGpB,UAAU,EAEV,UAAU,EACV,SAAS,EACT,SAAS,EAEV,MAAM,SAAS,CAAC;AA4DjB,qBAAa,SAAS;IACpB,OAAO,CAAC,GAAG,CAA6B;IACxC,OAAO,CAAC,UAAU,CAAsC;IACxD,OAAO,CAAC,MAAM,CAA8E;IAC5F,OAAO,CAAC,aAAa,CAAuF;IAC5G,OAAO,CAAC,OAAO,CAAuB;IACtC,OAAO,CAAC,QAAQ,CAAmC;IACnD,OAAO,CAAC,UAAU,CAAM;IACxB,OAAO,CAAC,MAAM,CAAe;IAE7B,OAAO,CAAC,SAAS,CAAM;IACvB,OAAO,CAAC,WAAW,CAAM;IACzB,OAAO,CAAC,KAAK,CAAM;IACnB,OAAO,CAAC,UAAU,CAAM;IACxB,OAAO,CAAC,OAAO,CAAsB;IACrC,OAAO,CAAC,sBAAsB,CAAmC;IACjE,OAAO,CAAC,sBAAsB,CAAmC;IACjE,OAAO,CAAC,UAAU,CAAiB;IACnC,OAAO,CAAC,SAAS,CAAM;IAGvB,OAAO,CAAC,WAAW,CAAmB;IACtC,OAAO,CAAC,YAAY,CAAM;IAC1B,OAAO,CAAC,eAAe,CAAO;IAC9B,OAAO,CAAC,UAAU,CAA8C;IAChE,OAAO,CAAC,eAAe,CAAuB;IAC9C,OAAO,CAAC,MAAM,CAAa;IAC3B,OAAO,CAAC,cAAc,CAAa;IAGnC,OAAO,CAAC,cAAc,CAAqB;IAC3C,OAAO,CAAC,cAAc,CAAO;IAC7B,OAAO,CAAC,qBAAqB,CAAS;IACtC,OAAO,CAAC,mBAAmB,CAAS;IACpC,OAAO,CAAC,yBAAyB,CAAS;IAC1C,OAAO,CAAC,sBAAsB,CAAS;IACvC,OAAO,CAAC,sBAAsB,CAA6B;IAC3D,MAAM,EAAE,OAAO,CAAC;IAChB,QAAQ,EAAE,OAAO,CAAC;IAElB,IAAI,CAAC,OAAO,EAAE,oBAAoB,GAAG,IAAI;IAoEzC,OAAO,CAAC,aAAa;IA4BrB,OAAO,CAAC,mBAAmB;IAsB3B,OAAO,CAAC,iBAAiB;IASzB,OAAO,CAAC,uBAAuB;IAS/B,OAAO,CAAC,oBAAoB;IAuB5B;;;OAGG;IACH,mBAAmB,IAAI,IAAI;IAU3B;;;;OAIG;IACG,WAAW,IAAI,OAAO,CAAC;QAAE,OAAO,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAA;KAAE,CAAC;YAsB7E,OAAO;IA2CrB,OAAO,CAAC,aAAa;IAMrB;;;;OAIG;IACH,GAAG,CAAC,MAAM,EAAE,UAAU,EAAE,OAAO,GAAE,UAAe,GAAG,IAAI;YA0BzC,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;IA6B3D;;OAEG;IACH,KAAK,IAAI,IAAI;IAOb;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,IAAI;YAapB,aAAa;IA6B3B;;OAEG;IACH,MAAM,CAAC,GAAG,EAAE,SAAS,GAAG,IAAI;IAyC5B,OAAO,CAAC,yBAAyB;IAUjC,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,UAAe,GAAG,IAAI;IAKlD,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,UAAe,GAAG,IAAI;IAKlD,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,UAAe,GAAG,IAAI;IAKnD,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,GAAE,UAAe,GAAG,IAAI;IASrD;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAkBjC,OAAO,CAAC,iBAAiB;YAmBX,cAAc;IAgC5B,OAAO,CAAC,mBAAmB;IAgB3B,OAAO,CAAC,qBAAqB;IAc7B,WAAW,IAAI,IAAI;IAkBnB;;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"}

package/dist/errorMonitor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errorMonitor.d.ts","sourceRoot":"","sources":["../src/errorMonitor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAG/D,KAAK,QAAQ,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,KAAK,IAAI,CAAC;AA8MzD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,QAAQ,EAAE,IAAI,GAAE,OAAO,GAAG,mBAAmB,GAAG,SAAc,GAAG,IAAI,CAmBhH"}
+{"version":3,"file":"errorMonitor.d.ts","sourceRoot":"","sources":["../src/errorMonitor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAG/D,KAAK,QAAQ,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,KAAK,IAAI,CAAC;AA4QzD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,QAAQ,EAAE,IAAI,GAAE,OAAO,GAAG,mBAAmB,GAAG,SAAc,GAAG,IAAI,CAqBhH"}

package/dist/index.esm.js

@@ -1,5 +1,3 @@
-import { AsyncClient, LogGroup, Log, PutLogsRequest } from 'tencentcloud-cls-sdk-js-web';
-
 function isPlainObject(value) {
     return Object.prototype.toString.call(value) === '[object Object]';
 }
@@ -536,6 +534,8 @@ function installRequestMonitor(report, opts = {}) {
 }
 
 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;
@@ -569,6 +569,54 @@ function normalizeErrorLike(err, maxTextLength) {
     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;
@@ -576,6 +624,7 @@ function installBrowserErrorMonitor(report, options) {
     if (w.__beLinkClsLoggerErrorInstalled__)
         return;
     w.__beLinkClsLoggerErrorInstalled__ = true;
+    const shouldReport = createDedupeGuard(options);
     window.addEventListener('error', (event) => {
         try {
             if (!sampleHit$1(options.sampleRate))
@@ -598,6 +647,8 @@ function installBrowserErrorMonitor(report, options) {
                     if (e.stack)
                         payload.stack = e.stack;
                 }
+                if (!shouldReport(buildErrorKey(options.reportType, payload)))
+                    return;
                 report(options.reportType, payload);
                 return;
             }
@@ -609,6 +660,8 @@ function installBrowserErrorMonitor(report, options) {
                 payload.source = 'resource.error';
                 payload.tagName = tagName;
                 payload.resourceUrl = truncate$2(url, 2000);
+                if (!shouldReport(buildErrorKey(options.reportType, payload)))
+                    return;
                 report(options.reportType, payload);
             }
         }
@@ -629,6 +682,8 @@ function installBrowserErrorMonitor(report, options) {
                 errorName: e.name,
                 stack: e.stack,
             };
+            if (!shouldReport(buildErrorKey(options.reportType, payload)))
+                return;
             report(options.reportType, payload);
         }
         catch {
@@ -641,6 +696,7 @@ function installMiniProgramErrorMonitor(report, options) {
     if (g.__beLinkClsLoggerMpErrorInstalled__)
         return;
     g.__beLinkClsLoggerMpErrorInstalled__ = true;
+    const shouldReport = createDedupeGuard(options);
     const wxAny = globalThis.wx;
     // wx.* 事件（兼容在 App 已经创建后的场景）
     try {
@@ -649,10 +705,13 @@ function installMiniProgramErrorMonitor(report, options) {
                 try {
                     if (!sampleHit$1(options.sampleRate))
                         return;
-                    report(options.reportType, {
+                    const payload = {
                         source: 'wx.onError',
                         message: truncate$2(String(msg ?? ''), options.maxTextLength),
-                    });
+                    };
+                    if (!shouldReport(buildErrorKey(options.reportType, payload)))
+                        return;
+                    report(options.reportType, payload);
                 }
                 catch {
                     // ignore
@@ -670,12 +729,15 @@ function installMiniProgramErrorMonitor(report, options) {
                     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
@@ -697,10 +759,12 @@ function installMiniProgramErrorMonitor(report, options) {
                 next.onError = function (...args) {
                     try {
                         if (sampleHit$1(options.sampleRate)) {
-                            report(options.reportType, {
+                            const payload = {
                                 source: 'App.onError',
                                 message: truncate$2(String(args?.[0] ?? ''), options.maxTextLength),
-                            });
+                            };
+                            if (shouldReport(buildErrorKey(options.reportType, payload)))
+                                report(options.reportType, payload);
                         }
                     }
                     catch {
@@ -716,12 +780,14 @@ function installMiniProgramErrorMonitor(report, options) {
                         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 {
@@ -750,6 +816,8 @@ function installErrorMonitor(report, opts = {}) {
         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);
@@ -1826,6 +1894,27 @@ function createAutoDeviceInfoBaseFields(envType, opts) {
     };
 }
 
+function readGlobal(key) {
+    try {
+        const g = globalThis;
+        return g[key] ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+function tryRequire(moduleName) {
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-implied-eval
+        const req = (typeof require === 'function' ? require : null);
+        if (!req)
+            return null;
+        return req(moduleName);
+    }
+    catch {
+        return null;
+    }
+}
 function enterClsSendingGuard() {
     const g = globalThis;
     const next = (g.__beLinkClsLoggerSendingCount__ ?? 0) + 1;
@@ -1837,7 +1926,10 @@ function enterClsSendingGuard() {
 }
 class ClsLogger {
     constructor() {
+        this.sdk = null;
+        this.sdkPromise = null;
         this.client = null;
+        this.clientPromise = null;
         this.topicId = null;
         this.endpoint = 'ap-shanghai.cls.tencentcs.com';
         this.retryTimes = 10;
@@ -1879,6 +1971,19 @@ class ClsLogger {
             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;
@@ -1889,7 +1994,7 @@ class ClsLogger {
         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;
         this.userGenerateBaseFields = options.generateBaseFields ?? this.userGenerateBaseFields;
         this.autoGenerateBaseFields = createAutoDeviceInfoBaseFields(this.envType, options.deviceInfo);
         this.storageKey = options.storageKey ?? this.storageKey;
@@ -1899,8 +2004,10 @@ class ClsLogger {
         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();
         // 初始化后立即启动请求监听
@@ -2004,14 +2111,70 @@ class ClsLogger {
         this.behaviorMonitorCleanup = null;
         this.behaviorMonitorStarted = false;
     }
-    getInstance() {
+    /**
+     * 获取 CLS client（按环境懒加载 SDK）
+     * - browser: 优先走 UMD 全局变量 `tencentcloudClsSdkJsWeb`
+     * - miniprogram: 优先走 require（webpack/taro 可解析），否则 fallback import()
+     */
+    async getInstance() {
         if (this.client)
             return this.client;
-        this.client = new 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.clientPromise;
+    }
+    async loadSdk() {
+        if (this.sdk)
+            return this.sdk;
+        if (this.sdkPromise)
+            return this.sdkPromise;
+        const isMini = this.envType === 'miniprogram';
+        const moduleName = isMini ? 'tencentcloud-cls-sdk-js-mini' : 'tencentcloud-cls-sdk-js-web';
+        // UMD（浏览器脚本）优先读全局变量
+        if (!isMini) {
+            const g = readGlobal('tencentcloudClsSdkJsWeb');
+            if (g?.AsyncClient && g?.Log && g?.LogGroup && g?.PutLogsRequest) {
+                this.sdk = g;
+                return this.sdk;
+            }
+        }
+        // 尽量同步 require（小程序/webpack 里最稳），失败再走 import()
+        const reqMod = tryRequire(moduleName);
+        if (reqMod?.AsyncClient && reqMod?.Log && reqMod?.LogGroup && reqMod?.PutLogsRequest) {
+            this.sdk = reqMod;
+            return this.sdk;
+        }
+        this.sdkPromise = import(moduleName)
+            .then((m) => {
+            const mod = (m?.default && m.default.AsyncClient ? m.default : m);
+            const sdk = {
+                AsyncClient: mod.AsyncClient,
+                Log: mod.Log,
+                LogGroup: mod.LogGroup,
+                PutLogsRequest: mod.PutLogsRequest,
+            };
+            this.sdk = sdk;
+            return sdk;
+        })
+            .catch((err) => {
+            this.sdkPromise = null;
+            throw err;
         });
-        return this.client;
+        return this.sdkPromise;
     }
     detectEnvType() {
         const wxAny = globalThis.wx;
@@ -2043,22 +2206,33 @@ class ClsLogger {
             appVersion: this.appVersion || undefined,
             ...normalizedFields,
         });
-        const client = this.getInstance();
-        const logGroup = new 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 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 PutLogsRequest(this.topicId, logGroup);
+        const request = new sdk.PutLogsRequest(this.topicId, logGroup);
         const exit = enterClsSendingGuard();
+        let p;
         try {
-            client.PutLogs(request);
+            p = client.PutLogs(request);
         }
         finally {
             exit();
         }
+        await p;
     }
     /**
      * 直接上报：把 data 序列化后放入指定 key（默认 “日志内容”）
@@ -2117,11 +2291,19 @@ class ClsLogger {
             console.warn('ClsLogger.putBatch：未初始化 topic_id');
             return;
         }
-        const client = this.getInstance();
-        const logGroup = new 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 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]));
@@ -2130,14 +2312,16 @@ class ClsLogger {
         }
         if (logGroup.getLogs().length === 0)
             return;
-        const request = new PutLogsRequest(this.topicId, logGroup);
+        const request = new sdk.PutLogsRequest(this.topicId, logGroup);
         const exit = enterClsSendingGuard();
+        let p;
         try {
-            client.PutLogs(request);
+            p = client.PutLogs(request);
         }
         finally {
             exit();
         }
+        await p;
     }
     /**
      * 参考《一、概述》：统一上报入口（内存队列 + 批量发送）
@@ -2250,12 +2434,13 @@ class ClsLogger {
     async sendReportLogs(logs) {
         if (!this.topicId)
             return;
-        const client = this.getInstance();
-        const logGroup = new 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 Log(fields.timestamp);
+            const log = new sdk.Log(fields.timestamp);
             for (const key of Object.keys(fields)) {
                 if (key === 'timestamp')
                     continue;
@@ -2263,7 +2448,7 @@ class ClsLogger {
             }
             logGroup.addLog(log);
         }
-        const request = new PutLogsRequest(this.topicId, logGroup);
+        const request = new sdk.PutLogsRequest(this.topicId, logGroup);
         // 只在“发起网络请求”的同步阶段打标记，避免 requestMonitor 监控 CLS 上报请求导致递归
         const exit = enterClsSendingGuard();
         let p;