wechat-miniapp-sdk-azir

面向微信小程序的 TypeScript SDK。

这个库封装了几个在小程序里经常要重复处理的能力：

• 运行时环境识别：优先使用 uni，没有 uni 时退回 wx
• 初始化阶段统一接管应用级事件
• 自动接入微信更新管理器
• 获取版本、设备、网络、启动参数等运行时信息
• 输出适合日志系统直接上报的上下文对象

库产物同时支持：

• ESM：dist/index.mjs
• CommonJS：dist/index.cjs

特性

• uni / wx 双运行时兼容，初始化时自动判断
• 明确的环境兜底：uni 和 wx 都不存在时直接抛环境错误
• 单例模式，适合在 App 启动阶段只初始化一次
• 自动监听 onError、onAppShow、onAppHide
• 自动接入 getUpdateManager
• TypeScript 完整类型

安装

pnpm add wechat-miniapp-sdk-azir

运行时约定

这个 SDK 不是浏览器通用库，它要求运行环境中至少存在以下之一：

• globalThis.uni
• globalThis.wx

初始化时的选择顺序如下：

1. 如果存在 uni，优先使用 uni
2. 如果不存在 uni，但存在 wx，则回退到 wx
3. 如果两者都不存在，调用初始化时会抛出 MiniProgramEnvironmentError

也就是说，这个库适合：

• uni-app 小程序项目
• 原生微信小程序项目
• 通过测试桩在 Node 环境里做单元测试

不适合直接在普通 Web 页面或 Node 服务端里执行初始化逻辑。

快速开始

1. 在应用启动时安装

推荐在应用启动生命周期尽早调用。

import { installWechatSdk } from 'wechat-miniapp-sdk-azir'

onLaunch(() => {
  installWechatSdk({
    enableUpdateManager: true,
    updateModalTitle: '发现新版本',
    updateModalContent: '检测到小程序更新，请重启以使用新版本',
    onError: (error) => {
      // 压栈上报、错误监控等额外业务处理
      console.error('[WechatSdk] 检测到错误', error)
    },
    logger: (event, payload) => {
      console.log(`[WechatSdk] ${event}`, payload)
    },
  })
})

2. 后续通过单例读取信息

import { wechatSdk } from 'wechat-miniapp-sdk-azir'

const version = wechatSdk.getVersionInfo()
const device = wechatSdk.getDeviceInfo()

3. uni-app 示例

import { installWechatSdk, wechatSdk } from 'wechat-miniapp-sdk-azir'

onLunch(()=>{
  installWechatSdk({
    enableUpdateManager: true,
    updateModalTitle: '发现新版本',
    updateModalContent: '检测到小程序更新，请重启以使用新版本',
    onError: (error) => {
      // 压栈上报、错误监控等额外业务处理
      console.error('[WechatSdk] 检测到错误', error)
    },
    logger: (event, payload) => {
      console.log(`[WechatSdk] ${event}`, payload)
    },
  })
})

const version = wechatSdk.getVersionInfo()
console.log('当前版本信息', version)

4. 原生微信小程序示例

import { installWechatSdk, wechatSdk } from 'wechat-miniapp-sdk-azir'

App({
  onLaunch() {
    installWechatSdk({
      logger(event, payload) {
        console.log('[wechat-sdk]', event, payload)
      },
    })

    console.log(wechatSdk.getLaunchOptions())
  },
})

导出内容

这个库当前导出以下内容：

• installWechatSdk
• wechatSdk
• resolveMiniProgramApi
• MiniProgramEnvironmentError
• default：默认导出就是 wechatSdk

另外还有一个仅供测试使用的导出：

• resetWechatSdkForTesting

不建议业务代码依赖 resetWechatSdkForTesting。

初始化

installWechatSdk(options?)

安装并返回 SDK 单例。

import { installWechatSdk } from 'wechat-miniapp-sdk-azir'

const sdk = installWechatSdk()

特点：

• 首次调用时创建实例
• 后续重复调用会复用同一个实例
• 默认会立刻自动初始化

配置项 WechatSdkOptions

interface WechatSdkOptions {
  autoInit?: boolean
  enableUpdateManager?: boolean
  updateModalTitle?: string
  updateModalContent?: string
  updateFailTitle?: string
  updateFailContent?: string
  logger?: (event: string, payload?: unknown) => void
  onError?: (error: string) => void
}

字段说明：

• autoInit 默认 true。创建实例后立即执行初始化。
• enableUpdateManager 默认 true。初始化时自动接入小程序更新管理器。
• updateModalTitle 有新版本可重启时弹窗标题，默认 更新提示。
• updateModalContent 有新版本可重启时弹窗内容，默认 请重启小程序以应用更新。
• updateFailTitle 更新下载失败弹窗标题，默认 更新失败。
• updateFailContent 更新下载失败弹窗内容，默认 新版本下载失败，请稍后重试。
• logger SDK 内部日志钩子。适合接你自己的埋点、日志平台或调试输出。
• onError 应用级错误回调。SDK 监听到小程序全局错误后，除了内部 logger 记录外，还会回调这里。

手动初始化

如果你不希望在安装时立刻初始化，可以关闭 autoInit，然后手动调用 init()。

import { installWechatSdk } from 'wechat-miniapp-sdk-azir'

const sdk = installWechatSdk({
  autoInit: false,
})

sdk.init()

注意：

• 只有 init() 执行后，SDK 才会真正解析运行环境并注册应用事件
• 如果当前不存在 uni 和 wx，init() 会抛 MiniProgramEnvironmentError

环境识别

resolveMiniProgramApi()

手动解析当前运行时环境。

import { resolveMiniProgramApi } from 'wechat-miniapp-sdk-azir'

const runtime = resolveMiniProgramApi()
console.log(runtime.source) // 'uni' 或 'wx'

返回值里最关键的字段是：

• source: 'uni' | 'wx'

使用场景：

• 你想在业务代码里显式知道当前走的是 uni 还是 wx
• 你在单元测试里想验证环境解析逻辑

MiniProgramEnvironmentError

当运行环境里既没有 uni 也没有 wx 时抛出。

import {
  MiniProgramEnvironmentError,
  installWechatSdk,
} from 'wechat-miniapp-sdk-azir'

try {
  installWechatSdk()
}
catch (error) {
  if (error instanceof MiniProgramEnvironmentError) {
    console.error('当前不是受支持的小程序环境')
  }
}

单例对象

wechatSdk

wechatSdk 是一个懒代理对象。你可以把它当成 SDK 单例直接使用。

import { installWechatSdk, wechatSdk } from 'wechat-miniapp-sdk-azir'

installWechatSdk()

console.log(wechatSdk.getVersionInfo())

建议：

• 先执行 installWechatSdk(...)
• 再访问 wechatSdk 上的方法

虽然 wechatSdk 内部会懒创建实例，但如果你希望配置项生效，最好在首次访问任何方法之前先调用 installWechatSdk()。

SDK 方法说明

init()

初始化 SDK。

它会做这些事情：

• 解析运行环境，确定使用 uni 还是 wx
• 读取启动参数快照
• 注册全局应用事件
• 如果启用更新管理器，则注册更新检测逻辑

const sdk = installWechatSdk({ autoInit: false })
sdk.init()

checkUpdate()

手动补触发更新管理器初始化。

wechatSdk.checkUpdate()

说明：

• 实际上微信更新管理器初始化后会自动检查更新
• 这个方法更适合业务侧显式补初始化或确保更新逻辑已经挂上

getLaunchOptions()

获取应用初始化阶段记录的启动参数。

const launchOptions = wechatSdk.getLaunchOptions()

返回类型：

interface WechatLaunchOptions {
  path: string
  scene: number
  query: Record<string, string>
  shareTicket?: string
  referrerInfo?: {
    appId?: string
    extraData?: Record<string, unknown>
  }
  forwardMaterials?: Array<{
    type: string
    name: string
    path: string
    size: number
  }>
  chatType?: number
  apiCategory?: string
}

适用场景：

• 记录首次启动来源
• 渠道归因
• 页面跳转参数追踪

getLastShowOptions()

获取最近一次 App Show 时记录的参数。

const lastShow = wechatSdk.getLastShowOptions()

返回类型：

interface WechatShowOptions extends WechatLaunchOptions {
  entryType?: string
  appURL?: string
}

说明：

• 初次启动后如果还没有发生过切前台行为，可能返回 null
• 适合分析应用从后台恢复时的来源和场景

getVersionInfo()

获取版本相关信息。

const versionInfo = wechatSdk.getVersionInfo()

返回类型：

interface WechatVersionInfo {
  currentVersion: string
  envVersion: 'develop' | 'trial' | 'release' | string
  sdkVersion: string
  hasUpdate: boolean
}

字段说明：

• currentVersion 当前线上版本号，开发和体验版环境里可能为空字符串
• envVersion 当前运行环境，一般是 develop、trial 或 release
• sdkVersion 微信基础库版本
• hasUpdate 当前 SDK 记录的是否存在新版本

getDeviceInfo()

获取设备、窗口和应用基础信息的聚合结果。

const deviceInfo = wechatSdk.getDeviceInfo()

返回类型：

interface WechatDeviceInfo {
  brand?: string
  model?: string
  deviceOrientation?: string
  pixelRatio?: number
  screenWidth?: number
  screenHeight?: number
  windowWidth?: number
  windowHeight?: number
  statusBarHeight?: number
  safeArea?: {
    left?: number
    right?: number
    top?: number
    bottom?: number
    width?: number
    height?: number
  }
  platform?: string
  system?: string
  language?: string
  version?: string
  theme?: string
  benchmarkLevel?: number
  fontSizeSetting?: number
  SDKVersion?: string
  host?: Record<string, unknown>
}

这个结果聚合了：

• 设备信息
• 窗口和屏幕信息
• 应用基础信息

适合：

• 日志采集
• 兼容性排查
• UI 适配决策

getNetworkInfo()

异步获取当前网络信息。

const networkInfo = await wechatSdk.getNetworkInfo()

返回类型：

interface WechatNetworkInfo {
  networkType: string
  isConnected?: boolean
}

行为说明：

• 如果底层接口调用失败，返回 { networkType: 'unknown' }
• 同时会通过 logger 打出 network:get:fail

getRuntimeInfo()

异步获取完整运行时快照。

const runtimeInfo = await wechatSdk.getRuntimeInfo()

返回类型：

interface WechatRuntimeInfo {
  version: WechatVersionInfo
  device: WechatDeviceInfo
  network: WechatNetworkInfo
  launchOptions: WechatLaunchOptions | null
  lastShowOptions: WechatShowOptions | null
  timestamp: number
}

这是最适合直接上报监控系统的一份聚合信息。

getLogContext(extra?)

生成适合日志打点直接使用的上下文对象。

const context = await wechatSdk.getLogContext({
  page: 'home',
  action: 'click_banner',
})

返回结构等价于：

{
  ...await wechatSdk.getRuntimeInfo(),
  extra: {
    page: 'home',
    action: 'click_banner',
  }
}

适合：

• 错误日志
• 行为埋点
• 业务事件上报

内部监听的事件

初始化后，SDK 会尝试接入以下应用级事件：

• onError
• onAppShow
• onAppHide

对应行为：

• onError 记录 app:error 日志，并调用你传入的 options.onError
• onAppShow 记录最近一次前台参数，并输出 app:show
• onAppHide 输出 app:hide

更新管理器行为

如果 enableUpdateManager !== false，初始化后会自动尝试接入更新管理器。

内部流程：

1. 调用 getUpdateManager
2. 监听 onCheckForUpdate
3. 监听 onUpdateReady
4. 监听 onUpdateFailed

具体表现：

• 检查到新版本时，内部会更新 hasUpdate
• 新版本准备完成时，弹出确认框
• 用户确认后调用 applyUpdate()
• 下载失败时，弹出失败提示框

自定义更新提示文案

installWechatSdk({
  updateModalTitle: '发现新版本',
  updateModalContent: '新版本已准备完成，点击确定立即重启更新',
  updateFailTitle: '更新下载失败',
  updateFailContent: '请退出小程序后重新打开再试',
})

日志事件

如果你传入了 logger(event, payload)，SDK 会在内部关键节点输出事件。

常见事件包括：

• sdk:init
• app:error
• app:show
• app:hide
• update-manager:init
• update-manager:check
• update-manager:ready
• update-manager:apply
• update-manager:failed
• update-manager:modal:fail
• update-manager:unavailable
• account-info:get:fail
• device-info:get:fail
• window-info:get:fail
• app-base-info:get:fail
• launch-options:get:fail
• network:get:fail

日志接入示例

installWechatSdk({
  logger(event, payload) {
    console.log(`[wechat-sdk] ${event}`, payload)
  },
})

错误处理建议

推荐把环境错误和业务错误分开处理。

import {
  installWechatSdk,
  MiniProgramEnvironmentError,
} from 'wechat-miniapp-sdk-azir'

try {
  installWechatSdk({
    onError(error) {
      console.error('miniapp global error:', error)
    },
  })
}
catch (error) {
  if (error instanceof MiniProgramEnvironmentError) {
    console.error('当前环境不支持初始化微信小程序 SDK')
  }
  else {
    console.error('初始化失败', error)
  }
}

在测试环境里声明 uni / wx

这个库支持在本地测试里通过给 globalThis 挂测试桩来声明运行时变量。

使用 uni 测试桩

globalThis.uni = {
  getLaunchOptionsSync: () => ({
    path: '/pages/index/index',
    scene: 1001,
    query: {},
  }),
  getAccountInfoSync: () => ({
    miniProgram: {
      version: '1.0.0',
      envVersion: 'release',
    },
  }),
  getAppBaseInfo: () => ({
    SDKVersion: '3.0.0',
  }),
}

使用 wx 测试桩

globalThis.wx = {
  getLaunchOptionsSync: () => ({
    path: '/pages/home/index',
    scene: 1007,
    query: { from: 'wx' },
  }),
}

如果测试之间需要重置单例，可以使用：

import { resetWechatSdkForTesting } from 'wechat-miniapp-sdk-azir'

resetWechatSdkForTesting()

这个方法主要给测试使用，不建议在生产代码中调用。

开发

pnpm install
pnpm typecheck
pnpm test
pnpm build

发布流程

pnpm changeset
pnpm version-packages
pnpm release

说明：

• pnpm changeset：新增版本变更说明
• pnpm version-packages：根据 changesets 更新版本号
• pnpm release：发布 npm 包

产物说明

构建后输出在 dist/：

• index.mjs
• index.cjs
• index.d.mts
• index.d.cts

其中：

• ESM 消费者走 import
• CommonJS 消费者走 require

License

MIT