Vue 3中watch侦听器的正确使用姿势你掌握了吗？深度监听、与watchEffect的差异及常见报错解析

1. 侦听器的基本用法

侦听器（watch）是Vue 3中用于响应式跟踪数据源变化的核心API，它允许你在响应式数据改变时执行自定义副作用（如发请求、更新DOM、日志记录等）。其核心逻辑是：明确指定要监听的“源”，并定义“变化时的回调”。

1.1 监听单个ref源

ref是Vue 3中最基础的响应式包装器，监听ref的语法非常直观——直接将ref对象作为watch的第一个参数：

<script setup>
import { ref, watch } from 'vue'

// 响应式数据：计数器
const count = ref(0)

// 侦听器：监听count的变化
watch(count, (newValue, oldValue) => {
  console.log(`计数器从 ${oldValue} 变到了 ${newValue}`)
  // 这里可以执行任何副作用，比如更新页面标题
  document.title = `Count: ${newValue}`
})
</script>

<template>
  <button @click="count++">点击增加（当前：{{ count }}）</button>
</template>

关键说明：

• watch的第一个参数是监听源（这里是count）；
• 第二个参数是变化回调，接收两个参数：newValue（变化后的值）、oldValue（变化前的值）；
• 点击按钮时，count变化会触发回调，修改页面标题。

1.2 监听reactive对象的属性

对于reactive创建的响应式对象，不能直接监听整个对象的属性（会丢失响应式跟踪），需要用getter函数返回要监听的属性：

<script setup>
import { reactive, watch } from 'vue'

// 响应式对象：用户状态
const user = reactive({
  name: 'Alice',
  age: 25
})

// 侦听器：监听user.name的变化
watch(
  () => user.name, // getter函数：返回要监听的属性
  (newName, oldName) => {
    console.log(`用户名从 ${oldName} 改为 ${newName}`)
  }
)
</script>

<template>
  <input v-model="user.name" placeholder="修改用户名" />
</template>

为什么要用getter？
reactive对象的属性是“响应式代理”，直接写user.name会返回原始值，无法被watch跟踪。getter函数会让Vue感知到“这个属性需要被跟踪”。

1.3 监听多个源

watch支持同时监听多个响应式源，只需将源包装成数组即可。回调函数的参数会对应数组的新值和旧值：

<script setup>
import { ref, reactive, watch } from 'vue'

const count = ref(0)
const user = reactive({ name: 'Alice' })

// 监听count和user.name两个源
watch(
  [count, () => user.name], // 源数组
  ([newCount, newName], [oldCount, oldName]) => { // 新值数组、旧值数组
    console.log(`计数器：${oldCount} → ${newCount}；用户名：${oldName} → ${newName}`)
  }
)
</script>

2. 侦听器的高级选项

watch还支持通过选项对象（第三个参数）配置更灵活的行为，常见选项有deep（深度监听）、immediate（立即执行）。

2.1 深度监听（deep: true）

当监听的源是嵌套对象时，默认情况下watch只会跟踪“对象引用”的变化，不会跟踪“嵌套属性”的变化。需要开启deep: true来监听嵌套属性：

<script setup>
import { reactive, watch } from 'vue'

// 嵌套响应式对象：商品信息
const product = reactive({
  id: 1,
  info: {
    name: 'Vue 3 实战',
    price: 99 // 嵌套属性
  }
})

// 深度监听product.info的变化
watch(
  () => product.info,
  (newInfo, oldInfo) => {
    console.log(`商品信息更新：价格从 ${oldInfo.price} 变为 ${newInfo.price}`)
  },
  { deep: true } // 开启深度监听
)
</script>

<template>
  <input v-model.number="product.info.price" placeholder="修改价格" />
</template>

注意：深度监听会遍历对象的所有嵌套属性，性能开销较大，尽量只在必要时使用（比如确实需要跟踪嵌套变化）。

2.2 立即执行（immediate: true）

默认情况下，watch只会在源第一次变化时执行回调。如果需要初始挂载时就执行一次（比如初始化时拉取数据），可以加immediate: true：

<script setup>
import { ref, watch } from 'vue'

const keyword = ref('Vue')

// 立即执行：页面加载时先查一次“Vue”的搜索结果
watch(
  keyword,
  async (newKeyword) => {
    const res = await fetch(`https://api.example.com/search?q=${newKeyword}`)
    const data = await res.json()
    console.log('搜索结果：', data)
  },
  { immediate: true }
)
</script>

应用场景：初始化时根据默认值加载数据（比如搜索页的默认关键词）。

3. watch vs watchEffect：核心差异与选择

3.1 核心差异对比

3.2 代码示例对比

<script setup>
import { ref, watch, watchEffect } from 'vue'

const count = ref(0)
const message = ref('Hello')

// 使用watch：显式监听count
watch(count, (newVal, oldVal) => {
  console.log(`count从 ${oldVal} 变到 ${newVal}`)
})

// 使用watchEffect：自动跟踪count和message
watchEffect(() => {
  console.log(`当前count：${count.value}，message：${message.value}`)
})
</script>

执行结果：

• 页面加载时，watchEffect立即执行，输出当前count：0，message：Hello；
• 点击按钮修改count，watch和watchEffect都会触发；
• 修改message，只有watchEffect触发（因为它自动跟踪了message）。

4. 实践中的应用场景

侦听器的价值在于将“数据变化”与“副作用”解耦，以下是几个常见的实际场景：

4.1 数据变化时发起网络请求

比如用户选择城市后，自动加载该城市的天气：

<script setup>
import { ref, watch } from 'vue'

const city = ref('北京')
const weather = ref('')

// 监听city变化，加载天气
watch(city, async (newCity) => {
  const res = await fetch(`https://api.example.com/weather?city=${newCity}`)
  const data = await res.json()
  weather.value = data.weather
})
</script>

<template>
  <select v-model="city">
    <option value="北京">北京</option>
    <option value="上海">上海</option>
    <option value="广州">广州</option>
  </select>
  <p>当前天气：{{ weather }}</p>
</template>

4.2 表单输入的实时验证

比如注册页的密码强度校验：

<script setup>
import { ref, watch } from 'vue'

const password = ref('')
const passwordError = ref('')

// 实时验证密码强度
watch(password, (newPwd) => {
  if (newPwd.length < 6) {
    passwordError.value = '密码必须至少6位'
  } else if (!/[A-Z]/.test(newPwd)) {
    passwordError.value = '密码必须包含大写字母'
  } else {
    passwordError.value = ''
  }
})
</script>

<template>
  <input type="password" v-model="password" placeholder="输入密码" />
  <p class="error" v-if="passwordError">{{ passwordError }}</p>
</template>

5. 课后Quiz

通过以下问题巩固所学知识（答案基于Vue官网文档）：

问题1：如何监听reactive对象中的嵌套属性（如state.user.address.city）？请写出代码示例。

答案：使用getter函数返回嵌套属性（显式指定监听源）：

const state = reactive({
  user: {
    address: {
      city: 'Beijing'
    }
  }
})

// 正确写法：用getter返回嵌套属性
watch(
  () => state.user.address.city,
  (newCity, oldCity) => {
    console.log(`城市从 ${oldCity} 改为 ${newCity}`)
  }
)

错误写法：直接写state.user.address.city（会丢失响应式跟踪）。

问题2：watch和watchEffect的核心区别是什么？请列举两点。

答案：

1. 依赖跟踪方式：watch需要手动指定监听源（显式），watchEffect自动跟踪回调中使用的所有源（隐式）；
2. 初始执行时机：watch默认不执行（需immediate选项），watchEffect挂载时立即执行一次。

6. 常见报错与解决方案

报错1：监听reactive对象时，旧值与新值相同

现象：修改reactive对象的属性后，watch回调中的oldValue和newValue完全一样。
原因：reactive返回的是代理对象，修改属性不会改变对象的引用，因此oldValue和newValue指向同一个对象。
解决方法：

• 若需监听单个属性，用getter函数返回属性（如() => state.count），此时oldValue会是原始值；
• 若需监听整个对象，手动保存旧值（适用于简单场景）：

  const state = reactive({ count: 0 })
  let oldCount = state.count // 手动保存旧值
  
  watch(
    () => state.count,
    (newCount) => {
      console.log(`旧值：${oldCount}，新值：${newCount}`)
      oldCount = newCount // 更新旧值
    }
  )
  

报错2：深度监听不生效

现象：修改reactive对象的嵌套属性，watch回调不触发。
原因：未开启deep: true选项，watch默认只跟踪对象的引用变化，不跟踪嵌套属性。
解决方法：在watch的选项中添加deep: true：

watch(
  () => state.user,
  (newUser, oldUser) => {
    console.log('用户信息更新：', newUser)
  },
  { deep: true } // 必须加！
)

报错3：immediate: true时旧值为undefined

现象：开启immediate后，第一次执行回调时oldValue是undefined。
原因：immediate让回调在挂载时立即执行，此时还没有“旧值”（第一次执行）。
解决方法：

• 若不需要旧值，忽略即可；
• 若需要初始值，手动处理（比如用ref保存初始值）：

  const keyword = ref('Vue')
  const initialKeyword = keyword.value // 保存初始值
  
  watch(
    keyword,
    (newKeyword, oldKeyword) => {
      if (oldKeyword === undefined) {
        console.log(`初始关键词：${initialKeyword}`)
      } else {
        console.log(`关键词从 ${oldKeyword} 改为 ${newKeyword}`)
      }
    },
    { immediate: true }
  )
  

参考链接

• Vue官网：侦听器基础 → vuejs.org/guide/essen…
• Vue官网：watch vs watchEffect → vuejs.org/guide/essen…
• Vue官网：侦听器选项 → vuejs.org/guide/essen…