@pluve/mp-logger-sdk

微信小程序日志上报 SDK，专为小程序环境优化，剔除了浏览器相关逻辑与冗余依赖。

概览

• 环境支持：仅支持微信小程序（WeChat Mini Program）
• 采集与采样：支持开关控制、日志等级白名单、分级/来源/路径采样率
• 传输适配：使用微信原生 wx.request 进行上报
• 批量与队列：支持批量上报（阈值与定时器双重触发）、队列持久化（使用 wx.setStorageSync）
• 重试策略：可配置最大重试次数与指数退避策略
• 压缩能力：支持 Gzip 压缩（使用 fflate + wx.arrayBufferToBase64），显著减少上报流量

快速开始

安装

pnpm add @pluve/mp-logger-sdk
# 或
npm install @pluve/mp-logger-sdk

使用示例

import { LoggerSDK } from '@pluve/mp-logger-sdk';

const sdk = LoggerSDK.getInstance();

// 1. 初始化 SDK
sdk.init({
  appId: 'your-app-id',
  logStage: 'product', // 环境：develop/trial/release
  token: 'your-access-token',
  
  // 可选配置
  debug: false,
  userId: 'u-001',
  storeCode: 's-001',
  
  // 批量上报配置
  enableBatch: true,
  batchSize: 20,
  batchInterval: 15000,
  
  // 压缩配置
  enableGzip: true,
  gzipBatchMinSize: 2,
  
  // 自动采集配置
  enableAutoCapture: true,
  autoCapture: {
    wechat: true // 开启小程序异常自动捕获（JS Error & Promise Rejection）
  },
  
  // 采样率（0.0 - 1.0）
  sampleRate: 1,
});

// 2. 业务日志上报
sdk.track({
  message: '用户点击了购买按钮',
  traceId: 'trace-xyz', // 可选：链路追踪 ID
  logLevel: 'INFO',     // INFO | WARN | ERROR | FATAL
});

// 3. 动态设置用户信息
sdk.identify('u-002');
sdk.setStoreCode('s-002');

配置项说明

详细类型定义请参考 SDKOptions。

| 配置项 | 类型 | 默认值 | 说明 | | :--- | :--- | :--- | :--- | | appId | string | (必填) | 应用标识 | | token | string | (必填) | 上报鉴权 Token | | logStage | string | (必填) | 日志环境（develop/trial/release） | | enableBatch | boolean | false | 是否启用批量上报 | | batchSize | number | 20 | 批量上报阈值（条数） | | batchInterval | number | 15000 | 批量上报时间间隔（ms） | | enableGzip | boolean | true | 是否启用 Gzip 压缩（仅批量模式生效） | | enableStorage | boolean | true | 是否启用队列持久化（使用 wx.storage） | | enableRetry | boolean | true | 是否启用失败重试 | | enableAutoCapture | boolean | true | 自动采集总开关 | | sampleRate | number | 1.0 | 全局采样率 (0.0-1.0) |

核心特性实现原理

1. 压缩实现

• 使用轻量级 fflate 库进行 Gzip 压缩。
• 压缩后使用小程序原生 API wx.arrayBufferToBase64 转换为 Base64 字符串。
• 相比通用 Base64 库，利用原生能力大幅提升性能并减少包体积。
• 代码参考：compression.ts

2. 传输机制

• WechatTransport：封装 wx.request 发送 POST 请求。
• 编码方式：
  • 未压缩：Body 为 JSON 字符串。
  • 启用压缩：将日志条目数组序列化并 Gzip 压缩为 Base64 字符串，作为字段 items 上报。
• 代码参考：wechatTransport.ts

3. 持久化队列

• 使用 wx.getStorageSync / wx.setStorageSync 实现队列持久化。
• 当发生异常或小程序退出时，未上报的日志会保存在本地，下次启动时自动恢复并尝试上报，防止数据丢失。
• 代码参考：queueManager.ts

4. 堆栈解析

• 内置轻量级堆栈解析器，替代庞大的 stacktrace-js 库。
• 支持 V8 格式（开发者工具/Android）和 JSC 格式（iOS）的 Error Stack 解析。
• 代码参考：stacktrace.ts

依赖说明

• fflate: 用于 Gzip 压缩（已作为 dependencies 包含）。
• 无其他运行时依赖：移除了 js-base64、localforage 等浏览器端依赖。

流程图

构建

# 安装依赖
pnpm install

# 构建产物 (ESM + CJS)
pnpm run build