@fz-firefly/taro

萤火虫 SDK 的 Taro 平台适配层。负责 Taro 存储、请求、系统信息、全局错误、生命周期冲刷和页面上下文，不直接依赖 window、localStorage 或 fetch，因此同一份代码可以跑在 H5、微信小程序、支付宝小程序和 React Native。

React / Vue 的组件错误处理是框架层的事，通过子路径引入：

| 项目 | 平台入口 | 框架入口 | | ------------ | ------------------ | ------------------------ | | Taro + React | @fz-firefly/taro | @fz-firefly/taro/react | | Taro + Vue 3 | @fz-firefly/taro | @fz-firefly/taro/vue |

安装

pnpm add @fz-firefly/taro

Taro 项目本身已经安装 @tarojs/taro，不需要重复安装。

可选：注入 runtime

默认使用 @tarojs/taro。如果 pnpm 等包管理器解析出多份 Taro，SDK 可能拿到未初始化的一份，表现为 Taro.request / 存储 API 不可用。此时可以把项目实际使用的运行时传给 initFirefly：

import Taro from '@tarojs/taro'
import { initFirefly } from '@fz-firefly/taro'

initFirefly({ runtime: Taro, dsn, endpoint })

H5 的 request、getStorageSync 等 API 位于 @tarojs/taro-h5 的命名导出上；测试台会把该模块作为 runtime 注入。

Taro + React

// src/app.tsx
import type { PropsWithChildren } from 'react'
import { initFirefly } from '@fz-firefly/taro'
import { FireflyErrorBoundary } from '@fz-firefly/taro/react'

const firefly = initFirefly({
  dsn: process.env.TARO_APP_FIREFLY_DSN,
  endpoint: process.env.TARO_APP_FIREFLY_ENDPOINT,
  environment:
    process.env.NODE_ENV === 'production' ? 'production' : 'development',
  release: process.env.TARO_APP_RELEASE,
  // dist 不传时自动使用 Taro.getEnv()：h5 / mp-weixin / mp-alipay / rn
})

export default function App({ children }: PropsWithChildren) {
  return (
    <FireflyErrorBoundary client={firefly.client}>
      {children}
    </FireflyErrorBoundary>
  )
}

Taro React 的页面渲染由 Taro 运行时接管，通常不会自己调用 createRoot，所以错误边界是主要的组件错误捕获方式。

Taro + Vue 3

// src/app.ts
import { createApp } from 'vue'
import { initFirefly } from '@fz-firefly/taro'
import { installVue } from '@fz-firefly/taro/vue'
import App from './App.vue'

const firefly = initFirefly({
  dsn: process.env.TARO_APP_FIREFLY_DSN,
  endpoint: process.env.TARO_APP_FIREFLY_ENDPOINT,
  environment:
    process.env.NODE_ENV === 'production' ? 'production' : 'development',
  release: process.env.TARO_APP_RELEASE,
})

const app = createApp(App)
installVue({ client: firefly.client, app })

export default app

installVue 会接管 app.config.errorHandler，并把 client 挂到 app.config.globalProperties.$firefly。Taro 不使用 vue-router，页面面包屑由 SDK 包装的导航 API 负责（见下方限制）。

手动上报

firefly.client.captureException(error, {
  tags: { module: 'order' },
})

firefly.client.track('pay_click', { channel: 'wechat' })

平台识别

Taro.getEnv() 的返回值会映射到上报协议的平台字段：

| Taro 环境 | platform | 默认 dist | | --------------------------- | ----------- | --------------------------------------- | | WEB / H5 | web | h5 | | WEAPP | mp-weixin | mp-weixin | | ALIPAY | mp-alipay | mp-alipay | | RN | app | rn | | SWAN / TT / QQ / JD | app | mp-swan / mp-tt / mp-qq / mp-jd |

协议目前只接受 web / mp-weixin / mp-alipay / app，所以未覆盖的小程序在 platform 上归为 app，真实平台保留在 dist 里，仍可按版本和 dist 区分。

行为与限制

• 应用隐藏、回到前台和 H5 pagehide 时冲刷队列。
• 小程序切后台会触发 onAppHide，这是最后一次补发机会。
• 页面上下文会带上 ctx.page.route 和 ctx.page.query。
• 页面跳转面包屑通过包装 Taro.navigateTo、redirectTo、switchTab、reLaunch、navigateBack 记录。Taro 没有 uni-app 那样的统一路由拦截器，这是跨 React / Vue、跨 H5 / 小程序都能工作的折中方案。
• 已知边界：在 initFirefly 之前解构了导航方法，或直接调用 wx.navigateTo 等平台原生 API，不会经过包装，需要手动 client.addBreadcrumb()。
• 不传 dist 时根据 Taro.getEnv() 自动推断；上传 sourcemap 时必须使用相同的 dist。