@fz-firefly/uniapp

萤火虫 SDK 的 uni-app 一键接入包。安装后只需要调用一次 initFirefly，内部会自动完成 uni 平台适配和 Vue 组件错误接入。

@fz-firefly/core、@fz-firefly/shared、@fz-firefly/vue-plugin 都是这个包的内部依赖，用户不需要单独安装或 import。

安装

pnpm add @fz-firefly/uniapp

uni-app + Vue 2

// main.js
import Vue from 'vue'
import App from './App'
import { initFirefly } from '@fz-firefly/uniapp'

initFirefly({
  Vue,
  dsn: process.env.VUE_APP_FIREFLY_DSN,
  endpoint: process.env.VUE_APP_FIREFLY_ENDPOINT,
  environment:
    process.env.NODE_ENV === 'production' ? 'production' : 'development',
  release: process.env.VUE_APP_RELEASE,
})

App.mpType = 'app'

const app = new Vue({
  ...App,
})

app.$mount()

uni-app + Vue 3

// main.ts
import { createSSRApp } from 'vue'
import App from './App.vue'
import { initFirefly } from '@fz-firefly/uniapp'

export function createApp() {
  const app = createSSRApp(App)

  initFirefly({
    app,
    dsn: import.meta.env.VITE_FIREFLY_DSN,
    endpoint: import.meta.env.VITE_FIREFLY_ENDPOINT,
    environment: import.meta.env.PROD ? 'production' : 'development',
    release: import.meta.env.VITE_APP_RELEASE,
  })

  return { app }
}

H5 的运行时

uni-app H5 会先把 window.uni 初始化为空对象，而 SDK 不经过 uni 编译器，直接读全局时会拿不到 request / 存储 API。H5 项目可以把 @dcloudio/uni-h5 导出的 uni 传给 runtime：

import { uni } from '@dcloudio/uni-h5'

initFirefly({
  app,
  runtime: uni,
  // dsn / endpoint ...
})

小程序和 App 平台继续使用全局 uni，不需要传 runtime。

手动上报

初始化后，组件里可以直接使用：

this.$firefly.captureException(new Error('something went wrong'))
this.$firefly.captureMessage('checkout failed', 'warning')

initFirefly 的返回值也可以拿到 client：

const firefly = initFirefly({ Vue, ... })
firefly.client.captureException(error)

行为

• 使用 uni.getStorageSync / uni.setStorageSync 持久化离线队列，失败时退化为内存。
• 使用 uni.request 上报信封。
• 使用 uni.getSystemInfoSync 采集设备、系统、屏幕、网络等上下文。
• 自动挂载 uni.onError / uni.onUnhandledRejection（平台支持时）。
• H5 下检测到内联浏览器 SDK 的 window.__firefly__ 时复用同一个 client，避免两套全局监听重复上报。
• uni.onAppHide 与 H5 pagehide 时冲刷队列。
• 通过 uni.addInterceptor 记录 navigateTo / redirectTo / switchTab / reLaunch / navigateBack 导航面包屑。
• 传入 Vue 或 app 时，同时安装 Vue 组件错误处理，并挂载 $firefly。
• dist 不传时自动使用 uniPlatform，例如 h5 / mp-weixin / app-plus。

平台映射

| uniPlatform | 上报 platform | dist 默认值 | | ------------------ | ------------- | ----------- | | web | web | web | | mp-weixin | mp-weixin | mp-weixin | | mp-alipay | mp-alipay | mp-alipay | | app / app-plus | app | 原始值 | | 其他小程序平台 | app | 原始值 |