Vue 3 Watch 监视完全指南一、watch 基础概念watch用于侦听响应式数据源的变化并在变化时执行副作用函数。它默认是惰性的不会立即执行且能获取新值和旧值。基本语法watch(source,callback,options)source侦听源ref、reactive、getter 函数、数组callback(newVal, oldVal, onCleanup) {}options配置项immediate、deep、flush、once 等二、侦听不同数据源1. 侦听 refscript setup import { ref, watch } from vue const count ref(0) watch(count, (newVal, oldVal) { console.log(count: ${oldVal} - ${newVal}) }) count.value // 输出: count: 0 - 1 /script2. 侦听 reactive 对象⚠️注意侦听 reactive 对象时必须使用 getter 函数否则会隐式创建深度侦听且新值等于旧值。import{reactive,watch}fromvueconststatereactive({name:Tom,age:18})// ❌ 错误直接传 reactive新旧值相同watch(state,(newVal,oldVal){console.log(newValoldVal)// true因为都是同一个代理对象})// ✅ 正确使用 getterwatch(()state.name,(newVal,oldVal){console.log(name:${oldVal}-${newVal})})// ✅ 侦听整个 reactive 需要 deepwatch(()state,(newVal)console.log(newVal),{deep:true})3. 侦听 getter 函数constuserreactive({first:张,last:三})// 侦听组合值watch(()user.firstuser.last,(newVal,oldVal){console.log(全名:${oldVal}-${newVal})})4. 侦听多个源数组constaref(1)constbref(2)watch([a,b],([newA,newB],[oldA,oldB]){console.log(a:${oldA}-${newA}, b:${oldB}-${newB})})// 混合写法watch([a,()b.value*2],([newA,newDoubleB]){console.log(newA,newDoubleB)})三、核心配置项 options1.immediate—— 立即执行constidref(1)watch(id,(newVal){console.log(立即执行一次:,newVal)// 首次运行就输出 1},{immediate:true})常用于组件初始化时根据 props 拉取数据。2.deep—— 深度侦听constobjref({nested:{count:0}})// ❌ 不加 deep修改嵌套属性不会触发watch(obj,()console.log(触发))obj.value.nested.count// 不会触发// ✅ 加 deepwatch(obj,()console.log(触发),{deep:true})obj.value.nested.count// 触发reactive 对象的特殊情况直接侦听 reactive 对象时Vue 会自动启用 deepconststatereactive({nested:{count:0}})watch(state,(){console.log(自动深度侦听)})state.nested.count// 触发性能优化使用 getter 精确侦听避免 deep 全量遍历。// ✅ 只侦听特定属性性能更好watch(()obj.value.nested.count,(){})3.flush—— 回调执行时机值说明pre默认组件更新前执行post组件更新后执行sync同步执行变化立即触发watch(source,cb,{flush:post})// 可访问更新后的 DOMwatch(source,cb,{flush:sync})// 谨慎使用性能开销大4.once—— 只执行一次Vue 3.4watch(source,(newVal){console.log(只执行一次)// 变化后只触发一次},{once:true})5.onCleanup—— 清理副作用用于取消上一次的异步请求、定时器等防止竞态问题。watch(id,async(newId,oldId,onCleanup){constcontrollernewAbortController()onCleanup(()controller.abort())// 下次触发前先取消上次请求constresawaitfetch(/api/user/${newId},{signal:controller.signal})constdataawaitres.json()console.log(data)})四、停止侦听watch返回一个停止函数调用它可手动停止侦听。conststopwatch(count,(){console.log(count 变化了)})count.value// 触发stop()// 停止侦听count.value// 不再触发注意在setup()或script setup中创建的 watch会自动绑定到组件实例组件卸载时自动停止。只有在异步回调中创建的 watch 才需要手动停止。// 异步中创建需要手动清理setTimeout((){conststopwatch(source,cb)onUnmounted(stop)},1000)五、watchEffect —— 自动追踪watchEffect会立即执行一次并自动收集回调中用到的响应式依赖。constcountref(0)constnameref(Tom)watchEffect((){// 自动追踪 count 和 nameconsole.log(count${count.value}, name${name.value})})// 立即输出一次之后任一变化都触发watch vs watchEffect 对比特性watchwatchEffect执行时机默认惰性立即执行依赖收集显式指定自动收集旧值可获取无法获取适用场景需新旧值对比、精确控制简单副作用watchEffect 的停止与清理conststopwatchEffect((onCleanup){consttimersetInterval((){},1000)onCleanup(()clearInterval(timer))})stop()// 停止watchPostEffect和watchSyncEffectimport{watchPostEffect,watchSyncEffect}fromvue// flush: postwatchPostEffect((){// DOM 更新后执行})// flush: syncwatchSyncEffect((){// 同步执行})六、实战案例案例 1搜索框防抖script setup import { ref, watch } from vue const keyword ref() const results ref([]) let timer null watch(keyword, (newVal) { clearTimeout(timer) timer setTimeout(async () { if (!newVal) { results.value [] return } const res await fetch(/api/search?q${newVal}) results.value await res.json() }, 300) }) /script template input v-modelkeyword placeholder搜索... / ul li v-foritem in results :keyitem.id{{ item.name }}/li /ul /template案例 2侦听 props 变化script setup import { watch, toRefs } from vue const props defineProps({ userId: Number }) // ✅ 推荐getter 写法 watch( () props.userId, async (newId) { if (newId) { await loadUser(newId) } }, { immediate: true } ) /script案例 3多源侦听 深度侦听constformreactive({name:,address:{city:,street:}})watch([()form.name,()form.address.city],([newName,newCity],[oldName,oldCity]){console.log(name:${oldName}-${newName})console.log(city:${oldCity}-${newCity})},{immediate:true})案例 4避免竞态的异步请求watch(()props.id,async(newId,oldId,onCleanup){letcancelledfalseonCleanup(()(cancelledtrue))constdataawaitfetchData(newId)if(!cancelled){// 确保只渲染最新请求的结果result.valuedata}},{immediate:true})七、常见坑点总结侦听 reactive 对象直接传参会失效必须用 getter否则新旧值相同。ref 对象的.value侦听 ref 本身传ref侦听属性传() ref.value.xxx。deep 性能问题大对象深度侦听开销大优先用 getter 精确侦听。数组/对象引用变化watch侦听的是引用直接修改属性需deep: true。异步创建的 watch 不会自动清理需要手动调用停止函数或用onUnmounted清理。watchEffect无法获取旧值需要新旧值对比时用watch。flush: sync慎用频繁触发会导致性能问题。八、速查表场景写法侦听单个 refwatch(ref, cb)侦听 reactive 属性watch(() obj.key, cb)侦听整个 reactivewatch(obj, cb)自动 deep侦听多个源watch([a, b], cb)立即执行{ immediate: true }深度侦听{ deep: true }DOM 更新后执行{ flush: post }只执行一次{ once: true }自动追踪依赖watchEffect(fn)停止侦听const stop watch(...); stop()掌握以上内容即可应对 Vue 3 中绝大多数watch使用场景。核心原则能精确侦听就不用 deep能用 getter 就不传对象异步副作用记得清理。