从 tryOnBeforeUnmount 理解 VueUse 安全生命周期钩子：让组件卸载清理在非组件上下文也能从容执行

tryOnBeforeUnmount 是 VueUse 提供的 onBeforeUnmount 安全版本：只有代码运行在组件生命周期内部时才会真正注册回调，否则静默跳过而不抛错。本文以 tryOnBeforeUnmount.md 为骨架，结合本仓库（airi，一个基于 Vue 3 的桌面/Web 多端 AI 桌面伙伴项目）中真实组件的卸载清理写法，讲解该工具的用法、类型语义、适用边界与配套 API，帮助你写出既能在组件内正确回收资源、又不会在纯函数或模块级作用域中"炸掉"的通用 composable。

先看原文档说了什么

该参考文档虽然短小，但给出了三个关键信息，构成理解 tryOnBeforeUnmount 的完整起点：

1. 定位：category: Component，属于 VueUse 的组件生命周期工具族，在 SKILL.md 的 Component 分类下被描述为 "Safe onBeforeUnmount"。
2. 行为定义：Safe onBeforeUnmount。Call onBeforeUnmount() if it's inside a component lifecycle, if not, do nothing——即"若处于组件生命周期内则调用 onBeforeUnmount()，否则什么都不做"。
3. 签名与用法：入参为回调函数 fn，可选的第二参数 target 用于显式指定目标组件实例，用法与普通生命周期注册几乎无差别。

这一"安全（Safe）"前缀是该工具的设计灵魂，也是它与 Vue 原生 onBeforeUnmount 的根本区别。

为什么需要"安全的" onBeforeUnmount：Vue 的报错前提

Vue 3 的 setup() 机制决定了生命周期钩子（onMounted、onBeforeUnmount、onUnmounted 等）必须在组件实例活跃期间被调用，即只能在以下上下文使用：

• 组件的 setup() 内部；
• 在 setup 期间被同步调用的 composable 内部。

如果脱离该上下文调用，Vue 会直接抛出运行时错误：onBeforeUnmount is called when there is no active component instance to be associated with.，并提示你应将生命周期钩子放到组件的 setup() 顶层或某个 composable 内部。

真实项目中的对照：本仓库如何做卸载清理

在本仓库中，存在大量"进入组件后建立资源、卸载前回收资源"的典型代码，它们使用的是 Vue 原生 onBeforeUnmount，例如：

• use-iframe-message-port.ts：渲染层组件为插件扩展 iframe 建立 Eventa 类型的消息上下文后，在 onBeforeUnmount 中调用 iframeRuntime.dispose() 释放 postMessage 监听与上下文资源；
• use-element-scroll.ts：聊天场景滚动 composable 在卸载时回收元素滚动相关的副作用；
• screen-capture.vue：开发者工具页在 onBeforeUnmount 中停止屏幕捕获相关任务。

这些写法的前提是"调用方一定位于组件上下文"。一旦这类 composable 需要被复用到非组件场景（例如定时任务、事件总线处理器、createSharedComposable 包装的跨组件共享状态，甚至测试环境），onBeforeUnmount 就会因没有活跃组件实例而抛错。

tryOnBeforeUnmount 正是为抹平这种差异而生：它将"是否有组件实例"的守卫内置，让同一个 composable 无论在组件内还是组件外调用都保持安全。

用法：与 onBeforeUnmount 几乎一致

import { tryOnBeforeUnmount } from '@vueuse/core'

tryOnBeforeUnmount(() => {
  // 组件卸载前执行的清理逻辑
})

回调中可以放置任何需要在组件卸载前同步完成的清理动作——移除全局事件监听、销毁 WebSocket 连接、clearInterval 定时器、释放子资源等。

一个更贴近本仓库场景的例子：把上文的 iframe 消息上下文清理改写成"可安全复用"的版本：

import { tryOnBeforeUnmount } from '@vueuse/core'

export function useIframeRuntime(target: MaybeElementRef) {
  const runtime = createContext({ /* ... */ })

  // 组件内调用 → 正常注册；组件外调用 → 静默跳过
  tryOnBeforeUnmount(() => {
    runtime.dispose()
  })

  return runtime
}

类型声明逐项解读

原文档给出了完整类型声明：

/**
 * Call onBeforeUnmount() if it's inside a component lifecycle, if not, do nothing
 *
 * @param fn
 * @param target
 */
export declare function tryOnBeforeUnmount(
  fn: Fn,
  target?: ComponentInternalInstance | null,
): void

逐项拆解其语义：

成员	类型	含义
fn	Fn	必填。卸载前要执行的回调函数。Fn 是 VueUse 约定的无参函数类型，一般等价于 () => void
target	ComponentInternalInstance | null	可选。显式指定要关联的组件内部实例。缺省（undefined）时由 VueUse 在内部使用当前的活跃组件实例；传入 null 或 undefined 都表示"跟随当前上下文"。ComponentInternalInstance 是 Vue 3 导出的组件内部实例类型，可通过 getCurrentInstance() 获得
返回值	void	无返回值

关键行为可归纳为一句判断：

• 调用时机处于组件生命周期内（存在活跃组件实例）→ 与直接调用 onBeforeUnmount(fn, target) 等价，回调会在此组件卸载前被执行；
• 调用时机处于组件生命周期之外（无活跃组件实例）→ 函数什么都不做，不注册任何回调，也不抛任何错误。

需要说明的是，在组件卸载时真正触发回调的语义与 Vue 原生 onBeforeUnmount 完全一致——它是 Vue 生命周期中最靠后的卸载前同步钩子，适合做最后的、必须同步完成的收尾（异步清理可考虑 onUnmounted）。

为什么默认"静默跳过"是有意设计

对不熟悉该 API 的开发者，"outside 就什么都不做"看起来像一个隐患：万一清理逻辑没执行导致内存泄漏怎么办？但实际上这是刻意取舍：

1. 保证不破坏调用方。非组件上下文（如工具函数、外部事件回调、定时器、测试）本来就不存在组件卸载事件，此时抛错没有意义，只会让共享 composable 无法被复用。
2. 泄漏责任仍归属调用方。如果你的清理逻辑在组件外也"必须"执行（例如模块级单例、window 级监听），那么正确的做法是不依赖组件生命周期，改用 tryOnScopeDispose（跟随 effect scope）或显式的手动清理函数，而不是指望 tryOnBeforeUnmount 兜底。
3. 语义聚焦。它解决的是"在可复用 composable 中安全地、有则注册、无则跳过"这一特定问题，是 VueUse 组件生命周期工具的通用设计模式。

这一点在本仓库的分层结构中格外有价值：airi 的 renderer 层存在大量"可被组件、也可被普通模块调用"的 composable 与 hooks（如 stage-ui、stage-tamagotchi 的 composables 目录），引入 VueUse 的 Safe 系列后，这些共享逻辑无需为"我到底是不是在组件里"编写额外判断。

配套的 Safe 家族与兄弟工具

tryOnBeforeUnmount 并非孤例，VueUse 在 Component 分类下提供了一整套同构工具（参见 SKILL.md 的 Component 小节）：

API	安全包装的原生钩子	语义
tryOnBeforeMount	onBeforeMount	组件挂载前执行，无活跃实例则跳过
tryOnMounted	onMounted	组件挂载后执行，无活跃实例则跳过
tryOnBeforeUnmount	onBeforeUnmount	组件卸载前执行，无活跃实例则跳过
tryOnUnmounted	onUnmounted	组件卸载后执行，无活跃实例则跳过
tryOnScopeDispose	onScopeDispose	当前 effect scope 销毁时执行，无 scope 则跳过

选择建议：

• 清理目标是普通监听/订阅/定时器：使用 tryOnBeforeUnmount，在组件真正卸载前同步回收；
• 清理逻辑涉及异步或对已卸载 DOM 的访问，希望延迟到最后：使用 tryOnUnmounted；
• 想要跟随的不是组件而是更通用的 effect scope（如 effectScope() 手动创建的作用域）：使用 tryOnScopeDispose；
• 与 createSharedComposable（见 createSharedComposable.md）配合时，Safe 系列能让共享 composable 在被多个组件复用时各自安全地注册/跳过生命周期清理。

实战建议与注意事项

结合原文档与本仓库写法，给出落地建议：

1. 优先考虑调用上下文。若 composable 明确只服务组件（如本仓库 use-iframe-message-port.ts 这类被组件专用的模块），继续使用 Vue 原生 onBeforeUnmount 反而能借助"必须处于 setup"的约束提前发现误用；只有当你希望 composable 具备"组件内外通吃"的复用能力时，才切换到 tryOnBeforeUnmount。

2. 不要用它掩盖架构问题。如果一个函数必须在销毁时执行清理，而它确实没有组件实例，那么问题在于资源归属设计，而不是钩子选型。此时应在函数外部显式调用清理，或在模块内部用 tryOnScopeDispose 管理作用域。

3. 回调保持同步、轻量。onBeforeUnmount 阶段不允许等待异步操作，因此放进 tryOnBeforeUnmount 的 fn 也应保持同步、快速、幂等，避免在卸载路径上引入昂贵的计算。

4. 与 getCurrentInstance() 心智对齐。target 参数的存在意味着你可以在"组件 A 的 setup 中、为组件 B 的实例注册清理"这类特殊场景下手动指定实例；日常开发中留空即可，VueUse 会自动取当前活跃实例。

小结

tryOnBeforeUnmount 用一行内置守卫，把 Vue 原生生命周期钩子"必须在组件上下文内调用"的约束，转化为"在组件内则正常注册、在组件外则安全跳过"的宽容语义。它适合出现在一切"可能被组件、也可能被非组件代码复用"的 composable 中，与 tryOnBeforeMount、tryOnUnmounted、tryOnScopeDispose 共同构成 VueUse 的 Safe 生命周期家族。当你在本仓库的 stage 系列应用中编写共享清理逻辑时，先问一句"这段代码是否永远只在组件里跑"——若答案不确定，就用 tryOnBeforeUnmount 让清理代码无论身在何处都从容执行。