PostHog 前端 kea-disposables 使用指南定时器与事件监听的自动清理与后台自动暂停【免费下载链接】posthog:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.项目地址: https://gitcode.com/GitHub_Trending/po/posthog本篇技术指南以 PostHog 仓库内.agents/skills/using-kea-disposables/SKILL.md为核心讲解前端 kea 逻辑logic中资源清理的最佳实践。凡是你在 kea logic 里注册setInterval、setTimeout、window.addEventListener、MediaQueryList.addEventListener或任何需要显式销毁的订阅WebSocket、EventSource、ResizeObserver、IntersectionObserver 等都应通过全局注册的disposablesPlugin注入的cache.disposables来管理。读完本文你将掌握cache.disposables.add(...)/dispose(key)的完整用法、pauseOnPageHidden后台自动暂停机制、isDisposed的异步续期防护以及如何把代码库中现存的「裸cache.thingbeforeUnmount」反模式安全迁移过来。为什么需要 disposables取代裸cache存句柄 beforeUnmount清理PostHog 前端基于 kea 状态管理框架组织业务逻辑。在过去一个常见的写法是在afterMount里创建定时器把句柄塞进cache再在beforeUnmount里手动clearInterval。这种模式存在三个痛点清理代码重复每个逻辑都要写两段配套代码容易遗漏后台标签页空耗资源即使页面被隐藏轮询与动画定时器仍在运行白白消耗 CPU 与网络生命周期边界易错手动清理时机、条件判断if (cache.xxx)都容易写错。仓库通过一个本地 kea 插件解决了这些问题disposablesPlugin定义于 frontend/src/kea-disposables.ts类型为KeaPlugin通过events.afterMount与events.beforeUnmount挂钩逻辑生命周期并在 frontend/src/initKea.ts 中被全局注册plugins数组中的disposablesPlugin。因此仓库内每一个 kea logic 的cache上都有cache.disposables无需任何额外初始化。插件的行为可以概括为自动清理你在setup函数中返回的 cleanup 函数会在逻辑卸载unmount时自动执行后台自动暂停默认情况下页面隐藏时所有 disposables 的 cleanup 会被执行暂停页面重新可见时 setup 会重新运行恢复大幅降低后台标签页的 CPU 与网络开销安全执行setup 与 cleanup 中的异常都会被捕获并打印[KEA] Disposable setup/cleanup failed in logic path错误不会污染其他逻辑见 frontend/src/kea-disposables.ts 的safeCleanup/safeSetup。不要在清理场景中使用beforeUnmount。插件会在逻辑卸载时自动运行你在 setup 里返回的 cleanup并在标签页可见性变化时重新执行 setup/cleanup。如果你发现某个beforeUnmount的唯一职责就是clearInterval/clearTimeout/removeEventListener清理前面注册过的资源请把这些资源改由cache.disposables.add(...)注册并删除该beforeUnmount。beforeUnmount只应保留给「非自管资源」的收尾工作例如刷新状态、持久化到 localStorage、调用第三方库的dispose()。核心模式setup 返回 cleanupcache.disposables.add的签名与useEffect的 cleanup 模式极其相似——传入的 setup 立即执行且必须返回一个清理函数cache.disposables.add( setup, // () () void — 立即执行MUST return a cleanup function key?, // string — 以相同 key 重复添加会先销毁前一个 options?, // { pauseOnPageHidden?: boolean } — 默认 true隐藏时执行 cleanup可见时重新执行 setup )规范示例位于 frontend/src/layout/navigation/noEventsBannerLogic.ts一个无 key 的setInterval轮询器afterMount(({ actions, cache }) { cache.disposables.add(() { const pollTimer window.setInterval(() { actions.loadCurrentTeam() }, POLL_INTERVAL_MS) return () clearInterval(pollTimer) }) }),这段代码创建了一个每 30 秒POLL_INTERVAL_MS 30_000见 noEventsBannerLogic.ts轮询一次loadCurrentTeam的定时器并返回清理函数。插件会在逻辑卸载时调用clearInterval无需任何beforeUnmount。从底层实现看frontend/src/kea-disposables.tsadd做了几件关键的事未传 key 时自动生成__auto_n递增 keyoptions默认合并为{ pauseOnPageHidden: true }若传入 key 且该 key 已存在先safeCleanup旧的 entry 再注册新的这是「防抖替换」语义的实现基础若页面当前处于隐藏状态且该 disposable 未选择退出暂停则只注册 setup、不立即执行cleanup 置为 no-op等页面可见时再由resumeAllDisposables补跑 setup——这样即使在隐藏期间从异步回调里add()新的轮询也不会产生一个应当被暂停却活跃运行的定时器。何时选择 key不传 key——即「一次性发射fire-and-forget」只在逻辑卸载时清理。适用于在afterMount中注册的一次性监听器。传入命名 key——当出现以下需求时必须使用之后要调用cache.disposables.dispose(key)提前停止同一 setup 可能被重复添加每次调用都应替换前一个防抖/防重复场景。dispose的实现frontend/src/kea-disposables.ts会在注册表中查找 key找到则执行 cleanup 并从注册表删除返回true找不到或已卸载返回false。场景一hover 暂停/恢复的键控轮询frontend/src/lib/components/LiveUserCount/liveUserCountLogic.ts 展示了「hover 时启动、离开时销毁」的键控 interval以及暂停/恢复流的完整模式setIsHovering: ({ isHovering }) { if (isHovering) { actions.setNow(new Date()) cache.disposables.add(() { const intervalId setInterval(() actions.setNow(new Date()), 500) return () clearInterval(intervalId) }, nowInterval) } else { cache.disposables.dispose(nowInterval) } }, pauseStream: () { cache.disposables.dispose(statsInterval) }, resumeStream: () { actions.pollStats() cache.disposables.add(() { const intervalId setInterval(() actions.pollStats(), props.pollIntervalMs ?? 30000) return () clearInterval(intervalId) }, statsInterval) },注意这里add与dispose成对出现状态切换时用dispose(key)精确销毁某个资源而无需卸载整个逻辑。场景二setTimeout 防抖spam-replacement用户连续触发showSeekIndicator时旧定时器必须被替换而非叠加。frontend/src/scenes/session-recordings/player/sessionRecordingPlayerLogic.ts 利用「同 key 先销毁旧 entry」的特性实现了 600ms 的防抖隐藏showSeekIndicator: () { // Same key auto-disposes the previous timer when spamming cache.disposables.add(() { const timerId setTimeout(() { actions.hideSeekIndicator() }, 600) return () clearTimeout(timerId) }, seekIndicatorTimer) },场景三一个afterMount内注册多个 keyed 窗口监听器frontend/src/toolbar/bar/toolbarLogic.ts 在挂载时一次性注册多个全局监听器每个都有自己的 keycache.disposables.add(() { const clickListener (e: MouseEvent): void { /* ... */ } window.addEventListener(mousedown, clickListener) return () window.removeEventListener(mousedown, clickListener) }, clickListener) // popstate only fires on user-initiated back/forward, so a hidden tab wont // generate events — pausing on hide (the default) is fine here. Opt out // only if you must observe popstates while the tab is in the background. cache.disposables.add(() { const popstateHandler (): void actions.maybeSendNavigationMessage() window.addEventListener(popstate, popstateHandler) return () window.removeEventListener(popstate, popstateHandler) }, popstateListener)场景四events(afterMount)中的 MediaQueryList 监听kea 的events构建器同样可用frontend/src/layout/navigation-3000/themeLogic.ts该文件是lib/logic/themeLogic的 re-export实际逻辑实现位于frontend/src/lib/logic/themeLogic.ts中的暗色模式监听如下events(({ cache, actions }) ({ afterMount() { cache.disposables.add(() { const prefersColorSchemeMedia window.matchMedia((prefers-color-scheme: dark)) const onPrefersColorSchemeChange (e: MediaQueryListEvent): void actions.syncDarkModePreference(e.matches) prefersColorSchemeMedia.addEventListener(change, onPrefersColorSchemeChange) return () prefersColorSchemeMedia.removeEventListener(change, onPrefersColorSchemeChange) }, prefersColorSchemeListener) }, })),pauseOnPageHidden后台标签页自动暂停默认值true适用于几乎一切场景——轮询、动画 ticker、hover 定时器。页面隐藏时这些资源会被暂停恢复可见时重新执行 setup从而大幅降低后台标签页的 CPU 与网络消耗。底层实现由 frontend/src/kea-disposables.ts 的pauseAllDisposables/resumeAllDisposables完成全局维护一个allManagers集合页面visibilitychange到hidden时对所有pauseOnPageHidden ! false的 entry 执行 cleanup回到可见时对它们重新执行 setup 并更新 cleanup 引用若 setup 失败则替换为 no-op cleanup防止执行过期的旧 cleanup。全局监听器是惰性挂载的——第一个 manager 注册时attachGlobalVisibilityListener最后一个 manager 卸载时detachGlobalVisibilityListener见 frontend/src/kea-disposables.ts。仅在监听器必须于页面隐藏时持续触发时才退出暂停传{ pauseOnPageHidden: false }监听可能真实发生在隐藏标签页中的事件storage来自其他标签页的写入、online/offline、message来自 web worker、service worker 或其他 windowvisibilitychange监听器本身——它的意义就是观察隐藏/显示任何用户期望在隐藏时继续运行的功能。一个反直觉但正确的判断popstate只能由用户操作触发隐藏标签页不会产生事件所以默认的隐藏时暂停对它毫无影响见上方 toolbar 示例中的注释。pauseOnPageHidden: false的典型场景是visibilitychange监听器本身frontend/src/scenes/product-tours/productTourLogic.ts 中的工具栏模态框可见性处理openToolbarModal: () { cache.disposables.add( () { const handler (): void { if (document.visibilityState hidden) { actions.handleToolbarTabVisibility() } } document.addEventListener(visibilitychange, handler) return () document.removeEventListener(visibilitychange, handler) }, toolbarModalVisibility, { pauseOnPageHidden: false } ) }, closeToolbarModal: () { cache.disposables.dispose(toolbarModalVisibility) },提前停止dispose(key)的适用场景cache.disposables.dispose(key)在不卸载逻辑的前提下拆毁某一个具体资源。适合的状态迁移场景包括暂停/恢复轮询器如liveUserCountLogic的pauseStream/resumeStream鼠标移出时停止 hover 专属 ticker关闭模态框时销毁其作用域内的监听器如上面closeToolbarModal的做法。卸载之后的调用add/dispose是安全的isDisposed用于异步续期逻辑卸载后add()与dispose()会成为no-op因此可以放心地直接调用不要写cache.disposables?.dispose(...)或if (!cache.disposables) return——manager 在挂载后永不为空。但一个异步续期通常需要跳过的远不止 disposable 本身对已拆毁逻辑派发 action 或读取values是另一类 bug。此时应分支判断cache.disposables.isDisposed// The stream teardown aborts this request, so the catch can resume after the unmount if (cache.disposables.isDisposed) { return } actions.connectionErrored(reason)isDisposed在逻辑开始最终卸载时被置为true且先于所有注册的 cleanup 执行——这样 cleanup 唤醒的异步续期例如被中止的请求在finally中恢复会看到一个惰性 manager而不会在即将消亡的逻辑上重新注册资源。这一点在finally中最关键卸载中止的请求会 rejectfinally随后会对着一个已不存在的逻辑执行。底层行为frontend/src/kea-disposables.tsbeforeUnmount中只有当!typedLogic.isMounted()且 manager 尚未 disposed 时才执行完整清理——先把 manager 从全局可见性跟踪中移除、置isDisposed true、遍历 registry 执行所有 cleanup 并清空最后按需摘除全局 visibilitychange 监听。manager 本身保留在 cache 上而非置空因为比卸载更长寿的异步代码仍会触达cache.disposables.dispose(...)若此处为 null 会在续期代码里抛出 TypeError而不是安静地什么都不做。重新挂载的陷阱同一逻辑再次挂载时cache 上会放一个全新的 manager。于是上一世遗留的异步续期可能触达cache.disposables并发现一个存活的 manager此时isDisposed读到false若续期里 dispose 了共享 key会拆毁新一世的资源。因此当续期需要的关键数据务必在逻辑存活时捕获如 frontend/src/scenes/notebooks/Notebook/notebookKernelInfoLogic.ts 在afterMount里把getContext()的结果捕获到闭包外层。不要只用isDisposed守卫定时器回调如果定时器回调还要读取values仅用isDisposed守卫是不够的该标志只在真正卸载时翻转而替换 kea contextStorybook 每次挂载 story 都会做会把逻辑从 store 中丢弃但不会触发卸载于是 cleanup 永不执行。正确做法是拿getContext()与资源创建时所在的 context 做比较。notebookKernelInfoLogic.ts的实现即为范本const mountedIn getContext() const isLive (): boolean getContext() mountedIn注意这里把getContext()捕获在 setup 闭包之外而非 setup 内部——因为插件在模块级持有每个 manager页面可见时会重跑 setup若在 setup 内读 context重跑时的 context 与自身恒等起不到守卫作用。回调中if (!isLive()) return即可安全跳过已脱离 store 的逻辑。反模式迁移把裸cachebeforeUnmount转换为 disposables「裸cache.thingbeforeUnmount清理」正是本插件要取代的模式遇到即可转换。Beforefrontend/src/lib/components/HedgehogMode/hedgehogModeLogic.tsafterMount(({ actions, cache }) { cache.syncInterval setInterval(() actions.syncFromState(), 1000) }), beforeUnmount(({ cache }) { if (cache.syncInterval) { clearInterval(cache.syncInterval) cache.syncInterval null } }),After——beforeUnmount整块消失改由 setup 返回的 cleanup 承担卸载清理afterMount(({ actions, cache }) { cache.disposables.add(() { const id setInterval(() actions.syncFromState(), 1000) return () clearInterval(id) }, syncInterval) }),仓库中还有两个已知的开放转换目标frontend/src/scenes/welcome/welcomeDialogLogic.ts约 L325-L345——手动把window.addEventListener(storage, ...)的 handler 塞进cache.storageHandler可迁移为 keyed disposableproducts/signals/frontend/inbox/inboxSceneLogic.ts约 L260-L267——裸setInterval在每次状态变更时手动清除可迁移为同 key 自动替换或显式dispose(key)。迁移要点回顾转换后逻辑不再需要手写beforeUnmount清理自管资源add的 key 让「重复注册自动替换」与「提前销毁」开箱即用默认开启的后台暂停还会顺带消灭隐藏标签页的空转开销。小结何时用 disposables何时保留 beforeUnmount场景做法setInterval/setTimeoutafterMount、listener、subscription 内cache.disposables.add(setup, key?, options?)window/document/MediaQueryList.addEventListenercache.disposables.add(...)返回对应removeEventListenercleanup需要显式销毁的订阅WebSocket、EventSource、ResizeObserver、IntersectionObserver 等cache.disposables.add(...)状态变化需提前结束已注册资源cache.disposables.dispose(key)页面隐藏时仍需运行的监听storage、online/offline、message、visibilitychange自身等cache.disposables.add(setup, key, { pauseOnPageHidden: false })异步续期finally等在卸载后要继续执行先判cache.disposables.isDisposed跳过对已拆毁逻辑的 action/values 访问非自管资源的收尾flush 状态、localStorage 持久化、第三方dispose()保留在beforeUnmount这套机制贯穿 PostHog 前端大量场景——顶部导航轮询noEventsBannerLogic、实时人数LiveUserCount、录制播放器防抖sessionRecordingPlayerLogic、工具栏全局监听toolbarLogic、产品引导弹窗productTourLogic与暗色模式themeLogic。在新增任何需要销毁的资源时优先查阅这些示例文件并遵循同一模式即可保证内存安全、后台省电且逻辑可读。【免费下载链接】posthog:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.项目地址: https://gitcode.com/GitHub_Trending/po/posthog创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
