微信小程序 SDK

HealthGuard 微信小程序 SDK（@health-guard/sdk-miniprogram）用于在微信、支付宝等小程序运行时中采集错误、请求和页面生命周期信息。

安装

npm install @health-guard/sdk-miniprogram

基础用法

import { createMiniProgramClient } from '@health-guard/sdk-miniprogram';

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

域名配置

小程序要求使用 HTTPS 上报地址，并需要将 Collector 域名添加到小程序后台的「request 合法域名」列表中。

配置选项

选项	类型	必填	默认值	说明
appKey	string	是	-	应用唯一标识
endpoint	string	是	-	Collector 上报地址
wx	MiniProgramWxLike	是	-	小程序全局 wx / my 等运行时对象
platform	string	否	wechat-miniprogram	平台标识，如 alipay-miniprogram
release	string	否	-	应用版本号
environment	string	否	-	环境：development / test / production
userId	string	否	-	业务用户标识
autoCapture	boolean | object	否	false	是否自动捕获错误和请求
flushIntervalMs	number	否	5000	批量上报间隔（毫秒）
maxBatchSize	number	否	10	单次上报最大事件数
transportFailureRetryDelayMs	number	否	30000	transport 失败后回队等待重试的间隔（毫秒）

autoCapture 选项

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

autoCapture: {
  request: true   // 拦截 wx.request
}

手动上报 API

captureException(error, errorType?, context?)

手动上报一个错误：

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

也可以指定错误类型和上下文：

client.captureException('custom error', 'native', { page: 'pages/order/detail' });

captureHttp(input)

手动上报一次 HTTP 请求：

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

addBreadcrumb(breadcrumb)

添加一条面包屑：

client.addBreadcrumb({
  type: 'click',
  message: 'User tapped submit button',
  data: { formId: 'checkout' }
});

wrapPage(route, definition)

为页面生命周期自动添加面包屑：

Page(client.wrapPage('pages/index/index', {
  data: { ... },
  onLoad() { ... },
  onShow() { ... }
}));

wrapApp(definition)

为 App 生命周期自动添加面包屑：

App(client.wrapApp({
  onLaunch() { ... },
  onShow() { ... }
}));

flush()

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

await client.flush();

请求标注

使用 wx.request 时，可通过 healthGuard 字段补充上下文，避免上报敏感数据：

wx.request({
  url: '/api/order',
  healthGuard: {
    page: 'pages/order/detail',
    scene: 'checkout',
    context: { orderId: '123' },
    requestData: { sku: 'abc' }   // 按需上报，不会自动采集
  }
});

隐私与脱敏

• URL Query 中的 authorization、password、token、secret、cookie 等字段会被自动过滤。
• 请求体与响应体默认不上报，需通过 healthGuard.requestData 显式传入。
• 使用业务方传入的 userId 或匿名 ID，不采集真实身份信息。

网络诊断（未发布源码）

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