uni-app 多端 SDK

HealthGuard uni-app SDK（@health-guard/sdk-uniapp）一套代码同时覆盖 H5、微信小程序、支付宝小程序、抖音小程序和 App 等多个平台，自动检测运行环境并适配对应采集逻辑。

安装

npm install @health-guard/sdk-uniapp

基础用法

import { createUniAppClient } from '@health-guard/sdk-uniapp';

const client = createUniAppClient({
  appKey: 'your-app-key',
  endpoint: 'https://your-server.com/api/events/batch',
  autoCapture: true
});

平台自动检测

SDK 会根据运行环境自动设置 platform 字段：

运行环境	platform 值
H5	uniapp-h5
微信小程序	uniapp-wechat
支付宝小程序	uniapp-alipay
抖音/头条小程序	uniapp-douyin
App	uniapp-app
未知	uniapp

配置选项

选项	类型	必填	默认值	说明
appKey	string	是	-	应用唯一标识
endpoint	string	是	-	Collector 上报地址
release	string	否	-	应用版本号
environment	string	否	-	环境：development / test / production
userId	string	否	-	业务用户标识
autoCapture	boolean | object	否	false	是否自动捕获错误、请求和 Promise rejection
flushIntervalMs	number	否	5000	批量上报间隔（毫秒）
maxBatchSize	number	否	10	单次上报最大事件数
transportFailureRetryDelayMs	number	否	30000	transport 失败后回队等待重试的间隔（毫秒）

autoCapture 选项

当 autoCapture 为 true 时，全部自动采集开启：

autoCapture: {
  errors: true,               // JS 运行时错误
  unhandledRejections: true,  // 未处理的 Promise rejection
  fetch: true,                // H5 fetch（仅在 H5 环境生效）
  xhr: true,                  // H5 XMLHttpRequest（仅在 H5 环境生效）
  request: true               // uni.request（仅在小程序/App 环境生效）
}

手动上报 API

captureException(error)

手动上报一个错误：

try {
  riskyOperation();
} catch (err) {
  client.captureException(err);
}

captureHttp(input)

手动上报一次 HTTP 请求：

client.captureHttp({
  method: 'POST',
  url: '/api/order',
  status: 500,
  duration: 240,
  success: false,
  errorMessage: 'Internal Server Error'
});

capturePerformance(input)

手动上报一个性能指标：

client.capturePerformance({
  name: 'custom-metric',
  value: 120,
  rating: 'good'
});

addBreadcrumb(breadcrumb)

添加一条面包屑：

client.addBreadcrumb({
  type: 'navigation',
  message: 'User navigated to /pages/order/detail',
  data: { from: '/pages/index/index' }
});

flush()

立即刷新队列，上报所有未发送事件（包括 transport 失败后重新入队的事件）：

await client.flush();

隐私与脱敏

• URL Query 中的 authorization、password、token、secret、cookie 等字段会被自动过滤。
• 不上报 request body 和 response body。
• 使用业务方传入的 userId 或匿名 ID，不采集真实身份信息。

网络诊断（未发布源码）

2026-10-14 源码新增诊断与补传能力，配置方式、发布状态和不可用字段见 网络诊断。Flutter 接入见 Flutter SDK。