Langfuse 前端性能优化：用 SWR 订阅去重全局事件监听器实战

导读

在 Langfuse 这类大型 React/Next.js 前端应用中，多个组件实例同时监听 window 等全局对象上的事件（键盘快捷键、滚动、resize 等）十分常见。本文以仓库内 vercel-react-best-practices 技能包中的 client-event-listeners 规则 为核心，讲解如何借助 SWR 的 useSWRSubscription 把"N 个组件实例 = N 个监听器"重构为"N 个组件实例 = 1 个监听器"，并配套讲解被动事件监听与事件处理器存入 ref 两个相邻优化技巧。读完你将掌握一套可直接落地的全局事件订阅去重方案，并能在 Langfuse 源码中找到对应的工程实践佐证。

---

一、问题本质：每个组件实例都注册一个全局监听器

当一个自定义 Hook 被多个组件实例复用时，React 的 useEffect 会在每个实例挂载时各自执行一遍。如果 Hook 内部直接向 window 或 document 添加事件监听器，那么 N 个组件实例就会产生 N 个监听器。

原规则文档给出的反面示例是一个键盘快捷键 Hook：

function useKeyboardShortcut(key: string, callback: () => void) {
  useEffect(() => {
    const handler = (e: KeyboardEvent) => {
      if (e.metaKey && e.key === key) {
        callback()
      }
    }
    window.addEventListener('keydown', handler)
    return () => window.removeEventListener('keydown', handler)
  }, [key, callback])
}

问题链条很清晰：

1. 每次 keydown 事件触发，浏览器需要依次调用 N 个几乎相同的回调；
2. 每个监听器都独立比较 metaKey 与 e.key，逻辑被重复执行；
3. 组件频繁挂载/卸载时，监听器反复 add/remove，还会引入时序性 Bug（例如卸载顺序导致的幽灵监听）；
4. callback 作为依赖项时，只要父组件传入新函数引用，Hook 就会重新订阅一次，进一步放大监听器数量。

在 Langfuse 的 Trace 详情页、Playground 等高频交互界面中，这类模式会造成可感知的事件处理开销与调试噪音。

---

二、核心方案：模块级 Map 聚合回调 + useSWRSubscription 统一订阅

原规则文档给出的正确做法分两层：

第一层：模块级 Map 聚合回调。 用 Map<string, Set<() => void>> 把同一按键的所有回调收集到一个集合中，组件卸载时只从集合中删除自己的回调，而不是移除全局监听器。

第二层：useSWRSubscription 保证整个应用只有一个底层监听器。 SWR 的订阅 API 以 key 做全局去重——同一个 key 的订阅在任意时刻只会存在一份资源与订阅逻辑，这正是把"每实例一监听"降为"全局一监听"的关键。

完整示例（继承自原文档）：

import useSWRSubscription from 'swr/subscription'

// Module-level Map to track callbacks per key
const keyCallbacks = new Map<string, Set<() => void>>()

function useKeyboardShortcut(key: string, callback: () => void) {
  // Register this callback in the Map
  useEffect(() => {
    if (!keyCallbacks.has(key)) {
      keyCallbacks.set(key, new Set())
    }
    keyCallbacks.get(key)!.add(callback)

    return () => {
      const set = keyCallbacks.get(key)
      if (set) {
        set.delete(callback)
        if (set.size === 0) {
          keyCallbacks.delete(key)
        }
      }
    }
  }, [key, callback])

  useSWRSubscription('global-keydown', () => {
    const handler = (e: KeyboardEvent) => {
      if (e.metaKey && keyCallbacks.has(e.key)) {
        keyCallbacks.get(e.key)!.forEach(cb => cb())
      }
    }
    window.addEventListener('keydown', handler)
    return () => window.removeEventListener('keydown', handler)
  })
}

function Profile() {
  // Multiple shortcuts will share the same listener
  useKeyboardShortcut('p', () => { /* ... */ })
  useKeyboardShortcut('k', () => { /* ... */ })
  // ...
}

2.1 分层职责拆解

层	职责	生命周期
Map<string, Set<cb>>	按 key 聚合回调，供事件分派时批量调用	模块级，随应用存活
useEffect（注册回调）	把当前实例的 callback 加入/移出集合	跟随组件实例挂载/卸载
useSWRSubscription（订阅）	全局唯一地创建/销毁 keydown 监听器	跟随 SWR 订阅缓存，全局一份

2.2 为什么 useSWRSubscription 是关键

useSWRSubscription 是 SWR 在 swr/subscription 子路径下导出的订阅原语。它的两个重要特性恰好命中本场景：

• 按 key 去重：'global-keydown' 作为订阅 key，所有调用该 Hook 的组件共享同一份订阅资源。第一个组件挂载时创建监听器，最后一个组件卸载时销毁监听器；
• 卸载即清理：SWR 会在最后一个订阅者离开后执行订阅函数返回的清理函数（即 removeEventListener），避免泄漏。

因此，无论 Profile 被渲染多少次、同时订阅多少个按键，window 上始终只有一个 keydown 监听器——这正是原规则标题"Deduplicate Global Event Listeners"的含义。

2.3 设计细节与边界

• 按键分发改用 keyCallbacks.has(e.key)：监听器不再与具体按键耦合，任何按键命中集合即有回调，天然支持任意数量的快捷键共存；
• 空集合清理：set.size === 0 时删除该 key 的条目，防止 Map 无限增长；
• Set 的引用稳定性：callback 在依赖数组中变化时，effect 重跑会把新函数加入、旧函数移除，keyCallbacks 始终持有最新引用，不需要重新订阅全局监听器。

---

三、Langfuse 仓库中的工程实践佐证

原规则是 Vercel 工程团队整理的最佳实践（详见 SKILL.md 中的 Client-Side Data Fetching 分类），而 Langfuse 前端代码库中也能找到与"模块级共享订阅、减少重复监听"一致的实践思路。

3.1 模块级 store：use-mobile.tsx

web/src/hooks/use-mobile.tsx 中，Langfuse 使用 useSyncExternalStore 封装 matchMedia 断点查询。其中 createMediaQueryStore 返回的 subscribe 函数只在模块初始化时创建一次 MediaQueryList，多个组件调用 useIsMobile() / useIsHandheld() 时共享同一份 mql.addEventListener("change", ...) 订阅源：

const mobileStore = createMediaQueryStore(MOBILE_QUERY);
const handheldStore = createMediaQueryStore(HANDHELD_QUERY);

export function useIsMobile() {
  return useSyncExternalStore(
    mobileStore.subscribe,
    mobileStore.getSnapshot,
    () => false,
  );
}

虽然这里用的是 React 内置的 useSyncExternalStore 而非 SWR，但思路同源：把全局资源（媒体查询）从组件实例中抽离到模块级，多个订阅者共享同一份底层监听。代码注释也明确写到"Module-level so the store functions stay referentially stable across renders"，即通过模块级常量保证订阅函数引用稳定，避免重复订阅。

3.2 被动 scroll 监听：useVirtualizedScrollSpy.ts

web/src/hooks/useVirtualizedScrollSpy.ts 中，滚动监听添加了 { passive: true } 选项：

scrollElement.addEventListener("scroll", clearFallbackOutsideBuffer, {
  passive: true,
});
return () =>
  scrollElement.removeEventListener("scroll", clearFallbackOutsideBuffer);

这正是相邻规则 client-passive-event-listeners 的落地：滚动/触摸类监听器若不需要调用 preventDefault()，声明为 passive 可让浏览器立即响应滚动，避免因等待监听器执行而造成的滚动延迟。

---

四、配套技巧：什么时候该用 passive，什么时候该把 handler 存进 ref

4.1 被动事件监听器（passive）

规则文档给出的判定标准非常直接：

• 适用 passive：埋点统计、日志记录、以及任何不调用 preventDefault() 的监听器（如 touchstart、wheel、scroll）。声明 { passive: true } 后浏览器不再等待监听器返回，滚动/触摸响应即时生效；
• 禁用 passive：需要自定义滑动手势、自定义缩放等必须调用 preventDefault() 的场景。passive 模式下调用 preventDefault() 会被浏览器忽略并告警。

// Correct：只读数据，无需阻止默认行为
useEffect(() => {
  const handleTouch = (e: TouchEvent) => console.log(e.touches[0].clientX)
  const handleWheel = (e: WheelEvent) => console.log(e.deltaY)

  document.addEventListener('touchstart', handleTouch, { passive: true })
  document.addEventListener('wheel', handleWheel, { passive: true })

  return () => {
    document.removeEventListener('touchstart', handleTouch)
    document.removeEventListener('wheel', handleWheel)
  }
}, [])

4.2 把事件处理器存进 ref（稳定订阅）

当回调本身频繁变化、但你不希望因此反复重新订阅监听器时，advanced-event-handler-refs 规则建议把回调放入 useRef，让订阅只依赖事件名：

function useWindowEvent(event: string, handler: (e) => void) {
  const handlerRef = useRef(handler)
  useEffect(() => {
    handlerRef.current = handler
  }, [handler])

  useEffect(() => {
    const listener = (e) => handlerRef.current(e)
    window.addEventListener(event, listener)
    return () => window.removeEventListener(event, listener)
  }, [event])
}

若项目已升级到最新 React，还可以用 useEffectEvent 获得更简洁的等价 API：它返回一个始终调用最新 handler 的稳定函数引用，订阅同样只依赖 event。此技巧与第二节的去重方案可以叠加使用——订阅只做一次，回调始终最新。

---

五、组合决策速查

场景	推荐做法	参考规则文件
多个组件实例监听同一全局事件	模块级 Map 聚合 + useSWRSubscription 统一订阅	client-event-listeners
滚动/触摸监听，不调 preventDefault()	加 { passive: true }	client-passive-event-listeners
回调频繁变化但不想重复订阅	handler 存入 ref 或用 useEffectEvent	advanced-event-handler-refs

三个技巧的共同原则是：让"订阅动作"与"组件实例数量、回调引用"解耦——订阅收敛到全局唯一，回调保持最新，清理无泄漏。Langfuse 的 use-mobile.tsx 与 useVirtualizedScrollSpy.ts 已经展示了这些原则在真实工程中的两种落地形态，开发者可以在编写新的全局事件 Hook（快捷键、滚动静默、断点响应等）时直接复用这套模式。