Vue3 onWatcherCleanup注册侦听器清理回调

在 Vue 3.5+ 版本中，处理侦听器（Watcher）内部的副作用清理变得更加直观和安全。过去，我们需要在 watch 或 watchEffect 的回调函数中手动返回一个清理函数，或者依赖 onUnmounted 钩子。这种方式在处理异步操作（如网络请求）或复杂逻辑时，往往会导致代码嵌套过深，甚至因为闭包问题引发内存泄漏或竞态条件。

onWatcherCleanup 函数允许我们在侦听器作用域内直接注册清理回调，确保在下一次侦听器执行或组件卸载时自动执行清理。以下是具体的操作步骤与实战指南。

场景一：解决异步请求的竞态条件

当用户快速切换输入框内容或切换 Tab 页时，前一个请求可能尚未完成，后一个请求已经发出。这会导致“先发后至”的问题，即旧的数据覆盖了新的数据。使用 onWatcherCleanup 可以强制取消未完成的请求。

1. 创建一个新的 Vue 组件文件 UserSearch.vue。
2. 引入 watch, ref 和 onWatcherCleanup。
3. 定义一个响应式变量 searchId 用于模拟查询条件。

import { watch, ref, onWatcherCleanup } from 'vue';

const searchId = ref(1);

4. 编写 watch 侦听器来监听 searchId 的变化。
5. 在侦听器内部，使用 AbortController 创建一个控制器实例。
6. 调用 onWatcherCleanup 并传入一个回调函数，在回调中执行控制器的 abort() 方法。

watch(searchId, async (newId) => {
  // 1. 创建控制器
  const controller = new AbortController();
  const signal = controller.signal;

  // 2. 注册清理函数：当 searchId 变化或组件卸载时触发
  onWatcherCleanup(() => {
    controller.abort();
  });

  try {
    // 3. 发起请求，携带 signal
    console.log(`正在请求 ID: ${newId}...`);
    // 模拟网络请求延迟
    await new Promise(resolve => setTimeout(resolve, 1000));
    
    // 如果请求被中止，抛出错误或直接返回
    if (signal.aborted) return;

    console.log(`收到 ID: ${newId} 的数据`);
  } catch (error) {
    if (error.name === 'AbortError') {
      console.log(`ID: ${newId} 请求已取消`);
    } else {
      console.error(error);
    }
  }
});
```

7.  **修改** `searchId` 的值（例如通过按钮点击 `searchId.value++`）。
8.  **观察**控制台输出。如果在 1 秒内多次点击，你会看到 `请求已取消` 的日志，只有最后一次请求会成功输出数据。这证明旧的请求被正确清理了。

---

### 场景二：管理定时器与事件监听

在 `watchEffect` 中使用定时器或事件监听器时，如果不清理，会导致内存泄漏（定时器叠加运行或监听器重复绑定）。

1.  **定义**一个响应式变量 `source`。
2.  **使用** `watchEffect` 自动追踪依赖。
3.  在副作用内部，**设置**一个 `setInterval` 定时器，每秒打印一次日志。
4.  立即**调用** `onWatcherCleanup`，在回调中**清除**该定时器。

```javascript
import { watchEffect, ref, onWatcherCleanup } from 'vue';

const source = ref(10);

watchEffect((onCleanup) => {
  // 注意：Vue 3.5+ 推荐直接使用 onWatcherCleanup，不再依赖 onCleanup 参数
  
  const timer = setInterval(() => {
    console.log(`当前计数值: ${source.value}`);
  }, 1000);

  // 注册清理逻辑
  onWatcherCleanup(() => {
    clearInterval(timer);
    console.log('定时器已清理');
  });
});

5. 修改 source.value 的值。
6. 观察控制台。每次 source 变化导致 watchEffect 重新执行前，定时器已清理 都会先打印出来，确保了同一时刻只有一个定时器在运行。

核心机制对比

为了更清晰地理解 onWatcherCleanup 的优势，我们需要对比传统的清理方式。

执行流程解析

当我们在侦听器中注册了清理回调后，Vue 的内部执行逻辑如下。理解这个流程有助于你编写更健壮的代码。

关键步骤说明：

1. 注册阶段：当代码运行到 onWatcherCleanup(fn) 时，Vue 并不会立即执行 fn，而是将其暂存起来，与当前的侦听器实例绑定。
2. 触发清理：一旦侦听器所依赖的响应式数据发生变化，Vue 会先调用上一次暂存的清理函数 fn，然后再重新运行侦听器。
3. 卸载清理：如果组件被卸载，Vue 也会自动触发剩余的清理函数，防止内存泄漏。

常见错误与修正

在使用 onWatcherCleanup 时，有几个常见的陷阱需要避开。

错误 1：在侦听器外部调用

// ❌ 错误示范
onWatcherCleanup(() => {
  console.log('这不会在 watch 重新运行时生效');
});

watch(id, () => {
  // ...
});

修正：确保 onWatcherCleanup 只在 watch 或 watchEffect 的回调函数作用域内调用。

错误 2：条件性注册导致清理失效

// ❌ 危险示范
watch(id, () => {
  if (id.value > 0) {
    onWatcherCleanup(() => {
      // 只有当 id > 0 时才会注册清理函数
      // 如果下一次 id 变为 -1，清理逻辑不会执行，但上次的副作用可能还在
    });
  }
});

修正：通常建议将清理逻辑的注册放在不依赖条件的顶层，或者确保清理逻辑与副作用逻辑成对出现。

错误 3：混淆 onUnmounted

// ❌ 不推荐混合使用
import { onUnmounted } from 'vue';

watch(id, () => {
  const timer = setInterval(...);

  // 如果只是为了清理 watch 相关的副作用，不要用 onUnmounted
  // 因为 watch 可能会在组件生命周期内多次执行，而 onUnmounted 只执行一次
  onUnmounted(() => clearInterval(timer)); 
});

修正：对于侦听器内部产生的副作用，坚持使用 onWatcherCleanup，它能精确匹配每次副作用的生命周期。

通过以上步骤和规范，你可以在 Vue 3 项目中高效、安全地管理侦听器的副作用，彻底告别内存泄漏和竞态条件带来的困扰。