Vue3 响应式系统 toRef 和 toRefs 有何区别？新手最容易搞混的点解析

toRef用于安全提取单个可能不存在的属性并返回ref，toRefs用于批量解构已知结构的reactive对象并返回含多个ref的普通对象。

toRef 和 toRefs 都是用来解决 reactive 对象解构后丢失响应性的问题，但它们的使用场景和行为逻辑完全不同。新手常误以为“只是单个 vs 多个”，其实关键在目标对象是否必须存在、能否设默认值、返回值是否可直接解构——这些细节一错，代码就静默失效。

toRef：专为“不确定是否存在”的单个属性设计

它不关心源对象是不是 reactive，甚至不强制要求属性当前存在。只要传入对象和属性名，就返回一个 ref，其 .value 始终与源对象该属性双向绑定；如果属性不存在，ref.value 就是 undefined（也可用第三个参数设默认值）。

• 适用场景：从 props、外部传入的普通对象、或可能动态添加字段的 reactive 对象中，安全提取某一个字段
• 典型写法：const nameRef = toRef(person, 'name') 或 const sexRef = toRef(person, 'sex', '未知')
• 注意：不能直接解构赋值成 const { name } = toRef(...)，因为 toRef 只返回一个 ref，不是对象

toRefs：专为“已知结构”的 reactive 对象批量解构而生

它只接受 reactive（或 shallowReactive）对象，且只会处理对象第一层已存在的可枚举属性。返回的是一个普通对象（非响应式），但它的每个属性都是 ref —— 所以能安全解构，且保持响应性。

• 适用场景：组合式函数 return 的状态对象、setup 中对 reactive 数据做模板级解构
• 典型写法：const { name, age } = toRefs(person)，之后在模板或 JS 中用 name.value 修改
• 注意：如果 person 缺少 age 属性，toRefs(person) 不会报错，但解构出的 age 是 undefined（不是 ref），后续 .value 会报错

新手最容易踩的三个坑

第一，把 toRefs 用在普通对象上——它对非 reactive 源对象无效，不会建立响应式连接；第二，解构 toRefs 结果后忘记加 .value，比如写成 name = '新名字' 而不是 name.value = '新名字'；第三，以为 toRef 能批量用，结果写成 toRef(obj, ['a', 'b'])，这会直接报错，批量只能用 toRefs。

立即学习“前端免费学习笔记（深入）”；

一句话记住核心差异

toRef 是“按需创建单个引用”，toRefs 是“一键打包所有已有属性的引用”。前者灵活容错，后者高效规范，选哪个，取决于你面对的是“不确定的字段”还是“确定的结构”。