@fz-firefly/unplugin

萤火虫 SDK 的构建插件。支持 webpack 4 / webpack 5 / Vite，负责：

• 可选地开启构建工具的 source map 生成
• 构建结束后扫描 .js.map
• 把 .map 路径换算成 JS 路径
• 用项目令牌上传到 Firefly
• 分批、重试、失败降级和可选删除本地 map

运行时 SDK（@fz-firefly/web / @fz-firefly/uniapp）不负责上传 source map。

安装

pnpm add -D @fz-firefly/unplugin

webpack 4 / 5

// webpack.config.js
const { fireflyWebpack } = require('@fz-firefly/unplugin/webpack')

module.exports = {
  mode: 'production',
  devtool: 'source-map',
  plugins: [
    fireflyWebpack({
      endpoint: process.env.FIREFLY_ENDPOINT,
      release: process.env.FIREFLY_RELEASE,
      dist: process.env.FIREFLY_DIST,
      sourcemap: {
        // 默认只在 CI 上传；本地想测试时显式设为 true
        enabled: process.env.CI === 'true',
        token: process.env.FIREFLY_TOKEN,
        // 可选：让插件设置 devtool: 'source-map'
        generate: true,
        // 可选：上传成功后删除本地 .map
        deleteAfterUpload: true,
        // 可选：补 sourcesContent，后台能看到源码上下文
        sourcesContent: true,
      },
    }),
  ],
}

Vite

// vite.config.ts
import { defineConfig } from 'vite'
import { fireflyVite } from '@fz-firefly/unplugin/vite'

export default defineConfig({
  plugins: [
    fireflyVite({
      endpoint: process.env.FIREFLY_ENDPOINT,
      release: process.env.FIREFLY_RELEASE,
      dist: process.env.FIREFLY_DIST || 'h5',
      sourcemap: {
        // 默认只在 CI 上传；本地想测试时显式设为 true
        enabled: process.env.CI === 'true',
        token: process.env.FIREFLY_TOKEN,
        // 可选：自动设置 build.sourcemap = true
        generate: true,
        // 可选：上传成功后删除本地 .map
        deleteAfterUpload: true,
        // 可选：补 sourcesContent
        sourcesContent: true,
      },
    }),
  ],
})

Vite 的 closeBundle 在产物写完后执行，插件会自动扫描 outDir；uni-app Vite 如果输出到 .sourcemap/<platform>，也会自动检测。

内联 SDK

开启 script 后，插件会把 @fz-firefly/web 的 IIFE 产物直接注入 HTML <head> 最前面，不依赖额外的 SDK JS 文件。IIFE 在构建时已经压缩，产物约 38KB，gzip 后约 12KB：

fireflyVite({
  endpoint: process.env.FIREFLY_ENDPOINT,
  release: process.env.FIREFLY_RELEASE,
  dist: 'h5',
  script: {
    dsn: 'ff_xxx',
    environment: 'production',
    // 严格 CSP 环境需要：
    // nonce: 'nonce-xxx',
  },
})

注入后会生成：

window.__firefly__ = Firefly.initFirefly({ ... })

业务入口可以复用 window.__firefly__，再挂 Vue / React / uni-app / Taro 的框架 hooks：

const handle = window.__firefly__ ?? initFirefly({ ... })

需要 @fz-firefly/web 已安装并构建出 dist/firefly.iife.js。也可以通过 script.code 直接传入自定义 IIFE 代码，代码必须暴露全局 Firefly.initFirefly。

uni-app 2（webpack 4）

uni-app 2 是否生成 source map 由 SOURCEMAP 环境变量控制，最好在 vue.config.js 顶部开启：

process.env.SOURCEMAP = 'true'

const { fireflyWebpack } = require('@fz-firefly/unplugin/webpack')

module.exports = {
  configureWebpack: {
    plugins: [
      fireflyWebpack({
        endpoint: process.env.FIREFLY_ENDPOINT,
        release: process.env.FIREFLY_RELEASE,
        dist: process.env.FIREFLY_DIST || process.env.UNI_PLATFORM,
        sourcemap: {
          enabled: process.env.CI === 'true',
          token: process.env.FIREFLY_TOKEN,
          // uni-app 会把 map 输出到 dist/build/.sourcemap/<platform>，
          // 插件会自动检测这个目录。
        },
      }),
    ],
  },
}

配置

| 字段 | 说明 | | ------------------------------- | --------------------------------------------------------------- | | endpoint | Firefly 服务端地址，默认 FIREFLY_ENDPOINT | | buildId | 一次构建的标识，默认自动生成；分批上传共享同一个值 | | release | 版本号，必须和 initFirefly({ release }) 一致 | | dist | 分发标识，必须和 initFirefly({ dist }) 一致 | | sourcemap.enabled | 是否上传，默认只在 CI=true/1 时开启 | | sourcemap.token | 项目上传令牌，默认 FIREFLY_TOKEN，需要 sourcemap:write 权限 | | sourcemap.generate | 是否尝试开启 source map，默认 false | | sourcemap.mapDir | .map 目录，默认自动检测 | | sourcemap.outDir | JS 产物目录，默认 webpack output.path | | sourcemap.base | JS URL 前缀，默认 output.publicPath | | sourcemap.include / exclude | 文件过滤，支持 RegExp 或字符串数组 | | sourcemap.skipVendorOnly | 纯 vendor map 是否跳过，默认 true；混合包会保留 | | sourcemap.batchBytes | 单批字节上限，默认 20MB | | sourcemap.maxFiles | 单批文件数上限，默认 100 | | sourcemap.deleteAfterUpload | 上传成功后删除 .map，默认 false | | sourcemap.failOnError | 上传失败是否让构建失败，默认 false | | sourcemap.uploadInDevelopment | 开发构建是否上传，默认 false | | sourcemap.uploadOnWatch | watch 模式是否上传，默认 false | | sourcemap.retries | 失败重试次数，默认 3 | | sourcemap.sourcesContent | 是否补源码内容，默认 false | | sourcemap.sourceRoot | 源码根目录，默认 webpack context | | script | 内联浏览器 SDK；传对象开启，传 false 或不传关闭 | | script.dsn | 项目 DSN，开启内联时必填 | | script.environment | 运行环境，默认按 NODE_ENV 推断 | | script.nonce | CSP nonce | | script.code | 自定义 IIFE 代码，需暴露 Firefly.initFirefly |

上传接口

POST {endpoint}/api/ingest/v1/sourcemaps
Authorization: Bearer <project token>
Content-Type: application/json

{
  "version": "[email protected]+3f2a1c9",
  "dist": "mp-weixin-MALL",
  "buildId": "9f0c2e6a-7b1d-4c3e-8a5f-2d6b7c8e9f01",
  "files": [
    {
      "filePath": "/common/main.js",
      "content": "..."
    }
  ]
}

version 对应运行时 release，dist 对应运行时 dist，两者必须完全一致。

注意

• 默认只在 CI 上传；本地生产构建想验证时设置 sourcemap.enabled: true。
• 上传成功后按文件打印 [firefly] sourcemap uploaded: <filePath>。
• Taro 环境通过 TARO_ENV 识别；Taro H5 把上传放到 compiler.shutdown，同一个 buildId 只上传一次。
• sourcemap.generate 对标准 webpack 4/5 有效；uni-app 2 建议显式设置 process.env.SOURCEMAP = 'true'。
• 小程序真机堆栈可能经过微信二次编译，uni-app 的 map 不一定能完整还原；先用真实设备验证。
• source map 可能包含源码，sourcesContent 和上传令牌都要注意权限。