在 Vue 组合式 API 中，当我们需要在响应式状态变化时执行“副作用”（如操作 DOM、发起异步请求、修改其他状态等），watch 和 watchEffect 是核心工具。它们能帮我们精准捕获状态变化并触发对应逻辑，但用法和适用场景各有不同。下面从基础用法到高级特性，全面解析两者的使用规则与细节。

一、watch：精准侦听指定数据源

watch 函数的核心特点是“精准控制”：需要明确指定要侦听的“数据源”，且仅当数据源变化时才触发回调。它适用于需要知道“旧值”“新值”，或需手动控制侦听目标的场景。

1. 基本用法（示例解析）

先从官方示例理解 watch 的基础逻辑：

 <script setup>
 import { ref, watch } from 'vue'
 
 const question = ref('') // 响应式状态：绑定输入框的问题
 const answer = ref('Questions usually contain a question mark. ;-)') // 响应式状态：答案
 const loading = ref(false) // 响应式状态：加载状态
 
 // 侦听 question 的变化：当 question 改变时，执行回调
 watch(question, async (newQuestion, oldQuestion) => {
   // 仅当输入包含问号时，才发起请求
   if (newQuestion.includes('?')) {
     loading.value = true // 开始加载
     answer.value = 'Thinking...' // 临时提示
     try {
       // 调用第三方 API 获取答案
       const res = await fetch('https://yesno.wtf/api')
       answer.value = (await res.json()).answer // 更新答案
     } catch (error) {
       answer.value = 'Error! Could not reach the API. ' + error // 捕获错误
     } finally {
       loading.value = false // 结束加载
     }
   }
 })
 </script>
 
 <template>
   <p>
     Ask a yes/no question:
     <input v-model="question" :disabled="loading" /> <!-- 输入框绑定 question，加载时禁用 -->
   </p>
   <p>{{ answer }}</p> <!-- 展示答案 -->
 </template>

核心逻辑：

• 明确指定侦听目标为 question（一个 ref）；
• 回调函数接收两个参数：newQuestion（变化后的新值）和 oldQuestion（变化前的旧值）；
• 仅当 question 变化且满足“包含问号”时，才执行后续的异步请求等副作用。

2. 侦听数据源的类型

watch 的第一个参数（数据源）支持多种形式，覆盖不同的侦听需求：

注意点：

• 若要侦听“响应式对象的属性”（如 reactive 对象的某个属性），不能直接传属性，必须用 getter 函数包裹。 例如：
• const obj = reactive({ count: 0 })
  
  // 错误：obj.count 是普通数值，不是响应式数据源
  watch(obj.count, (count) => { ... })
  
  // 正确：用 getter 函数返回属性，让 Vue 能追踪变化
  watch(() => obj.count, (count) => { ... })

3. 深层侦听器（处理嵌套对象/数组）

当侦听“响应式对象”（如 reactive 创建的对象、数组）时，watch 的“深层侦听”特性会影响回调触发时机：

• 情况1：直接侦听响应式对象（隐式深层侦听） 若直接将 reactive 对象作为数据源，watch 会自动创建“深层侦听器”——对象内任意嵌套属性变化时，都会触发回调：
• const obj = reactive({
  count: 0,
  info: { name: 'vue' }
  })
  
  // 直接侦听 reactive 对象：隐式深层侦听
  watch(obj, (newVal, oldVal) => {
  // 当 obj.count 变化（如 obj.count++），或 obj.info.name 变化（如 obj.info.name = 'vue3'）时，都会触发
  console.log('obj 内部有属性变化')
  })
• 注意：此时 newVal 和 oldVal 是同一个对象（因为 reactive 对象始终指向同一个引用），无法通过它们区分嵌套属性的具体变化。

• 情况2：用 getter 函数返回响应式对象（默认浅层侦听） 若用 getter 函数返回一个响应式对象（如 () => state.someObject），watch 默认是“浅层侦听”——仅当对象被整体替换时才触发回调：
• const state = reactive({
  someObject: { name: 'a', age: 18 }
  })
  
  // 用 getter 返回对象：浅层侦听
  watch(() => state.someObject, (newObj) => {
  // 仅当 state.someObject 被整体替换时触发（如下方代码）
  // 若仅修改属性（如 state.someObject.name = 'b'），不会触发
  console.log('someObject 被替换了')
  })
  
  // 触发回调：整体替换
  state.someObject = { name: 'b', age: 20 }

• 情况3：手动开启深层侦听（deep: true） 若需要通过 getter 函数侦听对象，且希望“嵌套属性变化时也触发”，可添加 deep: true 选项（Vue 3.5+ 中 deep 还可设为数字，表示最大遍历深度）：
• watch(
  () => state.someObject, // getter 函数返回对象
  (newObj) => {
  // 当 someObject 的任意嵌套属性变化时触发（如 name 变化、age 变化）
  console.log('someObject 内部属性变化')
  },
  { deep: true } // 开启深层侦听（3.5+ 可写 { deep: 2 }，限制遍历深度为 2 层）
  )

性能提示： 深层侦听需要遍历对象的所有嵌套属性，若对象结构复杂（如大型数组、深层嵌套对象），会产生性能开销。建议仅在必要时使用，优先通过“拆分状态”“手动指定关键属性”减少深层侦听的范围。

4. 其他常用选项

watch 还支持通过第三个参数（选项对象）控制回调的执行时机，常见选项如下：

• immediate: true：立即执行回调 watch 默认是“懒执行”（仅数据源变化时触发），若需要“创建侦听器时立即执行一次回调”（如初始加载数据），可加 immediate: true：
• watch(
  () => userId.value, // 侦听用户 ID
  async (newId) => {
  // 立即执行一次（获取初始用户数据），之后 userId 变化时再执行
  const res = await fetch(`/api/user/${newId}`)
  userData.value = await res.json()
  },
  { immediate: true } // 立即执行
  )

• once: true：仅触发一次 Vue 3.4+ 支持 once: true，使回调仅在数据源第一次变化时触发，之后不再响应：
• watch(
  count, // 侦听计数器
  (newCount) => {
  // 仅 count 第一次变化时触发（如从 0→1），后续变化（1→2、2→3）不触发
  console.log('count 首次变化')
  },
  { once: true }
  )