onWatcherCleanup() 注册侦听器清理回调
最后更新：2026-10-22
onWatcherCleanup() 注册侦听器清理回调
onWatcherCleanup() 注册清理函数：侦听器失效（重新执行或停止）前调用，用于取消请求、定时器等。
| 分组 | 响应式·核心 |
|---|---|
| 类型 | API |
| 作用域 | 组件内 |
| Vue 版本 | 3.5+ |
| SSR 支持 | 支持 |
📝 语法
watch(keyword, async () => {
const controller = new AbortController()
onWatcherCleanup(() => controller.abort())
const res = await fetch(url, { signal: controller.signal })
})⚙️ 参数
| cleanupFn | 清理函数，在侦听器失效前执行 |
|---|
返回值：无（在侦听器回调内调用）
▶ 示例
修改下面的代码，在预览区实时查看效果：
输出：
快速连打时，只有最后一次停顿 600ms 后显示结果——中间的结果都被取消了。💡 要点
⚠️ 注意 只能在侦听器回调同步执行阶段调用：await 之后调用会报错，需提前注册。
💡 提示 watch 回调的第三个参数 onCleanup 与本函数等价，两种写法都常见。
ℹ️ 说明 典型场景：搜索防抖、竞态请求取消、WebSocket 重连清理。
🏷️ 相关核心
💡 相关案例
更多案例即将上线。
📚 相关教程
❓ 常见问题
Q 不清理会怎样？
A 旧请求/定时器仍在跑：慢的旧响应可能后到并覆盖新结果，即典型竞态。
Q 和 onUnmounted 有什么区别？
A onWatcherCleanup 每次侦听器重新执行前都清理；onUnmounted 只在组件卸载时执行一次。
Q 能在 watchEffect 里用吗？
A 可以，watchEffect 同样支持（其回调也可接收 onCleanup 参数）。
