triggerRef 是 Vue 3 中专为 shallowRef 设计的手动通知更新工具，用于在直接修改其 .value 深层属性后触发依赖更新，需改完再调用且传 ref 本身，对 ref 或 reactive 无效。

triggerRef 是 Vue 3 中专为 shallowRef 设计的手动更新工具，不是“强制刷新组件”，而是告诉响应式系统：“这个 shallowRef 的 .value 虽然没换，但内部确实变了，请重新通知依赖”。它轻量、精准，只在必要时才用。

什么时候必须调用 triggerRef？

当你用 shallowRef 包裹一个对象（比如配置项、画布状态、大型列表），又直接修改了它的属性，但视图没反应——这就是典型信号。

• 修改了 state.value.name = '新名字' 或 list.value[0].done = true，但模板没更新
• 从第三方库（如 Chart.js、Three.js）回调中更新了对象字段
• 在定时器、事件监听器或 API 回调里改了 shallowRef.value 的深层内容
• 想避免频繁替换整个 .value 带来的内存开销（比如含上千条目的数据表）

怎么写才不出错？关键三步

写错参数、调用时机不对，是新手最常见的问题。记住：改完再触发，传 ref 本身，不传值。

• ✅ 正确写法：data.value.count++ → triggerRef(data)
• ❌ 错误写法：triggerRef(data.value)（报错）、triggerRef()（无效）、triggerRef({})（静默忽略）
• ⚠️ 注意：对 ref 或 reactive 调用 triggerRef 不起作用，也不需要——它们本就会自动响应内部变化
• ? 小技巧：一次改多个字段后，只调一次 triggerRef 即可，Vue 会批量合并后续更新

和哪些 API 配合更实用？

单独用 triggerRef 很直接，但结合其他响应式工具，能兼顾性能与可控性。

• 局部深度响应：对高频变动的子对象单独用 reactive，比如 const detail = reactive(user.value.profile)
• 读取原始值：修改前用 toRaw(shallowRef.value) 获取非代理对象，避免意外触发依赖
• 封装安全 setter：可封装一个自动触发的访问器，减少漏调风险，例如：set: (val) => { ref.value = val; triggerRef(ref); }
• 调试定位：在 triggerRef 前后加 console.log，确认修改已发生、触发及时

什么情况根本不用 triggerRef？

别为了用而用。很多场景其实更适合换种响应式策略。

• 数据结构简单（如不到 10 个字段、无深层嵌套），直接用 ref 或 reactive 更省心
• 只是修改字符串、数字等基本类型，ref 天然支持，无需手动干预
• 业务允许整体赋值，比如 list.value = [...list.value, newItem]，Vue 自动响应，比 triggerRef 更清晰
• 操作的是纯外部实例（如 Canvas、DOM 元素），本就不该参与响应式更新，应配合 markRaw