Vue watchEffect 异步副作用的清理时机

我在把搜索参数接入 Vue 的异步请求时，最容易遇到的不是请求发不出去，而是旧请求回来后覆盖了新结果。watchEffect 的清理回调正是处理这个边界的入口：当 effect 因依赖变化即将重新运行时，先清理上一轮副作用；当组件不再需要它时，再通过停止句柄结束整个 watcher。

官方地址：https://vuejs.org/

异步副作用要在创建资源后、第一次 await 之前注册清理。兼容写法使用 watchEffect((onCleanup) => {}) 的参数；Vue 3.5+ 也可使用 onWatcherCleanup()，但它同样要求在 watcher 的同步执行阶段调用。

watchEffect 的清理到底在什么时候发生

watchEffect 会立即执行一次，并追踪回调同步阶段读取到的响应式依赖。依赖变化时，effect 会再次运行；上一轮注册的清理函数会在下一次 effect 重跑前调用。这个时机不是“Promise 完成后”，也不是“每次赋值后”，所以清理逻辑应该释放上一轮创建的请求、定时器或订阅。

import { ref, watchEffect } from 'vue'

const keyword = ref('')
const result = ref(null)

const stop = watchEffect((onCleanup) => {
  const controller = new AbortController()
  // 本轮 effect 失效前取消上一轮请求，避免旧响应继续占用资源。
  onCleanup(() => controller.abort())

  fetch(`/api/search?q=${encodeURIComponent(keyword.value)}`, {
    signal: controller.signal
  })
    .then((response) => response.json())
    .then((data) => {
      // 被取消的请求不会走到这里；有效请求才写入当前结果。
      result.value = data
    })
    .catch((error) => {
      // AbortError 是主动清理，不应被当成页面故障提示。
      if (error.name !== 'AbortError') console.error(error)
    })
})

// 在不再需要这组响应式副作用时调用 stop()。
// 组件 setup 中创建的 watcher 通常会随组件卸载自动停止。
void stop

示例里的 stop 是可调用的停止句柄。若 watcher 在组件的 setup() 同步阶段创建，Vue 通常会把它和组件生命周期绑定；如果是在异步回调中晚创建，就不要假设它一定会自动停止，应保存句柄并主动释放。

onCleanup 与 onWatcherCleanup 的注册位置

函数参数形式的 onCleanup 是最稳妥的兼容写法：它作为 watchEffect 回调的第一个参数传入，创建资源后立即注册。Vue 3.5+ 的 onWatcherCleanup 让注册方式更接近普通组合式 API，但调用必须发生在同步执行阶段，不能先 await 再补登记。

import { onWatcherCleanup, ref, watchEffect } from 'vue'

const userId = ref('42')
const profile = ref(null)

watchEffect(async () => {
  const controller = new AbortController()
  // 清理必须放在第一次 await 之前，确保当前 watcher 能接管它。
  onWatcherCleanup(() => controller.abort())

  const response = await fetch(`/api/users/${userId.value}`, {
    signal: controller.signal
  })
  // await 后只处理结果，不在这里首次注册清理。
  profile.value = await response.json()
})

如果项目还要兼容没有 onWatcherCleanup 的 Vue 版本，优先保留前一种参数写法。两种 API 的共同点是“注册与资源创建相邻”，共同限制是不要把清理注册放在异步暂停之后。

让失效请求无法写回新状态

取消请求可以减少资源浪费，但业务代码仍要把失效响应视为不可写回的结果。最小做法是让 AbortController 与清理函数绑定，并在捕获 AbortError 时直接结束当前分支。错误提示、加载状态和数据赋值都要避免把主动取消误报成失败。

watchEffect((onCleanup) => {
  const controller = new AbortController()
  let valid = true
  // 同时保留取消资源和失效标记，覆盖不支持取消的异步工作。
  onCleanup(() => {
    valid = false
    controller.abort()
  })

  loadSummary({ signal: controller.signal })
    .then((summary) => {
      // 即使底层任务无法立即取消，失效结果也不能写入当前 ref。
      if (valid) summaryRef.value = summary
    })
    .catch((error) => {
      if (error.name !== 'AbortError' && valid) errorRef.value = error
    })
})

这个双保险适合封装层没有完整支持 AbortSignal 的情况。清理函数负责让资源尽快停止，valid 负责阻断已经排队、但尚未真正结束的回调。它们解决的是不同层面的边界，不应只依赖其中一个。

清理不生效时先查这四个边界

1. 依赖是否在 await 前读取：watchEffect 的异步回调只追踪第一次 await 前访问的响应式属性；把关键依赖放到 await 后，可能根本不会触发重跑。
2. 清理是否先注册：资源创建后立即调用 onCleanup 或 onWatcherCleanup，不要等请求返回才登记。
3. 取消是否被误报：捕获到 AbortError 时通常意味着 watcher 已失效，不要把它写成当前页面的失败状态。
4. watcher 是否晚于生命周期创建：异步创建的 watcher 可能不再自动绑定组件，必须保存停止句柄并在合适的销毁路径调用。

排查时先记录“哪一个依赖变化导致重跑、清理函数是否被调用、回调是否仍尝试写状态”，再决定是依赖追踪问题还是异步资源没有正确接管。图示只解释 API 关系，不代表实际请求一定按图返回。

相关问题

onWatcherCleanup 能在 await 后调用吗？
不能。Vue 官方说明它只能在 watcher 回调的同步执行阶段调用；需要更宽松绑定时使用回调参数提供的 onCleanup。

清理函数会在每次 Promise 完成后执行吗？
不会。它与 watcher 的失效和停止相关，重点时机是下一次 effect 重跑前，以及 watcher 停止或所属组件卸载时。

只调用 controller.abort() 就够了吗？
不一定。底层任务可能不完全支持取消，仍应通过失效标记或等价条件阻止旧回调写入当前状态。

参考资料：https://vuejs.org/api/reactivity-core、https://vuejs.org/guide/essentials/watchers。