如果你用 Vue 3 写过一段时间的业务代码大概率碰到过这种情况用reactive定义了一个对象模板里怎么用都正常结果在 script 里一解构视图就不跟手了——数据确实变了页面纹丝不动。我第一次遇到时还以为是 Vue 的生命周期问题翻了一圈文档才发现解构出来的变量已经不是原来的响应式属性了。这个问题的标准解药就是今天要讲的toRefs和toRef。这两个 API 是 Vue 3 Composition API 里最容易被人拿着当咒语用的工具大家知道它能保住响应性但很少有人讲清楚它到底是怎么保的、边界在哪、什么时候该用它、什么时候用了反而多余。这篇就围绕它们写透从原理到实战到坑一条龙讲明白。1. 先用一个真实场景看看 reactive 解构后为什么变哑1.1 十行代码复现响应性丢失先看一段最典型的翻车代码import { reactive } from vue const state reactive({ count: 0, name: Vue3 }) // 直接解构 const { count, name } state // 修改 count视图不会更新 function increase() { count 1 console.log(count:, count) console.log(state.count:, state.count) }跑起来之后你会发现很有意思打印出来的count已经自增了state.count也自增了但页面上绑定的count纹丝不动。如果你把页面模板写成{{ count }}那就更直接了——根本不会更新。原因一句话就能说清reactive返回的是一个Proxy代理对象你对它做的读写操作都会被拦截从而触发依赖收集和更新派发。但解构的行为是——把代理对象上当前属性的值拷贝到新的普通变量里。这个拷贝出来的count是一个普通数字后续再怎么改跟原来的代理对象没有任何关系。为了更直观你可以在组件里加一个按钮来触发increase再配合 Vue DevTools 看state.count的变化。你会看到 state 里的数据确实在变但页面上那个绑定count的地方永远停留在初始值。这其实不是 Bug而是解构这个 JavaScript 行为本身的特性。1.2 代理对象和值快照之间的本质差异要彻底理解这个问题得把 JavaScript 的对象访问机制掰开看。reactive的本质是拦截对象的属性读取和写入。你可以把它想象成一台带遥控的主控台遥控器上的按钮连接着台内各条线路按一个钮对应线路就通电。而解构操作相当于——你把遥控器面板上的每个按钮扣下来当纪念品带走这些按钮离开了主控台后面再怎么按当然是没有任何线路反应的。从数据层面讲就是const { count } state // 等价于 const count state.count这一步执行的时候count拿到的是当前值之后你就是把金条堆上去也改变不了state.count的值。反过来你在state.count上做修改这个普通变量也感知不到。更有迷惑性的是如果你在模板里直接用state.count它又是好的。因为模板里的state还是那个代理对象读取时走的是Proxy的get拦截依赖依然被正确收集。所以很多人一开始会以为是 reactive 坏了其实它是被你解构的时候甩掉了。1.3 日常开发中最容易中招的三个位置结合我自己的项目和身边同事踩过的坑响应性丢失不是偶发现象它高频出现在下面几个位置组合式函数返回的对象被调用方解构。比如你封装了一个useUser内部用reactive存用户信息返回值里包含userInfo和一些方法。调用方拿到后习惯性地const { userInfo } useUser()这时候userInfo已经不是那个响应式代理了页面上引用它的地方全部断电。setup 内部把 reactive 对象的属性拆成普通变量再塞进watch或computed里。最常见的是const state reactive({ page: 1, pageSize: 10 }) const { page } state watch(page, () { // 永远不触发因为 page 是个普通数字不是响应式引用 })把对象里的某个值提取出来传给普通函数。比如getArticle(state.id)如果这个函数内部只是按值使用那没问题但如果它内部把这个参数再喂给watch或者存进组合式函数里响应性就断了。这三种情况看着不一样本质完全相同你把一个原本活在响应系统里的值复制成了一块脱离电网的孤岛。理解到这个层面后面看toRefs和toRef就会非常清楚——它们做的就是一件事把孤岛重新接回电网。2. toRefs一键保住整个对象的解构能力2.1 基础用法与联动效果toRefs的定位很直白把一个响应式对象的所有属性都转换成独立的 ref并让这些 ref 和原对象保持联动。import { reactive, toRefs } from vue const state reactive({ count: 0, name: Vue3 }) const refs toRefs(state) // refs 结构: { count: Refnumber, name: Refstring } const { count, name } refs // 修改 ref原对象跟着变 count.value 10 console.log(state.count) // 10 // 修改原对象ref 也感知得到 state.name Vue4 console.log(name.value) // Vue4这里的核心效果是双向联动count.value改的是原对象上的属性state.count改的时候count.value读到的也是新值。因为ref本身是 Vue 响应系统的一部分所以解构出来的每个变量都能在你的模板、watch、computed里作为真正的响应式引用去使用。我在刚上手 Vue 3 的那段时间一直把toRefs理解成给对象安装一个解构安全壳后来写多了才意识到更好的理解方式是——toRefs把对象中的每个属性都变成了一条拉线线的另一头仍然连在原来的代理对象上你拉哪条线主控台对应的线路就跟着动。2.2 原理每个属性都是一座桥表面上toRefs做了一件很简单的事遍历对象的所有属性对每个属性调用一次toRef。但精髓在于toRef内部构造的那个 ref并不是简单地复制当前值而是自定义了读写操作。Vue 源码里对应的是一个叫ObjectRefImpl的类它的核心逻辑可以简化为class ObjectRefImpl { constructor(_object, _key) { this._object _object this._key _key } get value() { return this._object[this._key] } set value(newVal) { this._object[this._key] newVal } }也就是说这个 ref 实际上没有自己保存数据它的value读取永远通过this._object[this._key]去拿写入也永远是通过它写进原对象。所以当你const { count } toRefs(state)之后count这个 ref 的get value会跑去读state.count而state.count读取的是代理对象会触发依赖收集自然就把响应式链路完整接上了。这个设计非常巧妙它把保留响应性这个需求变成了保留属性访问能力。你不关心值在哪一步发生变更只要读写始终落在原代理对象上响应系统就能全程工作。2.3 模板与 script 中各自的使用姿势toRefs解构出来的变量是 ref所以它同时要遵守两条规则模板里自动解包。你不需要写.value{{ count }}会直接显示count.value的值。这是因为 Vue 3 模板渲染器遇到 ref 时会自动读取它的.value。script 里必须手动.value。count.value 10、console.log(name.value)漏掉.value你拿到的就是整个 ref 对象而不是里面的值。这两条规则刚入门时特别容易混尤其是从 Vue 2 切过来的朋友总是默认对象上直接取属性是安全的。我自己就出过这样的洋相在某个方法里写keyword.trim()结果keyword是 ref根本没有trim方法控制台报错报得我一脸懵。为了减少这类笔误有个小技巧如果只在模板里展示数据、在事件处理里通过方法修改状态那你完全可以放心解构。但如果要在 script 里频繁读取和赋值要么养成立刻加.value的肌肉记忆要么就干脆保留原来的state对象用state.count来访问。2.4 别忘了它只处理浅层toRefs触碰的只是对象的第一层属性。如果对象里嵌套了另一个对象情况要区分看const state reactive({ user: { name: 张三, age: 18 } }) const { user } toRefs(state) user.value.name 李四这里user是一个 ref它的value指向的是state.user。由于reactive是深度代理state.user本身也是一个代理对象所以user.value.name 李四依然能触发响应式更新。你不需要对嵌套对象再手动调一次toRefs它能用的原因是原对象深层的代理还没断。但如果你本来就用的是一个只做了浅层代理的shallowReactive对象那toRefs解构出来的嵌套对象就不会有深层响应性。这个看场景业务代码里 90% 用的都是深度reactive所以大多数情况下你不需要过度担心嵌套问题。还有一个隐含边界是toRefs返回的对象并没有被包装成响应式对象它只是一个普通对象里面的每个属性都是 ref。这意味着你不能给这个返回对象再添加新属性并且期望它响应式新增键必须以原对象为基准去初始化。3. toRef只保一个属性的响应性3.1 用法与典型场景toRef和toRefs是一对孪生工具区别在于toRefs一次性处理整个对象toRef只处理单个键import { reactive, toRef } from vue const state reactive({ count: 0, name: Vue3 }) const countRef toRef(state, count) countRef.value 5 console.log(state.count) // 5toRef最典型的使用场景是你手里已经有一个响应式对象但你只需要把其中一个属性传给别的地方去用又不想传整个对象。比如下面这个封装function useCountUp(sourceRef) { const doubled computed(() sourceRef.value * 2) function increase() { sourceRef.value 1 } return { doubled, increase } } const state reactive({ count: 0 }) const countRef toRef(state, count) const { doubled, increase } useCountUp(countRef)如果把state.count这个普通数值直接传进去里面基于它做的computed、watch全部失效。而传toRef(state, count)进去外部函数可以安全地读取、监听甚至可以在函数内修改这个 ref修改会直接反映到原对象上。3.2 props 与组合式函数toRef 的黄金搭档如果说toRefs是组合式函数返回值解构的标准答案那么toRef就是 props 单属性传递的默认姿势。在script setup里props本身是响应式的但如果你把它解构成普通变量就会切断响应链// 错误示范解构 props 导致响应性丢失 const { id, visible } defineProps([id, visible])正确的做法是const props defineProps([id, visible]) // 需要用响应式引用时用 toRef 单独取 const idRef toRef(props, id) const visibleRef toRef(props, visible) watch(idRef, (val) { // 有效 })这个模式在你封装通用组件时非常有用。比如写一个分页组件父组件传currentPage进来子组件内部要监听它的变化去请求数据就可以用toRef(props, currentPage)接住然后传给内部封装的组合式函数。需要提醒一点props在 Vue 3 中是只读的单向数据流约束。用toRef包装后虽然技术上你可以给它赋值因为ObjectRefImpl的setter会写回原对象但这样做会破坏组件数据流的约定应该通过emit通知父组件去修改。toRef在这里的正确用法是读取和监听而不是改造。3.3 toRef 和 ref 到底哪里不同这是很多人都会搞混的一对概念。ref创建一个自有的响应式变量它内部自己存值toRef创建一个桥接的响应式引用它的值始终来自目标对象。举一个生活化的例子ref相当于你自己办了一张独立的银行卡钱在自己账户里toRef相当于办理了一张主卡的副卡主卡账户动一毛钱副卡余额就变一毛钱。具体到代码const state reactive({ num: 1 }) const refNum ref(state.num) // 独立变量初始值是 1后续与 state.num 无关 const toRefNum toRef(state, num) // 桥接引用始终对应 state.num state.num 100 console.log(refNum.value) // 1不变 console.log(toRefNum.value) // 100跟着变这个差异的实践意义很大。如果你在某个组件里用ref(state.count)去拷贝一个响应式值后面原对象更新了你的 ref 还停留在旧值上容易引发隐蔽的数据不一致问题。判断标准很简单你希望这个新变量跟原对象保持联动吗希望就用toRef不希望说明你本来就要一个独立副本那就用ref。4. 两者放在一起选型对比与源码关系4.1 一张表把差异说清楚与其记一堆零散结论不如直接看下面这张对比表维度toRefstoRef输入一个响应式对象一个响应式对象 一个键名输出新对象所有属性均为 ref单个 ref典型场景组合式函数返回对象后整体解构从对象中取某一个属性单独传递/监听对原对象的引用所有生成的 ref 都保持桥接生成的单个 ref 保持桥接数组支持支持返回等长数组支持key 为数字索引是否改变原对象结构不改变不改变用一句话总结选型逻辑要解构一个对象的多个属性用toRefs只需要拿走一个属性并保持响应性用toRef。后者本质上也是前者内部实现的基本单位。4.2 源码视角toRefs 就是循环调用 toRef前面提到toRefs的核心实现就是遍历对象所有可枚举属性逐一调用toRef。你可以在 Vue 的 reactivity 源码里看到非常直接的代码去掉类型标注和边界处理后的简化版大概是这样export function toRefs(object) { const ret Array.isArray(object) ? new Array(object.length) : {} for (const key in object) { ret[key] toRef(object, key) } return ret }所以你在使用时完全可以认为toRefs(obj)等价于对 obj 的每个 key 手动执行toRef然后把结果放进一个新对象。这也解释了为什么说第四章里的对比表其实根本没有冲突——toRefs是toRef的批量升级版。再看toRef本身的实现逻辑它有一个很贴心的处理如果目标属性本身已经是 ref它会直接把它原样返回不会套一层再套一层。所以你在业务里反复调用toRef不会产生额外的性能损耗因为获得的引用可能是同一个。这也意味着toRefs和toRef在组合使用时很安全。4.3 用在普通对象上会发生什么toRefs和toRef并不要求输入必须是reactive创建的对象普通对象也一样能接收。区别在于普通对象上没有 Proxy 拦截桥接的 ref 修改值时虽然原对象会被同步改动但不会触发任何视图更新——因为没有响应系统在背后监听。const plain { a: 1 } const refA toRef(plain, a) refA.value 2 console.log(plain.a) // 2但没有任何组件会因为这次修改而更新这在某些场景下是有用的比如你想让两个普通变量共享同一份数据又不想引入 Vue 的响应系统干预。但业务代码里这种需求非常少大多数时候你还是希望修改触发页面更新的。所以请记住一句toRef / toRefs 的价值主要绑定在响应式对象上用在普通对象上它们退化成普通的共享引用工具。5. 实战重构一个搜索模块的演进过程5.1 原始版本组合式函数返回值被解构后失效为了把这两个 API 用活我拿一个真实项目中常见的搜索模块来完整走一遍。这是我认为最有教学价值的例子因为它几乎涵盖了所有和toRefs、toRef相关的问题形态。最初我写的版本是这样// composables/useSearch.js import { reactive } from vue import { fetchList } from /api export function useSearch() { const state reactive({ keyword: , page: 1, pageSize: 10, total: 0, loading: false, list: [] }) async function search() { state.loading true try { const res await fetchList({ keyword: state.keyword, page: state.page, pageSize: state.pageSize }) state.list res.list state.total res.total } finally { state.loading false } } function reset() { state.keyword state.page 1 state.pageSize 10 state.list [] state.total 0 } return { state, search, reset } }页面组件里我一开始是这样用的const { state, search, reset } useSearch() const { keyword, page, pageSize, loading, list, total } state这段代码跑起来之后页面初始化能正常渲染一次但只要search()跑完loading也好、list也好全都不会驱动视图更新。我当初排查了很久才发现问题就出在最后这行解构——它把state这个代理对象里的一堆普通值拷了出来导致后面search里改state.list页面读的list却还是旧拷贝。5.2 第一次重构toRefs 保留整体响应性修复思路非常直接把返回值里的状态部分改成由toRefs处理之后展开。import { reactive, toRefs } from vue export function useSearch() { const state reactive({ keyword: , page: 1, pageSize: 10, total: 0, loading: false, list: [] }) async function search() { /* 保持不变 */ } function reset() { /* 保持不变 */ } return { search, reset, ...toRefs(state) } }组件里就可以安全解构了const { keyword, page, pageSize, loading, list, total, search, reset } useSearch() watch([keyword, page], () { search() })注意这里keyword、page都是 ref所以它们可以直接放进watch的数组里。loading、list在模板里也都是自动解包的页面上完全不用写.value只有 script 逻辑中操作它们时要留意。这套重构之后搜索模块的响应式链路就通了。改动其实就一处返回值从{ state }变成了{ ...toRefs(state) }但体验差异巨大。现在组件里不再需要到处抱着state这个累赘解构出来的每个状态都直接可读可监听。5.3 第二次重构toRef 接管外部参数模块化往往会在这一步遇到新需求useSearch需要接收外部传入的默认关键字。你希望父组件传一个 ref 进来子模块既能读它的初始值又能监听它后续变化。这时候就轮到toRef出场。export function useSearch(externalKeywordRef) { const state reactive({ keyword: externalKeywordRef.value || , // ...其他状态 }) // 外部传入的响应式引用发生变化时同步到内部状态 watch(externalKeywordRef, (val) { state.keyword val }) // ... }更常见的组合是把toRef用在父子组件 props 上。比如搜索框子组件接收父组件传的modelValue// SearchInput.vue const props defineProps({ modelValue: String }) const emit defineEmits([update:modelValue]) // 拿到响应式引用便于内部逻辑监听 const valueRef toRef(props, modelValue) watch(valueRef, (val) { // 每次父组件传入的 modelValue 变化时做一些联动 console.log(外部值变为:, val) }) function onInput(e) { emit(update:modelValue, e.target.value) }这个场景里如果直接const value props.modelValue监听就失效了但如果用toRefs(props)再解构语法上没问题却略显冗余。toRef(props, modelValue)在语义上更精准我只需要这一个属性保持响应性那恰好就是toRef的价值所在。6. 容易踩的坑和我现在的使用习惯6.1 几个文档边角里写着但不醒目的坑这两个 API 表面上简单实际使用中还是有几个隐蔽的坑我逐个列出来都是真实项目中触发过的。坑一对 ref 对象调用 toRefs 会得到空结果。ref实例和普通对象不同它的value属性是定义在原型上的访问器for...in遍历不到所以toRefs(ref({ a: 1 }))的结果往往是空对象。如果你需要把 ref 内部的对象拆开用应该先toRefs(refObj.value)。坑二toRef 创建的 ref在模板中自动解包。这一点和普通ref一致但很多人会误以为toRef返回的是一个对象属性引用在模板里写{{ user.name }}却拿到undefined。实际上user是 ref模板里应该写{{ user.value.name }}除非你把toRef的结果直接包一层解包。Vue 3 的模板对顶层 ref 自动解包嵌套在对象内的 ref 则不一定解包这个要小心。坑三toRefs 不会转换对象中原本不是响应式的属性。比如你在一个 reactive 对象里塞入了普通对象toRefs只会把这个普通对象整体变成一个 ref它内部如果再变是检测不到的。要深层次响应你必须保证原始对象里的结构是用reactive或ref层层包裹过的。坑四用 toRef 给 props 赋值要克制。前面写过props的事后赋值会绕过单向数据流虽然不是技术上做不到但代码 review 阶段一定会被红字标出。规范做法始终是emit告知父组件去改。6.2 我实践下来的推荐写法踩过这些坑之后我现在写项目的习惯基本稳定成了一套规则第一组合式函数对外返回状态时默认就...toRefs(state)不再整体返回state。这样调用方可以自由选择解构粒度也不会踩响应性丢失的雷。第二单属性的响应性传递一律用toRef不为省一行代码去给整个对象做无谓转换。比如某个组件只需要props.visible的响应性那就toRef(props, visible)就够不需要toRefs(props)然后把其它属性也拉出来。第三我会刻意区分需要联动的引用和一次性快照两种需求。外部传入一个值后续要监听它的变化就用toRef只需要一个初始快照用它初始化本地状态就行这时候用ref(props.xxx)反而是正确的——因为我不希望本地修改回过头污染父组件的数据。第四如果是 Vue 3.3 的项目可以关注一下toRefs在泛型推导上的增强类型上更精确了但用法没有变化。老项目的写法在过去完全通用。最后再分享一个我在代码 review 中常用的快速判断法看到有人const x state.xxx然后把x用于watch、computed或模板绑定我就会多问一句这个x后面需要跟着响应式联动吗如果需要请写成toRef(state, xxx)如果不需要那你为什么要从一个响应式对象里取值考虑是不是应该用ref独立声明。 这一问在绝大多数情况下都能提前挡住响应性丢失的隐患。这两个 API 其实没有多少魔法核心就是把属性访问桥接回原对象这一件事。你只要记住这个原理再遇到任何响应性断裂的问题都能沿着这条线索自己推出来答案。