@supernathaniel/umi-plugin

把 @supernathaniel/sdk 性能采集接入 umi 应用的插件。宿主只需安装本包并在 umi config 注册，无需直接依赖 @supernathaniel/sdk。

安装与注册

pnpm add @supernathaniel/umi-plugin -D   # npmjs 公开包，默认 registry / npmmirror 直接可装

// framework/config/config.ts
plugins: [
  // ...已有插件
  require.resolve('@supernathaniel/umi-plugin'),
],
fpPerf: {
  appKey: 'bom-web',                 // 缺省取宿主 package.json name（多应用共用包名时必须显式）
  // collectUrl: '/integration/perfCollect/ingest.api', // 默认值，dev 与生产同形（网关按前缀路由）
  // configUrl: '/integration/perfConfig/findConfig.api', // 默认值，显式 '' 关闭远端采样
  // compress: true,                 // gzip 上报；后端未支持 gzip 请求解码时必须显式 false
  // panel: true,                    // 取证面板入口（默认 true）；false 时完全零副作用
  // panelUrl: '/fp-viewer/panel.js',// 面板脚本地址默认值，与 /fp-viewer/ 托管同路径
  // traceRate / slowTraceMs / flushIntervalMs 均有默认值
},

开关

• FP=1 环境变量（本地开发，与 start-ibom-fp 一致），或
• fpPerf: { enabled: true }（构建期固化，生产接入用）

未开启时插件注册后立即返回，对构建零影响。

开启后发生什么

1. entry 最前面注入 init.js → initFpPerf(sdkConfig)（config 在构建期内联）；
2. 注册 runtime 插件：React Profiler 包裹根节点（生产 React 不触发回调，透明传递）；
3. 宿主若安装了 @supernathaniel/viewer：dev server 挂 /fp-viewer/ 静态中间件，把 viewer 的 dist 以同源子路径托管（viewerPath 可改路径，viewerStatic: false 可关闭）。

URL 分类（fpPerf 配置）

umi dev server 的 HMR 通道是 SockJS 长连接（断线自动重连），采集它会占住 trace 在途名额、 把所有 trace 强制截断——插件默认内置忽略 /dev-server/、/sockjs-node/、.hot-update.，无需配置。

• ignoreUrls: string[]：追加不采集的 URL（子串匹配），与内置默认合并；
• streamingUrls: string[]：SSE/流式接口（如 ['/bommgmtsse/']）——照常采集（瀑布图可见， 事件带 streaming:true 标记）但不占 trace 在途名额，长连接不再把 trace 挂到强制截断。

注意：sdkConfig 经 JSON 内联进 entry，此处只支持字符串；需要 RegExp 时请直接用 @supernathaniel/sdk 的 initFpPerf。

viewer 面板（仪表盘）接入

宿主安装 @supernathaniel/viewer 后，面板即可经 iframe 同源嵌入（dev 由上面的中间件托管）：

<iframe src="/fp-viewer/" />

viewer 的接口 baseURL 固定为同源 /integration（接口路径带 .api 后缀，经网关按前缀路由；perfmgmt 已并入 integration-app，2026-09-20 与后端对齐不设独立前缀），dev 走 umi 代理/中间件，生产走聚合网关。 生产部署：把 node_modules/@supernathaniel/viewer/dist 拷入宿主构建产物的同名子路径（如 dist/fp-viewer/），由宿主既有静态托管（nginx/OSS/CDN）承接，无需动后端与网关路由。

取证面板（Runtime Forensics 阶段一）

sdk 内置面板入口 stub（默认开启，未激活零副作用）。三入口任一命中即激活：

• 快捷键 option+shift+P（按 e.code === 'KeyP' 判定，绕开 macOS option 组合键的 key 变体）；
• URL 参数 ?__fp_debug=1；
• localStorage.__fp_panel = "1"。

激活后按需注入 panelUrl 脚本——自包含 classic script（React 18 内联、Shadow DOM 自挂载、暴露 window.__fpPanel），加载失败仅 console.warn，不影响宿主页面。

前提：宿主升级的 @supernathaniel/viewer 版本 dist 含 panel.js。dev 下由 /fp-viewer/ 静态中间件原样服务（dist 任意文件，无需新路由）；生产由宿主静态产物承接 /fp-viewer/panel.js （与 viewer dist 同包拷入、同路径，见上一节）。

• panel: false：关闭入口 stub（三入口均不再注入脚本）；
• panelUrl: '/自定义路径/panel.js'：面板脚本托管在别处时覆盖默认地址（空串视为未配置）。

生产接入形状

enabled: true + collectUrl 指向网关承接的上报地址；中间件只存在于 dev server，不进产物。

pnpm 说明

init.js/runtime.js 对 @supernathaniel/sdk、@supernathaniel/runtime-react、react 的引用从插件自身依赖树解析 （react 为 peer，pnpm 自动链接宿主版本，保证单例）。宿主不需要直接安装 @supernathaniel/* 其他包。