在 Vue 3 的 Composition API 中，toRef 和 toRefs 是处理响应式对象解构时的关键工具。许多开发者在使用 reactive 创建状态后，习惯性地尝试通过解构来提取变量，却发现响应性丢失。本节将深入源码层面，剖析这一“隐形陷阱”的成因，并揭示 toRef 与 toRefs 如何从根本上解决问题。

一、问题重现：解构为何会丢失响应性？

考虑以下代码：

import { reactive } from 'vue';

const state = reactive({ count: 0, name: 'Vue' });

// 尝试解构
const { count } = state;

// 在模板或 effect 中使用 count
console.log(count); // 0

此时，count 是一个普通的数字变量，而非响应式引用。即使后续 state.count 被修改，count 的值也不会自动更新。响应性“丢失”了。

要理解这一现象，我们必须回到 reactive 的实现机制。

二、响应式的本质：依赖收集与 Proxy 拦截

reactive 的核心是 Proxy。当一个对象被 reactive 包装后，它变成一个 Proxy 实例。这个 Proxy 拦截了所有属性的读取（get）和设置（set）操作。

在 get 拦截器中，Vue 会执行依赖收集（track）：

const get = (target, key, receiver) => {
  const result = Reflect.get(target, key, receiver);
  track(target, key); // 收集当前 activeEffect 作为依赖
  return isObject(result) ? reactive(result) : result;
};

关键点在于：依赖收集发生在属性访问的那一刻。只有通过 Proxy 访问属性，get 拦截器才会被触发，从而执行 track。

当我们执行 const { count } = state 时，JavaScript 引擎实际上是在进行属性读取：

const count = state.count; // 触发 get 拦截器，track 被调用

这一步确实触发了 get，也执行了 track。但 track 收集的依赖是针对 state.count 这个属性的。然而，count 变量本身只是一个普通变量，它与 state.count 之间没有持续的引用关系。track 收集的是当前正在运行的副作用函数（effect），而不是 count 变量。

如果这个解构发生在 setup 函数中，而 setup 并不是一个响应式副作用（它只执行一次），那么实际上没有有效的依赖被收集。即使有，count 作为一个局部变量，也无法在 state.count 变化时被自动更新。

更关键的是，解构后的 count 不再是 state 的一部分，后续对 count 的修改（如 count++）只是修改局部变量，完全绕过了 Proxy 的 set 拦截器，因此不会触发 trigger，视图也不会更新。

三、toRef：创建到响应式属性的引用

toRef 的作用是为响应式对象的某个属性创建一个 ref，这个 ref 与源对象的属性保持同步。

const state = reactive({ count: 0 });
const countRef = toRef(state, 'count');

countRef.value++; // 等价于 state.count++
state.count++;    // countRef.value 也会更新

从源码角度看，toRef 返回的 ref 并非简单的包装，而是一个“代理 ref”：

function toRef(object, key) {
  return {
    __v_isRef: true,
    get value() {
      return object[key]; // 读取源对象属性，触发 reactive 的 get
    },
    set value(newVal) {
      object[key] = newVal; // 设置源对象属性，触发 reactive 的 set
    }
  };
}

这里的关键在于：

• 读取 countRef.value 时，会触发 object[key] 的读取，进而触发 reactive 的 get 拦截器，执行 track。
• 设置 countRef.value 时，会触发 object[key] 的设置，进而触发 reactive 的 set 拦截器，执行 trigger。

因此，toRef 创建的 ref 与源对象的属性是双向绑定的。它既保留了响应性，又提供了 ref 的统一接口。

四、toRefs：批量转换为响应式引用

在实际开发中，我们往往需要解构整个响应式对象。toRefs 就是为此而生：

const state = reactive({ count: 0, name: 'Vue' });
const stateRefs = toRefs(state);

// 现在可以安全解构
const { count, name } = stateRefs;

// count 和 name 都是 ref
count.value++; // 响应式更新

toRefs 的实现本质上是对对象的每个属性调用 toRef：

function toRefs(object) {
  const result = {};
  for (const key in object) {
    result[key] = toRef(object, key);
  }
  return result;
}

这样，stateRefs 中的每个属性都是一个 ref，它们都指向 state 的对应属性。解构这些 ref 不会丢失响应性，因为 .value 的访问会通过 toRef 的 getter/setter 桥接到原始的 reactive 对象。

五、为什么不能自动解包嵌套 ref？

你可能会问：既然模板能自动解包根级 ref，为什么不能自动解包 toRefs 解构后的 ref？

答案是：JavaScript 的解构赋值无法被拦截。

模板中的自动解包是由 Vue 的编译器在编译时实现的。编译器知道 setup 返回的对象结构，可以静态分析并生成解包代码。

而 const { count } = toRefs(state) 是纯粹的 JavaScript 运行时行为。JavaScript 引擎在执行解构时，只是简单地将 toRefs(state).count 的值（一个 ref 对象）赋给 count 变量。这个过程无法被 Vue 拦截或修改。

因此，开发者必须显式地通过 .value 来访问 ref 的值，这是语言层面的限制所决定的。

六、设计哲学：显式优于隐式

toRef 和 toRefs 的存在，体现了 Vue 响应式系统的一个重要设计原则：在运行时保持显式性。

• reactive 提供“透明”的响应式，适合在作用域内部直接操作对象。
• ref 提供“显式”的响应式，通过 .value 明确标识响应式读写。
• toRef / toRefs 在两者之间架起桥梁，允许我们将 reactive 对象的属性转换为可安全解构的 ref。

这种设计避免了魔法般的隐式行为，使数据流更加清晰可预测。虽然多了一层 .value，但它清晰地告诉开发者：“此处正在进行响应式操作”。

七、总结

const { count } = state 丢失响应性的根本原因在于：解构操作将响应式属性的值提取为普通变量，切断了与源对象的响应式连接。get 拦截器虽被触发，但无法建立持续的依赖关系。

toRef 通过创建一个代理 ref，将读写操作转发回源对象，重建了响应式连接。toRefs 则批量应用这一模式，使得解构 reactive 对象成为安全的操作。

理解这一机制，不仅能避免常见的响应性陷阱，更能深入把握 Vue 3 响应式系统中“引用”与“代理”的核心思想。