Vue 3 中开启深度侦听需显式配置 { deep: true },用于监听 ref 或 reactive 对象内部嵌套属性变化;默认为浅层监听,仅响应顶层引用变更。

Vue 3 中开启深度侦听,核心就是给 watch 函数传入 { deep: true } 配置项。它不是默认行为,必须显式启用,否则只监听顶层引用是否变化。
什么时候必须加 deep: true
当你监听的是一个 ref 或 reactive 对象,且关心其内部任意嵌套属性(比如 user.profile.address.city)的变化时,就需要开启深度侦听。
- 监听
ref({ a: { b: 1 } }),直接改value.a.b = 2—— 不加deep: true就不会触发回调 - 监听
reactive({ list: [{ id: 1 }] }),往list里push新项 —— 同样需要deep: true才能捕获 - 注意:
watch默认是浅层的,即使源是响应式对象,也只盯它的“外壳”有没有被重新赋值
基础写法:对象 + 配置对象
最常用的方式是把要监听的数据和回调函数作为前两个参数,第三个参数传配置对象:
import { ref, watch } from 'vue'
const nested = ref({
user: {
name: 'Alice',
settings: { theme: 'dark' }
}
})
watch(nested, (newVal, oldVal) => {
console.log('整个 nested 变了', newVal)
}, { deep: true }) // ← 关键就这一行
这样无论你改 nested.value.user.name 还是 nested.value.user.settings.theme,都会触发。
更精准的写法:用 getter 函数
如果你只想监听某一层级(比如只关心 user.settings),推荐用函数形式,既避免全量遍历开销,又能拿到准确的新旧值:
- 写法:
watch(() => obj.user.settings, callback) - 不需要加
deep: true,因为 Vue 会自动追踪这个表达式里所有响应式依赖 - 如果
settings是 reactive 对象,它内部任何属性变,都会触发;如果是普通对象,则仍需手动 deep
替代方案:用 watchDeep 简化调用
如果你项目中大量使用深度侦听,可以引入 VueUse 的 watchDeep,它把 deep: true 写死了,调用更简洁:
import { watchDeep } from '@vueuse/core'
watchDeep(nested, (newVal) => {
console.log('nested 深层变了', newVal)
})
// 效果等价于原生 watch(..., ..., { deep: true })
函数名自带语义,减少遗漏配置的风险,适合团队统一规范。
前端入门到VUE实战笔记:立即使用
在学习笔记中,你将探索 前端 的入门与实战技巧!










