Vue3的组合式API里，watch和watchEffect是两个经常被并列提及的响应式数据监测工具。它们都能在状态变化时触发副作用，但底层行为和适用场景存在本质区别。如果只是简单地把两者都当作数据变了就执行函数，很容易写出重复触发、依赖遗漏甚至内存泄漏的代码。本文会从依赖收集机制、执行时机、回调参数、实际场景与常见坑点几个维度展开，帮助你把这两个API彻底区分清楚。
一、依赖收集机制：watch显式指定，watchEffect自动追踪
Vue3的响应式系统基于Proxy实现，当组件渲染或副作用函数访问响应式数据时，会触发属性读取的track过程，把当前的副作用与这个属性建立依赖关系；属性变化时再触发trigger，通知对应的副作用重新执行。watch和watchEffect的本质差异，就体现在它们与这个依赖收集系统交互的方式上。
watch需要你显式传入一个或多个数据源。Vue在内部会遍历这些数据源，读取它们的值，从而手动建立数据源与回调之间的依赖关系。这意味着如果你传入了state.count，那么只有当state.count发生变化时回调才会执行；其他未被列入数据源的属性即使发生变化，watch也不会响应。这种精确性让watch非常适合追踪特定状态。
相比之下，watchEffect不需要你声明任何数据源。它会立即执行一次传入的回调函数，在执行过程中，凡是访问到的响应式属性都会被自动收集为依赖。这种机制很像计算属性的依赖收集方式，但它不需要返回值，而是专注于处理副作用。下面的代码展示了两种方式在依赖收集上的差异。
import { ref, reactive, watch, watchEffect } from 'vue';
const count = ref(0);
const name = ref('Vue');
// watch 只会追踪 count，name 改变时不会触发
watch(count, (newVal, oldVal) => {
console.log('count changed:', newVal, oldVal);
});
// watchEffect 执行时读取了 count.value 和 name.value，两个都会被追踪
watchEffect(() => {
console.log(`count: ${count.value}, name: ${name.value}`);
});
setTimeout(() => {
name.value = 'React'; // 只有 watchEffect 会再次执行
}, 500);
可以看到，watchEffect自动收集了count和name两个依赖，后续任何一方变化都会重新执行回调；而watch只对count敏感。这种差异决定了它们的使用倾向：当你要精确监控某个状态的变化时选watch，当你希望副作用自动跟随所有用到的状态时选watchEffect。
二、执行时机与回调参数：默认行为完全不同
执行时机是两者另一个关键差异。watch默认是惰性的，也就是说只有在被监听的数据源发生变化时才会执行回调。如果你希望在组件初始化时就先执行一次回调，需要手动配置immediate: true。而watchEffect在创建时会立即执行一次，这是它自动收集依赖的必要步骤，无法省略。
从回调参数来看，watch的回调函数接收newValue和oldValue两个参数，方便你比较变化前后的数据；如果监听的是数组或响应式对象，参数会是数组形式。而watchEffect的回调不接收任何参数，因为它的设计目标不是比较新旧值，而是执行副作用，比如请求数据、操作DOM、写日志等。
Vue3还为这两个API提供了flush选项，用来控制回调的执行时机。默认值都是pre，表示在组件更新前执行；post表示在组件更新后执行，适合操作更新后的DOM；sync表示同步执行，一般不推荐，容易造成多次不必要的触发。使用watchEffect时可以通过给回调传入一个onCleanup函数来清理上一次的副作用，而watch则没有这个内置机制，需要手动管理。
import { ref, watch, watchEffect } from 'vue';
const keyword = ref('');
// watch 默认不立即执行，需要 immediate
watch(keyword, async (newVal, oldVal) => {
console.log(`searching: ${newVal}`);
}, { immediate: true });
// watchEffect 立即执行，并且可以注册清理函数
watchEffect((onCleanup) => {
const timer = setTimeout(() => {
console.log('debounced search:', keyword.value);
}, 300);
onCleanup(() => clearTimeout(timer));
});
上面示例中，watchEffect每次重新执行前都会先运行onCleanup注册的清理函数，这样可以安全地清除上一次的定时器，避免输入过程中发起大量请求。watch则需要自己保存定时器ID，在下次执行前手动清理，复杂度略高。
三、实战场景与避坑指南：这样选型不会出错
在实际项目里，watch和watchEffect并非二选一的对立关系，而是互补工具。一般来说，当你需要监听某个特定数据源、获取新旧值、控制是否立即执行、或者对多个数据源做精确组合时，优先使用watch；当你写的副作用函数里天然会访问多个响应式状态、而且你并不关心具体哪个状态变了、也不需要新旧值对比时，watchEffect会让代码更简洁。
一个常见误区是在watchEffect内部无条件修改它所依赖的状态，这会导致无限循环。例如下面的代码会让程序进入死循环：
import { ref, watchEffect } from 'vue';
const count = ref(0);
watchEffect(() => {
count.value++; // 修改了 count，触发 watchEffect 再次执行，形成死循环
});
正确的做法是加入条件判断，或者使用watch配合明确的业务逻辑。另一个容易忽略的点是停止监听。在组件卸载时，Vue会自动清理组件内创建的watch和watchEffect，但如果你在全局作用域或者异步回调中创建它们，就需要手动调用返回的停止函数，否则会一直占用内存。示例：
import { ref, watch, watchEffect } from 'vue';
const count = ref(0);
const stopWatch = watch(count, (val) => {
console.log('watch:', val);
});
const stopEffect = watchEffect(() => {
console.log('effect:', count.value);
});
// 不再需要监听时手动停止
stopWatch();
stopEffect();
深度监听也是容易用错的地方。watch监听响应式对象时默认是浅层监听，只有对象引用变化才会触发；如果需要对对象内部属性变化做出响应，需要配置deep: true，但深度监听会递归遍历所有属性，大型对象上可能带来性能开销。watchEffect虽然会自动收集依赖，但如果你在回调里只读取了对象的某个属性，它只会追踪这个属性，而不是整个对象，这在性能上比watch的deep: true更有优势。
最后总结一下选型思路：需要精确控制、获取新旧值、处理多个数据源的组合变化时选watch；副作用函数本身就能自然地表达依赖关系、希望自动收集依赖并立即执行时选watchEffect。理解它们背后的响应式依赖收集机制，比记住API参数更重要。遇到不确定的情况，可以先问自己三个问题：我要不要拿到旧值？我是否必须立即执行一次？副作用依赖的状态是不是动态变化的？答案会帮你快速做出正确判断。
Vue3watchwatchEffect修改时间：2026-09-20 12:47:54