@be-link/cls-logger 1.0.1-beta.4 → 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":"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"}

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]';
 }
@@ -1896,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;
@@ -1907,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;
@@ -1949,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;
@@ -1959,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;
@@ -1969,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();
         // 初始化后立即启动请求监听
@@ -2074,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;
@@ -2113,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（默认 “日志内容”）
@@ -2187,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]));
@@ -2200,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;
     }
     /**
      * 参考《一、概述》：统一上报入口（内存队列 + 批量发送）
@@ -2320,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;
@@ -2333,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;

package/dist/index.js

@@ -2,8 +2,6 @@
 
 Object.defineProperty(exports, '__esModule', { value: true });
 
-var tencentcloudClsSdkJsWeb = require('tencentcloud-cls-sdk-js-web');
-
 function isPlainObject(value) {
     return Object.prototype.toString.call(value) === '[object Object]';
 }
@@ -1900,6 +1898,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;
@@ -1911,7 +1930,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;
@@ -1953,6 +1975,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;
@@ -1963,7 +1998,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;
@@ -1973,8 +2008,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();
         // 初始化后立即启动请求监听
@@ -2078,14 +2115,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 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.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;
@@ -2117,22 +2210,33 @@ class ClsLogger {
             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);
+        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（默认 “日志内容”）
@@ -2191,11 +2295,19 @@ class ClsLogger {
             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]));
@@ -2204,14 +2316,16 @@ class ClsLogger {
         }
         if (logGroup.getLogs().length === 0)
             return;
-        const request = new tencentcloudClsSdkJsWeb.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;
     }
     /**
      * 参考《一、概述》：统一上报入口（内存队列 + 批量发送）
@@ -2324,12 +2438,13 @@ class ClsLogger {
     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;
@@ -2337,7 +2452,7 @@ class ClsLogger {
             }
             logGroup.addLog(log);
         }
-        const request = new tencentcloudClsSdkJsWeb.PutLogsRequest(this.topicId, logGroup);
+        const request = new sdk.PutLogsRequest(this.topicId, logGroup);
         // 只在“发起网络请求”的同步阶段打标记，避免 requestMonitor 监控 CLS 上报请求导致递归
         const exit = enterClsSendingGuard();
         let p;

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]';
@@ -1900,6 +1900,27 @@
         };
     }
 
+    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;
@@ -1911,7 +1932,10 @@
     }
     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;
@@ -1953,6 +1977,19 @@
                 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;
@@ -1963,7 +2000,7 @@
             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;
@@ -1973,8 +2010,10 @@
             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();
             // 初始化后立即启动请求监听
@@ -2078,14 +2117,70 @@
             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 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;
+            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.sdkPromise;
         }
         detectEnvType() {
             const wxAny = globalThis.wx;
@@ -2117,22 +2212,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);
+            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（默认 “日志内容”）
@@ -2191,11 +2297,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]));
@@ -2204,14 +2318,16 @@
             }
             if (logGroup.getLogs().length === 0)
                 return;
-            const request = new tencentcloudClsSdkJsWeb.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;
         }
         /**
          * 参考《一、概述》：统一上报入口（内存队列 + 批量发送）
@@ -2324,12 +2440,13 @@
         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;
@@ -2337,7 +2454,7 @@
                 }
                 logGroup.addLog(log);
             }
-            const request = new tencentcloudClsSdkJsWeb.PutLogsRequest(this.topicId, logGroup);
+            const request = new sdk.PutLogsRequest(this.topicId, logGroup);
             // 只在“发起网络请求”的同步阶段打标记，避免 requestMonitor 监控 CLS 上报请求导致递归
             const exit = enterClsSendingGuard();
             let p;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@be-link/cls-logger",
-  "version": "1.0.1-beta.4",
+  "version": "1.0.1-beta.5",
   "description": "@be-link cls-logger - 腾讯云 CLS 日志上报封装",
   "homepage": "https://github.com/snowmountain-top/be-link",
   "author": "zhuiyi",
@@ -21,7 +21,8 @@
     "dist"
   ],
   "dependencies": {
-    "tencentcloud-cls-sdk-js-web": "^1.0.11"
+    "tencentcloud-cls-sdk-js-web": "^1.0.11",
+    "tencentcloud-cls-sdk-js-mini": "^1.0.3"
   },
   "publishConfig": {
     "access": "public"