@fz-firefly/unplugin 0.0.0-stage → 0.2.1

package/README.md

@@ -1,3 +1,200 @@
-# Temporary Holding Version
+# @fz-firefly/unplugin
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+萤火虫 SDK 的构建插件。支持 **webpack 4 / webpack 5 / Vite**，负责：
+
+- 可选地开启构建工具的 source map 生成
+- 构建结束后扫描 `.js.map`
+- 把 `.map` 路径换算成 JS 路径
+- 用项目令牌上传到 Firefly
+- 分批、重试、失败降级和可选删除本地 map
+
+运行时 SDK（`@fz-firefly/web` / `@fz-firefly/uniapp`）不负责上传 source map。
+
+## 安装
+
+```bash
+pnpm add -D @fz-firefly/unplugin
+```
+
+## webpack 4 / 5
+
+```js
+// 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
+
+```ts
+// 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：
+
+```ts
+fireflyVite({
+  endpoint: process.env.FIREFLY_ENDPOINT,
+  release: process.env.FIREFLY_RELEASE,
+  dist: 'h5',
+  script: {
+    dsn: 'ff_xxx',
+    environment: 'production',
+    // 严格 CSP 环境需要：
+    // nonce: 'nonce-xxx',
+  },
+})
+```
+
+注入后会生成：
+
+```js
+window.__firefly__ = Firefly.initFirefly({ ... })
+```
+
+业务入口可以复用 `window.__firefly__`，再挂 Vue / React / uni-app / Taro 的框架 hooks：
+
+```ts
+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` 顶部开启：
+
+```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`                  |
+
+## 上传接口
+
+```http
+POST {endpoint}/api/ingest/v1/sourcemaps
+Authorization: Bearer <project token>
+Content-Type: application/json
+
+{
+  "version": "cloud-front-wechat@1.0.7+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` 和上传令牌都要注意权限。

package/dist/index.cjs

@@ -0,0 +1,6 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_webpack = require("./webpack.cjs");
+const require_vite = require("./vite.cjs");
+exports.FireflyWebpackPlugin = require_webpack.FireflyWebpackPlugin;
+exports.fireflyVite = require_vite.default;
+exports.fireflyWebpack = require_webpack.default;

package/dist/index.d.cts

@@ -0,0 +1,4 @@
+import { a as FireflyWebpackOptions, i as FireflyViteOptions, n as FireflySourcemapOptions, o as SourcemapFilter, r as FireflyUnpluginOptions, t as FireflyScriptOptions } from "./options-Dn99v-iv.cjs";
+import fireflyWebpack, { FireflyWebpackPlugin } from "./webpack.cjs";
+import fireflyVite from "./vite.cjs";
+export { type FireflyScriptOptions, type FireflySourcemapOptions, type FireflyUnpluginOptions, type FireflyViteOptions, type FireflyWebpackOptions, FireflyWebpackPlugin, type SourcemapFilter, fireflyVite, fireflyWebpack };

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+import { a as FireflyWebpackOptions, i as FireflyViteOptions, n as FireflySourcemapOptions, o as SourcemapFilter, r as FireflyUnpluginOptions, t as FireflyScriptOptions } from "./options-Dn99v-iv.js";
+import fireflyWebpack, { FireflyWebpackPlugin } from "./webpack.js";
+import fireflyVite from "./vite.js";
+export { type FireflyScriptOptions, type FireflySourcemapOptions, type FireflyUnpluginOptions, type FireflyViteOptions, type FireflyWebpackOptions, FireflyWebpackPlugin, type SourcemapFilter, fireflyVite, fireflyWebpack };

package/dist/index.js

@@ -0,0 +1,3 @@
+import fireflyWebpack, { FireflyWebpackPlugin } from "./webpack.js";
+import fireflyVite from "./vite.js";
+export { FireflyWebpackPlugin, fireflyVite, fireflyWebpack };

package/dist/options-Dn99v-iv.d.cts

@@ -0,0 +1,100 @@
+/** source map 文件过滤条件。 */
+type SourcemapFilter = RegExp | string[];
+/** source map 上传配置。 */
+interface FireflySourcemapOptions {
+  /**
+   * 是否上传。默认只在 CI 中开启：
+   * `process.env.CI === 'true' || process.env.CI === '1'`。
+   */
+  enabled?: boolean;
+  /** 项目上传令牌，默认读取 FIREFLY_TOKEN。 */
+  token?: string;
+  /**
+   * 是否让插件尝试开启 source map 生成。默认 false。
+   *
+   * 标准 webpack 4/5 会设置 devtool；uni-app 2 仍建议在
+   * vue.config.js 顶部设置 process.env.SOURCEMAP = 'true'。
+   */
+  generate?: boolean;
+  /** .map 所在目录，默认自动检测 outDir 或 uni-app 的 .sourcemap/<platform>。 */
+  mapDir?: string;
+  /** JS 产物目录，默认 webpack output.path。 */
+  outDir?: string;
+  /** JS URL 前缀，默认 webpack output.publicPath。 */
+  base?: string;
+  /** 只上传匹配的 map 相对路径。 */
+  include?: SourcemapFilter;
+  /** 排除匹配的 map 相对路径。 */
+  exclude?: SourcemapFilter;
+  /**
+   * 是否跳过纯 vendor map，默认 true。
+   *
+   * 判断依据是 map 的 sources：全部来自 node_modules / 框架运行时才跳过；
+   * 只要包含任意业务源码就保留，避免误删混合包。
+   */
+  skipVendorOnly?: boolean;
+  /** 单批最大字节数，默认 20MB。 */
+  batchBytes?: number;
+  /** 单批最大文件数，默认 100。 */
+  maxFiles?: number;
+  /** 上传成功后删除本地 .map，默认 false。 */
+  deleteAfterUpload?: boolean;
+  /** 上传失败是否让构建失败，默认 false。 */
+  failOnError?: boolean;
+  /** 开发构建是否也上传，默认 false。 */
+  uploadInDevelopment?: boolean;
+  /** watch 模式是否上传，默认 false。 */
+  uploadOnWatch?: boolean;
+  /** 失败重试次数，默认 3。 */
+  retries?: number;
+  /** 单次请求超时时间，默认 60s。 */
+  timeoutMs?: number;
+  /** 是否打印日志，默认 true。 */
+  log?: boolean;
+  /** 平台标识，默认读取 UNI_PLATFORM，例如 h5 / mp-weixin。 */
+  platform?: string;
+  /** 是否补全 sourcesContent，默认 false。会增加 map 体积。 */
+  sourcesContent?: boolean;
+  /** 源码根目录，默认 webpack context。 */
+  sourceRoot?: string;
+}
+/** 内联 SDK 初始化配置。 */
+interface FireflyScriptOptions {
+  /** 项目公开写入凭证；从后台项目设置获取。 */
+  dsn: string;
+  /** 运行环境；默认按 NODE_ENV 推断为 production / development。 */
+  environment?: 'production' | 'staging' | 'development';
+  /** CSP nonce；严格 CSP 环境下必须传入。 */
+  nonce?: string;
+  /**
+   * 自定义 IIFE 代码，必须暴露全局 `Firefly.initFirefly`。
+   * 不传时自动读取 `@fz-firefly/web` 的 `dist/firefly.iife.js`。
+   */
+  code?: string;
+}
+/** 构建插件通用配置。 */
+interface FireflyUnpluginOptions {
+  /** Firefly 服务端地址，默认读取 FIREFLY_ENDPOINT。 */
+  endpoint?: string;
+  /** 一次构建的标识；不传时由插件自动生成。 */
+  buildId?: string;
+  /** 发布版本，必须与运行时 initFirefly 的 release 一致。 */
+  release?: string;
+  /** 分发标识，必须与运行时 initFirefly 的 dist 一致。 */
+  dist?: string;
+  /** source map 上传配置；传 false 可完全关闭。 */
+  sourcemap?: false | FireflySourcemapOptions;
+  /**
+   * 把浏览器 SDK 以 IIFE 内联到 HTML `<head>` 最前面。
+   *
+   * 开启后即使业务主 JS 404，内联 SDK 也已经安装并能上报早期错误。
+   * 传 false 或不传表示关闭。框架专项 hooks 仍需在业务入口加载后挂载。
+   */
+  script?: false | FireflyScriptOptions;
+}
+/** webpack 插件配置。 */
+type FireflyWebpackOptions = FireflyUnpluginOptions;
+/** Vite 插件配置。 */
+type FireflyViteOptions = FireflyUnpluginOptions;
+export { FireflyWebpackOptions as a, FireflyViteOptions as i, FireflySourcemapOptions as n, SourcemapFilter as o, FireflyUnpluginOptions as r, FireflyScriptOptions as t };
+//# sourceMappingURL=options-Dn99v-iv.d.cts.map

package/dist/options-Dn99v-iv.d.ts

@@ -0,0 +1,100 @@
+/** source map 文件过滤条件。 */
+type SourcemapFilter = RegExp | string[];
+/** source map 上传配置。 */
+interface FireflySourcemapOptions {
+  /**
+   * 是否上传。默认只在 CI 中开启：
+   * `process.env.CI === 'true' || process.env.CI === '1'`。
+   */
+  enabled?: boolean;
+  /** 项目上传令牌，默认读取 FIREFLY_TOKEN。 */
+  token?: string;
+  /**
+   * 是否让插件尝试开启 source map 生成。默认 false。
+   *
+   * 标准 webpack 4/5 会设置 devtool；uni-app 2 仍建议在
+   * vue.config.js 顶部设置 process.env.SOURCEMAP = 'true'。
+   */
+  generate?: boolean;
+  /** .map 所在目录，默认自动检测 outDir 或 uni-app 的 .sourcemap/<platform>。 */
+  mapDir?: string;
+  /** JS 产物目录，默认 webpack output.path。 */
+  outDir?: string;
+  /** JS URL 前缀，默认 webpack output.publicPath。 */
+  base?: string;
+  /** 只上传匹配的 map 相对路径。 */
+  include?: SourcemapFilter;
+  /** 排除匹配的 map 相对路径。 */
+  exclude?: SourcemapFilter;
+  /**
+   * 是否跳过纯 vendor map，默认 true。
+   *
+   * 判断依据是 map 的 sources：全部来自 node_modules / 框架运行时才跳过；
+   * 只要包含任意业务源码就保留，避免误删混合包。
+   */
+  skipVendorOnly?: boolean;
+  /** 单批最大字节数，默认 20MB。 */
+  batchBytes?: number;
+  /** 单批最大文件数，默认 100。 */
+  maxFiles?: number;
+  /** 上传成功后删除本地 .map，默认 false。 */
+  deleteAfterUpload?: boolean;
+  /** 上传失败是否让构建失败，默认 false。 */
+  failOnError?: boolean;
+  /** 开发构建是否也上传，默认 false。 */
+  uploadInDevelopment?: boolean;
+  /** watch 模式是否上传，默认 false。 */
+  uploadOnWatch?: boolean;
+  /** 失败重试次数，默认 3。 */
+  retries?: number;
+  /** 单次请求超时时间，默认 60s。 */
+  timeoutMs?: number;
+  /** 是否打印日志，默认 true。 */
+  log?: boolean;
+  /** 平台标识，默认读取 UNI_PLATFORM，例如 h5 / mp-weixin。 */
+  platform?: string;
+  /** 是否补全 sourcesContent，默认 false。会增加 map 体积。 */
+  sourcesContent?: boolean;
+  /** 源码根目录，默认 webpack context。 */
+  sourceRoot?: string;
+}
+/** 内联 SDK 初始化配置。 */
+interface FireflyScriptOptions {
+  /** 项目公开写入凭证；从后台项目设置获取。 */
+  dsn: string;
+  /** 运行环境；默认按 NODE_ENV 推断为 production / development。 */
+  environment?: 'production' | 'staging' | 'development';
+  /** CSP nonce；严格 CSP 环境下必须传入。 */
+  nonce?: string;
+  /**
+   * 自定义 IIFE 代码，必须暴露全局 `Firefly.initFirefly`。
+   * 不传时自动读取 `@fz-firefly/web` 的 `dist/firefly.iife.js`。
+   */
+  code?: string;
+}
+/** 构建插件通用配置。 */
+interface FireflyUnpluginOptions {
+  /** Firefly 服务端地址，默认读取 FIREFLY_ENDPOINT。 */
+  endpoint?: string;
+  /** 一次构建的标识；不传时由插件自动生成。 */
+  buildId?: string;
+  /** 发布版本，必须与运行时 initFirefly 的 release 一致。 */
+  release?: string;
+  /** 分发标识，必须与运行时 initFirefly 的 dist 一致。 */
+  dist?: string;
+  /** source map 上传配置；传 false 可完全关闭。 */
+  sourcemap?: false | FireflySourcemapOptions;
+  /**
+   * 把浏览器 SDK 以 IIFE 内联到 HTML `<head>` 最前面。
+   *
+   * 开启后即使业务主 JS 404，内联 SDK 也已经安装并能上报早期错误。
+   * 传 false 或不传表示关闭。框架专项 hooks 仍需在业务入口加载后挂载。
+   */
+  script?: false | FireflyScriptOptions;
+}
+/** webpack 插件配置。 */
+type FireflyWebpackOptions = FireflyUnpluginOptions;
+/** Vite 插件配置。 */
+type FireflyViteOptions = FireflyUnpluginOptions;
+export { FireflyWebpackOptions as a, FireflyViteOptions as i, FireflySourcemapOptions as n, SourcemapFilter as o, FireflyUnpluginOptions as r, FireflyScriptOptions as t };
+//# sourceMappingURL=options-Dn99v-iv.d.ts.map