cal.diy 前端性能规则解读：用 useSWRSubscription 让 N 个组件共享 1 个全局事件监听器

本文基于 cal.diy（cal.com）仓库中 Agent 技能规则文档 client-event-listeners.md 展开，讲解“全局事件监听器去重”这一客户端性能规则：当同一个键盘/窗口 Hook 被多个组件实例使用时，如何从“N 个实例注册 N 个 listener”重构为“N 个实例共享 1 个 listener”。读完后，你可以掌握该模式的完整代码结构、useSWRSubscription 的订阅语义、落地时的边界条件，并知道该规则与仓库中真实键盘事件处理代码的对应关系。

这条规则在仓库中的位置与定位

该规则是仓库内 Vercel React 最佳实践技能包的一部分，同一规则文件在仓库中有两份镜像位置：

• 需求指定的文档位置：.opencode/skill/vercel-react-best-practices/rules/client-event-listeners.md
• 技能包主目录位置：agents/skills/vercel-react-best-practices/rules/client-event-listeners.md，配套索引见 agents/skills/vercel-react-best-practices/AGENTS.md 与 agents/skills/vercel-react-best-practices/SKILL.md

文档的 YAML 元数据明确了这条规则的定位：

字段	取值	含义
title	Deduplicate Global Event Listeners	规则名称：去重全局事件监听器
impact	LOW	单点影响等级为低（但随组件实例数线性放大）
impactDescription	single listener for N components	目标收益：N 个组件只保留 1 个监听器
tags	client, swr, event-listeners, subscription	适用端与涉及的技术：客户端、SWR、事件监听、订阅

它属于“客户端（client）”侧的订阅型优化规则：适用于监听 window/document 全局事件（keydown、resize、visibilitychange、message 等）的自定义 Hook。

问题模式：每个组件实例各自注册全局监听

原文档给出的反模式是一个键盘快捷键 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])
}

问题出在“监听器随组件实例数线性增长”：

• 每个调用 useKeyboardShortcut 的组件实例都会在 useEffect 里执行 window.addEventListener('keydown', handler)，挂载 N 个组件就有 N 个 keydown 监听器；
• 每次按键事件到达时，浏览器会顺序执行全部 N 个 handler，即使其中 N-1 个 handler 都会立即判空退出（e.key !== key），这次遍历和函数调用开销也是真实发生的；
• 监听器是全局的，无法靠 React 组件树的局部卸载自动“共享”，组件 A 卸载并不会替组件 B 省掉任何工作。

对单次按键而言这是毫秒级以下的问题（这也解释了元数据中 impact 仅为 LOW）；但在命令面板、快捷键密集的配置页这类场景中，监听器数量会随路由切换、组件复用不断累积，且每个监听器都是一个潜在的闭包持有者，值得在架构层面统一治理。

解决方案：模块级回调表 + useSWRSubscription

原文档给出的正确写法由两部分组成：一个模块级回调登记表，和一个全局唯一的 SWR 订阅。完整代码原样继承自文档：

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', () => { /* ... */ })
  // ...
}

注册与清理：每个实例只管登记回调

第一段 useEffect 与事件系统完全无关，它只负责维护模块级（module-level）的登记表 keyCallbacks: Map<string, Set<() => void>>：

• key 作为一级键，Set<() => void> 作为二级容器，保证同一个快捷键被多个组件同时监听时各回调互不覆盖；
• 组件挂载时把自己的 callback 加入对应 Set；
• 清理函数在组件卸载时执行 set.delete(callback)，并在 set.size === 0 时删除整个 key——登记表随组件生命周期精确收缩，不残留死回调，避免“组件已卸载但仍被 Map 强引用”的内存泄漏；
• 登记表必须定义在模块作用域而非组件内部，这样所有组件实例才能读写同一份状态；这也是该模式成立的前提。

唯一监听器：由 SWR 订阅统一持有

第二段 useSWRSubscription('global-keydown', ...) 是整个模式的核心：

• 每个组件实例仍然调用它，但 SWR 的订阅机制保证同一 key 在任意时刻只有一个活跃订阅（详见下一节）；
• 活跃订阅的 setup 函数内部只做一次 window.addEventListener('keydown', handler)，组件卸载、订阅失活时通过返回的清理函数执行 removeEventListener；
• 唯一 handler 的职责变成分发：按键到达时先查 keyCallbacks.has(e.key)，命中后再 forEach 调用该 key 下所有登记的回调。

最终效果就是文档元数据里那句话：single listener for N components——无论 Profile 页面里挂了多少个 useKeyboardShortcut，window 上始终只有 1 个 keydown 监听器。

useSWRSubscription 的关键语义：同一 key 只有一个活跃订阅

要理解为什么上面代码里“每个实例都调用 useSWRSubscription”却不会产生 N 个监听器，需要明确 SWR 订阅的语义：

1. 单活跃实例：同一 key 的订阅在任意时刻只有一个处于激活状态；第一个挂载的实例的 setup 函数执行后，其余实例的 setup 均被挂起，不会重复注册监听器；
2. 失活接力：当处于活跃状态的实例卸载（或订阅被取消）时，其 setup 返回的清理函数会执行（移除 window 上的 keydown 监听器），随后 SWR 会把订阅接力给下一个仍挂载的实例，执行它的 setup 重新注册监听器。因此只要“至少有一个使用方挂载”，监听器就恰好存在一个；
3. 与数据请求的差别：普通 useSWR 是“共享请求结果，N 个实例可并发存在”；useSWRSubscription 面向的是“只有一个消费者有资格持有副作用资源（事件监听、WebSocket、定时器）”的场景，语义上更接近互斥锁而非缓存。

这正好匹配全局事件的诉求：监听器本身是全局单例性质的资源，天然不需要 N 份。

落地细节与边界条件

规则文档的代码是“可直接复制”的，但工程落地时有几个值得显式处理的点：

• callback 的引用稳定性：注册/清理 effect 的依赖是 [key, callback]。如果调用方每次渲染都传入内联箭头函数（如 useKeyboardShortcut('p', () => doX())），callback 引用每帧变化，会导致“注销→重新登记”的抖动（功能正确但产生多余的 Map 操作）。调用方应使用 useCallback 固定引用，或把最新回调存入 ref 中登记、仅以 ref 为依赖；
• key 必须全局稳定：订阅 key（示例中的字符串字面量 'global-keydown'）要跨所有实例保持一致，才能保证它们被 SWR 归并为同一个订阅；不同事件类型（resize、hashchange、message）应使用不同的订阅 key；
• 只适用于客户端：setup 函数会直接触碰 window，因此该模式只应在客户端组件中使用；在 SSR 首屏阶段订阅不会被激活，不会产生“服务端没有 window”的问题；
• 判据不变、分发收敛：注意正确示例中 handler 的判据 e.metaKey && keyCallbacks.has(e.key) 与反模式中的逐实例判据一致，只是把“N 次各自判断”收敛为“1 次全局判断 + 命中后批量调用”。快捷键条件本身没有被简化或改变，行为语义等价；
• 适用边界：该模式适合“全局事件 + 多实例 Hook”的组合。如果某个组件是页面内唯一实例、监听器生命周期与组件严格一致（如焦点管理、Escape 关闭），直接用 useEffect 注册反而是更简单正确的写法，没必要引入订阅层。

在 cal.diy 仓库中的对应场景

从源码结构看，cal.diy 的 Web 应用目前尚未引入 swr/subscription（在 apps/web 下检索 swr/subscription 无源码引用），该规则在仓库中作为 Agent 辅助开发的约束性最佳实践存在；但仓库内存在多处与规则“反模式”形态一致的、按组件实例注册全局 keydown 监听的真实代码，正是这条规则的目标改造对象：

• apps/web/modules/shell/Kbar.tsx：命令面板 Kbar 内部 NoResultsFound 组件在 useEffect 中向 document 注册 keydown 监听，监听器随该组件实例挂载/卸载而注册/移除；
• apps/web/modules/bookings/components/BookingDetailsSheet.tsx：预订详情侧滑面板在 useEffect 中通过 document.addEventListener("keydown", handleKeyDown, true) 以捕获阶段注册快捷键处理（左右翻页、聚焦入会链接等），其 handler 由 createBookingSheetKeydownHandler 构造，行为由 apps/web/modules/bookings/lib/bookingSheetKeyboardHandler.test.ts 单测覆盖；该 effect 依赖了 6 个导航相关状态，监听器会随这些依赖变化而重复拆装；
• 其他按实例注册监听器的位置还包括 apps/web/components/notification-sound-handler.tsx、apps/web/app/(use-page-wrapper)/settings/(settings-layout)/SettingsLayoutAppDirClient.tsx/settings/(settings-layout)/SettingsLayoutAppDirClient.tsx) 等。

需要强调的是，BookingDetailsSheet 这类监听器是“单实例 + 捕获阶段 + 与组件生命周期强绑定”的形态，本身并不构成规则要消除的“N 实例 N 监听器”问题；它们更多作为对照样本，说明“何时该直接注册、何时该去重”的判断依据：只有当同一监听逻辑会随组件实例数复制多份时，模块级登记表 + useSWRSubscription 的收敛才产生收益。

小结

client-event-listeners.md 这条规则给出的是一套可复制的客户端重构模板：

1. 识别“全局事件监听随组件实例数线性增长”的 Hook；
2. 把每个实例的回调收敛到模块级 Map<key, Set<callback>> 登记表，用 effect 的注册/清理保证登记表与组件生命周期同步；
3. 用 useSWRSubscription 以固定 key 持有全局唯一的监听器，利用 SWR“同一 key 单活跃订阅 + 失活接力”的语义保证监听器恰好存在一份；
4. 结合 callback 引用稳定性、订阅 key 一致性、仅客户端适用等边界条件落地，并对照仓库内 Kbar 与 BookingDetailsSheet 等真实代码判断哪些监听器属于可收敛的重复注册、哪些应保持按实例直接注册。