做后台管理系统这几年，“父组件传下来的数据变了，子组件怎么知道”这个问题，我差不多每周都要回答一次。上周同事调一个筛选联动的bug，父组件从接口拉回新的筛选项，子组件里的表格始终不刷新，他debug了一下午，最后发现是把props的值赋值给了本地data，导致数据流动在初始化之后就切断了。这不是个例。很多人对Vue3里watch监听props的理解，停留在“加一个watch就行”的层面，真到写的时候才发现一堆细节：有些场景监听根本不会触发，有些场景旧值和新值指向同一个对象，还有人纠结到底该用watch还是computed。这篇文章我就把这些东西一次性讲透：什么时候该监听props、怎么写最稳、监听不触发时怎么一步步排查，顺便把Vue3里defineProps的类型定义、props赋值给data的替代方案一起整理。面向的人群很明确——正在用Vue3做实际项目、尤其是维护中后台系统的读者，看完可以直接把里面的写法搬进自己的代码里。
1. props监听的本质：父组件数据变化后的“被动响应”
1.1 先从一次筛选联动说起
几乎每个后台项目里都能看到这个画面：父组件从接口拉取筛选条件，通过props传给子组件，子组件要根据条件变化重新请求列表。代码长这样：
<!-- Parent.vue --> <template> <FilterTable :filters="filters" /> </template> <script setup> import { ref } from 'vue' const filters = ref({ keyword: '', status: 1 }) // 模拟某个操作后更新筛选条件 function onSearch() { filters.value = { ...filters.value, keyword: 'vue' } } </script><!-- FilterTable.vue --> <template> <el-table :data="list" /> </template> <script setup> import { ref, watch } from 'vue' import { fetchList } from '@/api' const props = defineProps({ filters: { type: Object, default: () => ({}) } }) const list = ref([]) watch(() => props.filters, (newVal) => { fetchList(newVal).then((res) => { list.value = res }) }, { immediate: true, deep: true }) </script>这就是最典型的props监听需求。难点不在于“写一个watch”，而在于你写的watch在什么条件下触发、在什么条件下不触发、首次挂载时到底跑不跑。这些问题不搞清楚，写出来的代码大概率会在某个边界场景上翻车。
1.2 为什么子组件不能直接改props
很多人第一次在子组件里试图修改props，会看到Vue在控制台抛警告：
[Vue warn]: Set operation on key "filters" failed: target is readonly.
这不是Vue在跟你过不去，而是框架层面的设计约束。props是父组件向子组件单向传递数据的通道，它的语义是“父组件是这份数据的唯一拥有者”。如果子组件能随意改写props，就会出现两个来源同时修改一份数据的局面：父组件的状态是旧的，子组件却把显示值改了，两者一旦不同步，排查成本会成倍上升。
所以props在子组件里是一个readonly的代理对象。你不能写，但可以读，也可以基于它做派生、做监听。这正是watch派上用场的前提：既然不能直接改，那就监听它的变化，再决定子组件内部要做哪些动作。
1.3 不是所有props都需要watch：先想清楚三个场景
在下笔写watch之前，建议你先回答一个问题：这个props变化之后，子组件究竟要干什么？
我把实际项目中遇到的情况归纳成三类：
- 只是展示派生值：比如父组件传入商品单价和数量，子组件要显示总价。这种应该用computed，它不是副作用，也不该用watch去“手动触发”。
- 需要触发副作用：比如重新请求接口、重置表单、播放动画、上报埋点。这种才适合watch，因为副作用是“做一件事”，不是“算一个值”。
- 需要本地编辑后回传：比如子组件是一个可编辑表单，props传入初始值，用户改了之后要通过事件通知父组件。这种不应该靠watch同步，更不该把props直接赋值给data，而是应该用computed的getter/setter或者
v-model:xxx模式。
说白了，watch不是万能钥匙。它解决的是“数据变化后我要做点什么”的问题，而不是“数据变化后我要显示什么”的问题。后者交给computed，前者才轮到watch。
2. watch监听props的标准写法：getter是关键
2.1 为什么第一个参数必须传getter函数
组合式API里watch的第一个参数接收的是“响应式来源”，可以是ref、reactive对象、getter函数、或者由它们组成的数组。很多人写错的地方在于直接传了props的属性值：
// 错误写法：props.count 是一个普通值，不是响应式来源 watch(props.count, (newVal) => { console.log(newVal) }) // 正确写法：用 getter 返回 props.count watch(() => props.count, (newVal) => { console.log(newVal) })为什么必须包一层getter？因为props.count在表达式求值的那一刻就已经变成了一个具体的数字或字符串，watch拿到的是一个快照，根本没有追踪到“它从哪里来”。而() => props.count是一个函数，watch在内部执行它的时候，会触发props.count的getter，把props这个响应式对象收集为依赖。之后props.count一旦变化，watch就能感知到并重新执行getter、对比新旧值。
用一句话理解：watch监听的不是“值”，而是“值的来源路径”。getter就是那条路径。
2.2 immediate和deep：两个最常用的配置项
watch默认是惰性的——只有被监听的数据变化时才会执行回调。但业务里经常有“首次进入页面就要根据props拉一次数据”的需求，这时候就需要immediate: true：
watch(() => props.keyword, (newVal) => { getList({ keyword: newVal }) }, { immediate: true })加了immediate之后，组件创建时会立刻执行一次回调，此时newVal是props的当前值，oldVal是undefined。这个参数解决的是“初始化逻辑”和“更新逻辑”重复写两遍的问题，可以说是props监听里使用频率最高的配置。
deep: true则用在对象型props上。如果父组件传下来的是一个对象，而父组件内部直接改了对象的某个字段（比如obj.name = 'xxx'），对象引用本身没变，默认的浅监听不会触发。加上deep之后，Vue会递归遍历对象的每一层属性，任何一层的修改都能被感知。
两个参数放在一起，覆盖了大多数真实场景。我在代码里最常见的组合就是：
watch(() => props.filters, handler, { immediate: true, deep: true })2.3 同时监听多个props：数组写法
有时候一个副作用依赖于多个props。比如分页表格，页码和每页条数都是父组件传下来的，任何一个变化都要重新拉数据。watch支持传数组：
watch( [() => props.page, () => props.pageSize], ([newPage, newSize], [oldPage, oldSize]) => { getList({ page: newPage, pageSize: newSize }) } )回调参数也对应变成数组解构，每个新值和旧值一一对应。这种写法比写两个watch再互相调用的方式清晰得多，也避免了重复请求。需要注意，数组里的每个元素都必须是合法的响应式来源，也就是ref、getter或reactive对象，不能直接写props.page。
2.4 只监听props对象里的某个字段
对象型props最常见的操作是只关心里面某一个字段。比如props.filters里有keyword、status、dateRange三个字段，只有keyword变化时才要触发特定逻辑。这时候可以让getter直接返回具体字段：
watch(() => props.filters?.keyword, (newVal, oldVal) => { // 只有 keyword 变化时才会触发 console.log(newVal, oldVal) })这种写法有几个隐藏的好处。第一，监听的粒度细了，不会因为status或者dateRange变化而误触发。第二，新旧值都是基本类型，对比可靠，不会出现“新旧值指向同一个对象”的尴尬。第三，配合可选链?.使用，还能规避props初始默认值不到位时访问嵌套属性报错的问题。
这也是我想反复强调的一点：getter返回什么，watch就监听什么。返回对象，你就做实引用对比；返回字段值，你就做精确的值对比。合理控制getter的返回粒度，能避免后面一大半坑。
3. 最容易翻车的三个细节：不触发、旧值失真、初始化丢数据
3.1 对象内部被修改，浅监听默认不触发
我见过不少这样的案例：子组件里写了watch(() => props.filters, handler)，父组件里执行filters.value.status = 2，子组件的handler纹丝不动。原因就是浅监听只做引用对比——props.filters的引用没变，Vue就认为“没变化”。
要解决这个问题，有两条路：
// 方案一：加 deep，递归监听内部属性 watch(() => props.filters, handler, { deep: true }) // 方案二：getter 返回具体字段，只监听你关心的那一个 watch(() => props.filters.status, handler)方案一的优点是省事、覆盖面广，缺点是有性能开销——对象层级越深、体积越大，遍历成本越高。方案二是精准打击，只监听需要的字段，性能更好，逻辑也更清晰。我的习惯是能用方案二就不用方案一，除非真的需要感知整个对象的任何变化。
另外还有一个技巧：getter里返回一个新对象，比如watch(() => ({ ...props.filters }), handler)。因为每次执行getter都会创建新对象，引用必然不同，所以一定能触发。但要小心，这种写法会降低监听的“精度”，可能在其他无关的响应式更新里也被触发，属于一种暴力的兜底方案，建议只在临时调试时用，线上代码慎选。
3.2 新旧值指向同一个对象，旧值失真
这个坑特别隐蔽。如果你监听的是对象本身，而且加上了deep，当父组件修改对象内部字段时，回调确实触发了，但newVal和oldVal是同一个对象引用：
watch(() => props.obj, (newVal, oldVal) => { console.log(newVal === oldVal) // true console.log(oldVal.name) // 已经是修改后的值了，旧值被“污染” })因为props.obj从头到尾都是同一个引用，deep只是让Vue“感知到”了内部变化，但并没有帮你复制一份旧值。所以你在回调里拿到的oldVal，实际上已经是新的样子了。
如果你真的需要旧值做对比，我的做法是自己在外部维护快照：
let snapshot = JSON.parse(JSON.stringify(props.obj)) watch(() => props.obj, (newVal) => { const old = snapshot snapshot = JSON.parse(JSON.stringify(newVal)) // 此时 old 是变化前的完整数据，newVal 是当前数据 }, { deep: true })这个方法理解成本低，也足够可靠。对于无法JSON序列化的字段（比如Date、函数），可以换成structuredClone或者针对性地只复制你需要对比的字段。总之记住结论：指望watch自动给你一份不污染的对象旧值，是不现实的。
3.3 初始化时拿不到值，或首次就要执行却被跳过
第三个高频问题是初始化逻辑缺失。比如子组件挂载时要根据props.keyword设置某个本地状态，你写了一个watch但没加immediate，于是首次挂载时回调不执行，本地状态一直空着。等父组件改了keyword才执行，但那时候已经错过第一帧了。
解决方式有两种。第一种是给watch加immediate: true，让回调在初始化时执行一遍。第二种是用watchEffect，因为它天生就是立即执行的：
watchEffect(() => { localKeyword.value = props.keyword })watchEffect会自动追踪回调里访问的所有响应式数据，props.keyword一旦变化，回调就重跑。它和watch + immediate的区别在于，你不用手动指定监听目标，但你也拿不到新旧值。在“只要同步最新值、不需要做对比”的场景下，watchEffect写起来更省事。
3.4 记住一句口诀：监听的是“返回值变没变”
把上面三个坑串起来，其实就一句话：watch比较的是getter的返回值是否变化。返回基本类型，就比较值；返回引用类型，就比较引用；返回新对象，那就每次都算变。想清楚这一步，你就能预判watch到底触发不触发，而不是等上线了看用户反馈。
4. watch、computed与props转data：到底该选谁
4.1 computed是“自动计算”，watch是“手动触发”
这是Vue面试里几乎必考的问题，也是实际写代码时最容易纠结的地方。两者的本质区别在于数据流方向不同：
| 维度 | computed | watch |
|---|---|---|
| 定位 | 声明式派生数据 | 命令式副作用 |
| 缓存 | 有，依赖不变不重算 | 无，每次触发都执行 |
| 适用场景 | 由现有数据直接得出的展示值 | 请求、日志、重置、动画等动作 |
| 异步能力 | 设计上不该用 | 可以放心用 |
| 代码风格 | 返回一个值 | 执行一段逻辑 |
举一个最直白的例子：父组件传进来一个搜索关键词，子组件要显示“你正在搜索：xxx”。这是派生展示，computed就够了。但如果关键词变化后要重新请求接口、要重置分页、要上报埋点，这些是动作，该用watch。
很多人把computed和watch用反，主要原因是没有区分“值”和“事”。一个干净的组件里，computed负责把数据变成可展示的形态，watch负责把数据变化变成可执行的逻辑，两者各司其职。
4.2 props赋值给data，错在哪、怎么改
“把props赋值给data”是网上被问烂了的问题，因为它在Vue2时代就已经是个经典误解，到了Vue3依然有人踩：
// 错误示范：只拿到了初始值的快照 const localFilters = ref(props.filters)ref(props.filters)执行的那一刻，props.filters的值被复制进了ref内部。之后父组件再怎么更新props.filters，localFilters都不会跟着变，因为它们之间没有任何连接。这就是文章开头我同事那个bug的根因。
如果你想让本地变量和props保持同步，有三种正确的姿势：
// 方式一：toRef 建立引用连接，适合只读场景 const filtersRef = toRef(props, 'filters') // 方式二：toRefs 批量连接，适合需要解构多个属性 const { filters, page } = toRefs(props) // 方式三：computed + emit，适合需要本地编辑并回传的场景 const localFilters = computed({ get: () => props.filters, set: (val) => emit('update:filters', val) })方式一和方式二保持了响应式链路，父组件换新值时本地也跟着变，但它们不适合“本地修改”，因为直接修改会触发readonly告警。方式三走的是“编辑-回传-父组件更新-再传回来”的闭环，符合单向数据流，是可编辑子组件的标准解法。
另外提醒一下，toRef在处理带有默认值的props时有个细节：如果父组件还没传值，toRef(props, 'defaultKey')拿到的ref会随着props默认值的生效自动更新，比手动ref(props.defaultKey)可靠得多。
4.3 我的选型建议
我自己在实际项目里的判断顺序大概是这样：
| 需求 | 首选方案 |
|---|---|
| 派生展示值 | computed |
| 触发副作用 | watch + immediate（如果需要初始执行） |
| 保持本地读取同步 | toRef / toRefs |
| 本地编辑回传 | computed getter/setter + emit |
| 不需要新旧值对比的副作用 | watchEffect |
这套组合基本能覆盖90%以上的场景。剩下那10%属于特殊情况，比如需要精确控制触发时机、需要取消上一次请求，那就用到下一节的内容。
5. Vue2到Vue3：watch监听props的差异全梳理
5.1 options API写法在Vue3里依然能跑
很多从Vue2迁移过来的项目，还在用options API的写法：
export default { props: ['count'], watch: { count: { handler(newVal, oldVal) { console.log(newVal, oldVal) }, immediate: true } } }Vue3对options API的watch是兼容的，包括'props.count'这种字符串路径写法：
watch: { 'props.count': function (newVal, oldVal) { // 依然有效 } }但如果你用的是<script setup>，那就没有options API的位置了，只能用组合式API的watch。这就是为什么现在新项目里看到的多是getter写法。迁移的时候不用慌，两者在immediate、deep这些配置项上的语义一致的，差别主要在写法形态上。
5.2 watchEffect：不用指定来源的监听
Vue3新增的watchEffect是很多新人容易忽略的工具。它和watch最大的区别在于：watch要先指定“你要监听什么”，watchEffect则是“我在回调里用了什么，就自动监听什么”。
const requestParams = ref({ keyword: '', page: 1 }) watchEffect(() => { // 这里访问了 requestParams，它变化时回调会自动重跑 getList(requestParams.value) })watchEffect的好处是心智负担小，不需要维护getter列表。坏处是它拿不到新旧值，而且因为它立即执行，初次调用就会发起一次请求。如果你不需要“对比变化前后”，只是想“每次数据变了就同步做点事”，watchEffect是更简洁的选择。在props监听的场景里，它特别适合用来把props和本地状态做同步。
5.3 onCleanup：处理请求竞态问题的正确姿势
这是watch回调里一个非常实用但容易忽略的参数。当用户快速切换筛选条件时，前一个请求可能比后一个请求慢，导致先发出去的请求后返回，把最新的列表覆盖掉。这种竞态问题在watch回调里特别常见。
Vue3的watch回调第三个参数就是onCleanup，用于在上一次回调还没结束时标记“我需要取消”：
watch(() => props.keyword, async (newVal, _oldVal, onCleanup) => { let cancelled = false onCleanup(() => { cancelled = true }) const res = await fetchList({ keyword: newVal }) if (!cancelled) { list.value = res } })当keyword再次变化、上一次回调仍在等待时，onCleanup注册的清理函数会被调用，把cancelled置为true。这样就算旧请求最后返回了，也不会覆盖最新的数据。这个模式在后台管理系统的筛选、搜索、分页联动里几乎是刚需，强烈建议用上。
5.4 flush时机：默认'pre'，需要DOM更新后执行用'post'
watch回调的默认触发时机是组件更新之前，也就是flush: 'pre'。大多数时候这没问题，但如果你的回调里需要读取或操作DOM，而DOM的更新依赖props的变化，那么回调执行时DOM可能还没更新完。
这时候可以把flush改成post：
watch(() => props.activeTab, (newVal) => { // DOM 已经根据新值更新完毕 scrollToTab(newVal) }, { flush: 'post' })如果你在Vue2里用过$nextTick，可以理解为flush: 'post'帮你把这个步骤内置了。除此之外还有一个sync模式，会在数据变化时同步执行回调，但因为会牺牲性能，实际业务里几乎用不上，了解即可。
6. 监听没触发？完整排查链路
6.1 先看props定义：类型对不对，默认值有没有生效
排查监听问题，我习惯先从props定义下手。Vue3的defineProps有两种写法，类型标注和运行时声明。TypeScript项目里推荐用类型标注：
<script setup lang="ts"> interface Props { keyword: string tags?: string[] user: { name: string age: number } } const props = withDefaults(defineProps<Props>(), { keyword: '默认关键词', tags: () => [] }) </script>这里有个常见坑：如果父组件传的值是undefined，而你没有设置默认值，那么子组件里props.keyword就是undefined。此时如果watch的getter访问了props.user.name，会直接抛Cannot read properties of undefined。所以getter里尽量用可选链，或者给对象类型的props加上默认值工厂函数。排查第一步，就是确认props的值和类型都符合预期，再往下看。
6.2 再看父组件：数据是真的变了吗
props监听不触发，有时候问题根本不在子组件，而在父组件的数据根本没有变成“响应式的变化”。常见三种情况：
- 父组件直接mutate了对象的同一引用，子组件浅监听自然感知不到（这种属于预期行为，不是bug）。
- 父组件从Pinia里取数据，但用了普通变量解构，把响应性丢了：
const filters = store.filters，这会让整个数据流断开。 - 父组件在异步回调里改了值，但子组件props本身没有正确绑定。
我的排查方式很简单：在父组件模板里临时显示这个props，{{ filters }}，看它是否真的变了。父组件都变不了，子组件监听个寂寞。
6.3 再看watch的写法：getter和回调是否有问题
确认父组件数据正常之后，回头检查子组件的watch本身：
- source是不是getter，还是写成了普通值？
- getter返回的粒度对不对？返回的是整个对象，还是具体字段？
- 是否需要
deep: true？ - 是否需要
immediate: true处理初始状态？ - 依赖的props字段是否真的被访问到了？如果getter里写了个死值，比如
() => 1，那永远不会触发。
这一层检查是定位“写法问题”的关键。大多数“监听没反应”的案例，最终都折在这一步。
6.4 用watchEffect做归零验证
当你实在不确定问题出在哪里，我建议用watchEffect做一个“归零验证”：
watchEffect(() => { console.log('当前props.keyword：', props.keyword) console.log('当前props.filters：', JSON.stringify(props.filters)) })watchEffect会自动追踪回调里所有访问到的响应式数据，只要props里任何被访问的值发生了变化，控制台就会打印。如果watchEffect有输出、你原来的watch没输出，说明问题出在watch的source写法上，对照2.1和2.4检查getter。如果watchEffect也没输出，说明问题出在数据源头，回到6.2检查父组件。
这个方法的妙处在于，它把“watch有没有问题”和“数据有没有变”彻底拆成了两个独立问题，避免在一条链路上反复迷茫。
6.5 排查清单汇总
最后把常见的症状和对应解法整理成一张表，方便遇到问题时快速对照：
| 现象 | 可能原因 | 处理方式 |
|---|---|---|
| 对象字段变了，watch没触发 | 浅监听只对比引用 | 加deep，或getter返回具体字段 |
| 新旧值指向同一个对象 | 引用类型新旧是同一份 | 外部手动维护快照 |
| 首次挂载没有执行逻辑 | 默认惰性监听 | 加immediate，或改用watchEffect |
| watchEffect有输出，watch没有 | source写法有误 | getter包一层，确认返回的是响应式来源 |
| 父组件改了，控制台没任何输出 | 数据源本身失去响应性 | 检查父组件是否误用了普通解构 |
| 快速切换筛选，列表被旧请求覆盖 | 请求竞态 | 用onCleanup做取消标记 |
| DOM更新后才需要的操作拿不到新DOM | 触发时机过早 | 加flush: 'post' |
排查顺序就按这个表格从上往下走，大多数问题都能在几分钟内定位。
使用watch监听props这件事，表面上是API用法问题，实际上是对Vue响应式原理和组件数据流理解深度的体现。我自己现在的习惯是：能用toRef保持响应性就尽量别写watch；确实要监听时，先把immediate、deep、监听粒度这三个问题想清楚再动手；对象型props真正需要旧值时，自己维护快照比依赖watch的oldVal靠谱。这些结论都是一行行代码踩出来的，希望这篇能帮你把这条路上的弯弯绕绕提前趟平。
