前端 Vue watch 深度监听 怎样处理

我在维护 Vue 表单状态时，最容易踩的坑不是不会写 watch，而是把“对象被替换”和“对象内部某个字段被修改”当成了同一件事。处理 Vue watch 深度监听，关键是先确定要观察的层级，再决定用精确 getter、deep: true、Vue 3.5+ 的数值 deep，还是直接改用 watchEffect。生产代码不建议无条件监听整棵大对象。

官方地址：https://vuejs.org/guide/essentials/watchers.html

我先把监听范围拆开

Vue 的 watch 默认是浅层触发：一个 getter 只有在返回值发生变化时才会触发。如果直接把 reactive 对象交给 watch，Vue 会隐式创建深度监听；如果用 getter 返回这个对象，则默认只关心对象引用是否被替换。

import { reactive, watch } from 'vue'

const form = reactive({
  profile: { name: '小林', city: '杭州' },
  flags: { dark: false }
})

// 中文注释：直接监听 reactive 对象，会覆盖内部嵌套变更。
watch(form, () => {
  console.log('form 内部有变化')
})

// 中文注释：getter 默认只关心 profile 这个对象是否被替换。
watch(() => form.profile, () => {
  console.log('profile 引用被替换')
})

// 中文注释：只监听一个字段，触发面最小，也更容易解释。
watch(() => form.profile.city, (city, oldCity) => {
  console.log('城市发生变化', oldCity, city)
})

这三种写法的差别，决定了后面是否需要 deep。如果你的副作用只依赖一个字段，直接监听字段通常比深度监听更稳；只有当嵌套层级本身就是业务输入时，才考虑扩大范围。

需要捕获嵌套修改时再打开 deep

当监听的是 getter 返回的对象，而业务确实要响应对象内部字段变化，可以显式配置 deep: true。它解决的是“嵌套属性变了但回调没进来”，不是“让新旧值自动变成两份快照”。

import { reactive, watch } from 'vue'

const settings = reactive({
  notify: { email: true, sms: false },
  theme: { color: 'blue' }
})

// 中文注释：getter 配合 deep 才会继续遍历返回对象的嵌套属性。
watch(
  () => settings,
  (newValue, oldValue) => {
    // 中文注释：内部属性修改时，两者通常仍指向同一个对象。
    console.log(newValue === oldValue) // true（对象未被整体替换时）
  },
  { deep: true }
)

// 中文注释：如果只关心一个布尔值，精确 getter 就足够了。
watch(() => settings.notify.email, (enabled) => {
  console.log('邮件通知', enabled ? '开启' : '关闭')
})

如果回调需要比较修改前后的完整内容，不能直接依赖 oldValue。对象内部变更时，Vue 不会替你做深拷贝；可以在业务边界自行保存必要的字段快照，或者把监听目标改成返回一个轻量派生值。

Vue 3.5+ 可以限制深度

Vue 官方文档说明，Vue 3.5 及以上版本的 deep 可以传数字，表示最多遍历多少层。这样比 deep: true 更容易表达边界；旧版本不支持这个写法，不能把数值配置直接下发到所有项目。

import { ref, watch } from 'vue'

const rows = ref([
  { id: 1, meta: { selected: false } }
])

// 中文注释：Vue 3.5+ 用 deep: 1 观察数组替换和数组元素层面的变更。
watch(rows, (value) => {
  console.log('行集合发生变化', value.length)
}, { deep: 1 })

// 中文注释：如果项目低于 Vue 3.5，必须按旧版本规则使用 deep: true 或精确 getter。
// watch(rows, callback, { deep: 1 }) // 不要把这行直接用于旧版本项目

这个选项适合有明确层级的数组或配置对象，但它不是性能开关。遍历范围缩小了，不代表回调本身可以随意执行昂贵计算；仍要在回调里做去重、节流或把副作用拆出去。

大对象场景，我更倾向精确 getter 或 watchEffect

深度监听需要遍历被观察对象的嵌套属性。表单、筛选条件和缓存状态一旦变大，deep: true 会让监听面和维护成本一起上涨。我的取舍通常是：一个字段用 getter，几个明确字段用数组 source，回调使用的依赖很多且天然相同则评估 watchEffect。

import { reactive, watch, watchEffect } from 'vue'

const query = reactive({
  keyword: '',
  page: 1,
  filters: { type: 'all', owner: '' }
})

// 中文注释：数组 source 只表达真正影响请求的字段。
watch(
  [() => query.keyword, () => query.filters.type],
  ([keyword, type]) => {
    console.log('查询条件变化', keyword, type)
  }
)

// 中文注释：回调同步读取到的依赖会被自动收集，适合依赖集合会变化的场景。
watchEffect(() => {
  const cacheKey = `${query.keyword}:${query.page}`
  console.log('准备刷新缓存', cacheKey)
})

watchEffect 并不是深度监听的同义词。它只会追踪回调同步执行阶段实际访问的响应式属性；异步回调在第一个 await 之后读取的属性不会被自动追踪。需要精确控制触发条件时，显式 watch 更清楚。

异步副作用要把旧请求清掉

深度监听经常用于筛选条件变化后的请求，但频繁修改输入时，旧请求可能晚于新请求返回。Vue 的 watcher 可以注册清理函数，在下一次重新运行前取消上一次副作用。

import { ref, watch } from 'vue'

const keyword = ref('')

watch(keyword, (value, _oldValue, onCleanup) => {
  const controller = new AbortController()

  // 中文注释：下一次 watcher 触发前取消仍未完成的旧请求。
  onCleanup(() => controller.abort())

  fetch(`/api/search?q=${encodeURIComponent(value)}`, {
    signal: controller.signal
  }).catch((error) => {
    // 中文注释：取消属于正常清理，不把 AbortError 当成业务失败上报。
    if (error.name !== 'AbortError') console.error(error)
  })
})

如果使用 Vue 3.5+ 的 onWatcherCleanup，要在 watcher 回调同步阶段注册，不能等到 await 之后才注册。无论采用哪种形式，都建议让清理逻辑和副作用放在同一个 watcher 内，便于回看。

上线前用一张表检查

我自己的发布检查会再看三件事：是否真的需要整对象遍历，项目 Vue 版本是否支持当前选项，异步副作用是否注册了清理。只要这三项能对上，深度监听就不再是“加一个参数碰碰运气”。

常见追问

为什么 deep 监听后 newValue 和 oldValue 相等？

因为是对象内部变更，两个参数通常仍引用同一个对象。需要差异时，应在业务侧保存必要的快照或监听更小的派生值。

数组变化一定要 deep: true 吗？

Vue 3.5+ 可以用 deep: 1 表达数组替换和数组元素层级的变更；Vue 3.0 至 3.4 需要按旧规则使用 deep: true 或改成精确 getter。

deep: true 能解决性能问题吗？

不能。它扩大监听范围，可能增加遍历成本。性能敏感时优先缩小 source，必要时用数值 deep、派生值或 watchEffect。