在 Vue 3 的 Composition API 里，`ref` 和 `reactive` 是最常用的两个响应式声明方式。实际开发中常遇到一种情况：把 `reactive` 对象的某个属性重新赋值后，模板不更新；或者从 `setup` 返回一个 `ref` 后，在模板里不加 `.value` 就能用，但换到 `reactive` 对象里嵌套的 `ref`，行为又不一样。这些差异并不来自响应式系统本身，而是 Vue 对模板表达式做了一层“自动解包”的编译处理。理解这层机制能避开很多“数据改了页面没动”的问题，也能解释为什么在 `watch` 里拿到的是原始 ref 而在模板里拿到的是值。下面从模板编译、运行时解包和常见错误场景拆开说。

## 模板里 ref 自动解包是编译阶段做的事

Vue 3 的模板会被编译成渲染函数，模板里访问一个顶层 ref 时，编译器会生成 `unref` 调用或类似的解包逻辑。也就是说，你写 `{{ count }}`，最终执行的不是 `count.value`，而是编译后的 `_unref(count)`。这个行为只对渲染上下文顶层的 ref 生效。

```vue
<script setup>
import { ref } from 'vue'
const count = ref(0)
</script>

<template>
 {{ count }}
 <button @click="count++">+1</button>
</template>
```

这里的 `count++` 在模板里能直接工作，是因为编译器把它当成 `count.value++` 处理了。但如果你把这个 ref 放进一个 `reactive` 对象里，情况会变。

## reactive 对象内的 ref 只在顶层属性解包

`reactive` 对 ref 的解包规则是：只有作为对象的直接属性时才会解包。嵌套深一层，或者把 ref 放到数组里，都不会自动解包。

```js
import { reactive, ref } from 'vue'

const state = reactive({
 count: ref(0),
 nested: {
 inner: ref(10)
 },
 list: [ref(100)]
})

state.count // 0，顶层属性已解包
state.nested.inner // RefImpl，没有解包
state.list[0] // RefImpl，没有解包
```

在模板中同样遵循这个规则。`{{ state.count }}` 可以正常显示，但 `{{ state.nested.inner }}` 会渲染成一个对象字符串，需要写成 `{{ state.nested.inner.value }}`。这个差异经常在从接口拿数据后构造嵌套结构时踩到。

## 从 setup 返回时解包规则又不一样

如果用 `setup()` 选项而不是 `<script setup>`，返回一个包含 ref 的对象时，Vue 会对顶层属性做一次浅解包。但如果返回的是 `reactive` 对象，里面的 ref 不会再被额外处理。

```js
export default {
 setup() {
 const count = ref(0)
 const state = reactive({
 inner: ref(1)
 })
 return { count, state }
 }
}
```

模板里 `{{ count }}` 能直接用，`{{ state.inner }}` 也能直接用，因为 `state` 本身是 reactive 的，`inner` 是它的顶层属性。如果返回的是 `{ state: { inner: ref(1) } }` 这种普通对象，模板里 `{{ state.inner }}` 就不会解包。这个边界很容易在重构时弄混。

## watch 里拿到的是 ref 本身

一个常见错误是在 `watch` 里监听 `reactive` 对象上的 ref 属性，然后期望拿到值，结果拿到的是 RefImpl。

```js
const state = reactive({
 count: ref(0)
})

watch(() => state.count, (val) => {
 console.log(val) // 0，这里已经是值
})

watch(state, (val) => {
 console.log(val.count) // RefImpl，不是数字
})
```

当 watch 的第一个参数是 getter 函数时，Vue 会对返回值做解包；当直接传 reactive 对象时，回调里拿到的是原始对象，属性上的 ref 不会被解包。要拿值需要显式 `.value`。

## 在模板中给 reactive 的 ref 属性赋值

模板里给 `state.count = 1` 这种写法，如果是顶层 ref 属性，Vue 的响应式代理会拦截 set 并自动写到 ref 的 `.value` 上。但嵌套属性不行，因为嵌套对象没有被 reactive 代理（除非整个嵌套对象也是 reactive 的）。

```js
const state = reactive({
 nested: {
 inner: ref(0)
 }
})

state.nested.inner = 5 // 直接替换了 ref 对象，丢失响应性
state.nested.inner.value = 5 // 正确
```

这里 `state.nested` 是普通对象，Vue 不会递归把里面的 ref 转成响应式代理，所以直接赋值会破坏原有的 ref 引用。修复方式是把 `nested` 也声明成 `reactive`，或者干脆用 `ref` 包裹整个嵌套结构。

## 组合式函数里返回 ref 还是 reactive

写 composable 时，如果返回一个包含多个 ref 的普通对象，调用方在模板里使用需要小心解包层级。比较稳妥的做法是返回 `reactive` 对象，或者返回 ref 并在调用方用 `toRefs` 展开。

```js
// composable
import { reactive, toRefs } from 'vue'

export function useCounter() {
 const state = reactive({ count: 0, step: 1 })
 function increment() {
 state.count += state.step
 }
 return { ...toRefs(state), increment }
}
```

这样调用方拿到的 `count` 和 `step` 都是 ref，在模板顶层能自动解包，在 JS 里也能通过 `.value` 读写，不会因为嵌套 reactive 导致解包失效。

## 什么时候该用 ref 什么时候用 reactive

从解包规则反推：需要整体替换的对象用 `ref`，因为 `reactive` 直接赋值会丢失响应性；需要频繁访问深层属性且不希望到处写 `.value` 的用 `reactive`，但要注意嵌套 ref 不解包。团队协作里更常见的约定是统一用 `ref`，在模板顶层自动解包，在逻辑里显式 `.value`，减少心智负担。

```js
const user = ref({ name: 'a', tags: [] })
user.value = { name: 'b', tags: [] } // 可以整体替换
```

如果换成 `reactive`，整体替换后原来的代理对象就断了，模板不会再更新。这不是 bug，是 Proxy 的工作方式决定的。

把模板解包、reactive 嵌套解包、watch 取值、赋值行为这几处放在一起看，能解释大部分“响应式失效”的现场。真正写业务时，选一种风格并保持一致性，比记住所有边界情况更省事。

 推荐查看天气：https://www.0dtq.com/jiancaoping/
 推荐查看天气：https://www.0dtq.com/jiancaoping/zuotian.html
 推荐查看天气：https://www.0dtq.com/jiancaoping/7tian.html
 推荐查看天气：https://www.0dtq.com/jiancaoping/10tian.html
 推荐查看天气：https://www.0dtq.com/jiancaoping/15tian.html
 推荐查看天气：https://www.0dtq.com/jiancaoping/40tian.html
 推荐查看天气：https://www.0dtq.com/wanbailin/
 推荐查看天气：https://www.0dtq.com/wanbailin/zuotian.html
 推荐查看天气：https://www.0dtq.com/wanbailin/7tian.html
 推荐查看天气：https://www.0dtq.com/wanbailin/10tian.html
 推荐查看天气：https://www.0dtq.com/wanbailin/15tian.html
 推荐查看天气：https://www.0dtq.com/wanbailin/40tian.html
 推荐查看天气：https://www.0dtq.com/jinyuan/
 推荐查看天气：https://www.0dtq.com/jinyuan/zuotian.html
 推荐查看天气：https://www.0dtq.com/jinyuan/7tian.html
 推荐查看天气：https://www.0dtq.com/jinyuan/10tian.html
 推荐查看天气：https://www.0dtq.com/jinyuan/15tian.html
 推荐查看天气：https://www.0dtq.com/jinyuan/40tian.html
 推荐查看天气：https://www.0dtq.com/qingxu/
 推荐查看天气：https://www.0dtq.com/qingxu/zuotian.html
 推荐查看天气：https://www.0dtq.com/qingxu/7tian.html
 推荐查看天气：https://www.0dtq.com/qingxu/10tian.html
 推荐查看天气：https://www.0dtq.com/qingxu/15tian.html
 推荐查看天气：https://www.0dtq.com/qingxu/40tian.html
 推荐查看天气：https://www.0dtq.com/yangqu/
 推荐查看天气：https://www.0dtq.com/yangqu/zuotian.html
 推荐查看天气：https://www.0dtq.com/yangqu/7tian.html
 推荐查看天气：https://www.0dtq.com/yangqu/10tian.html
 推荐查看天气：https://www.0dtq.com/yangqu/15tian.html
 推荐查看天气：https://www.0dtq.com/yangqu/40tian.html
 推荐查看天气：https://www.0dtq.com/loufan/
 推荐查看天气：https://www.0dtq.com/loufan/zuotian.html
 推荐查看天气：https://www.0dtq.com/loufan/7tian.html
 推荐查看天气：https://www.0dtq.com/loufan/10tian.html
 推荐查看天气：https://www.0dtq.com/loufan/15tian.html
 推荐查看天气：https://www.0dtq.com/loufan/40tian.html
 推荐查看天气：https://www.0dtq.com/gujiao/
 推荐查看天气：https://www.0dtq.com/gujiao/zuotian.html
 推荐查看天气：https://www.0dtq.com/gujiao/7tian.html
 推荐查看天气：https://www.0dtq.com/gujiao/10tian.html
 推荐查看天气：https://www.0dtq.com/gujiao/15tian.html
 推荐查看天气：https://www.0dtq.com/gujiao/40tian.html
 推荐查看天气：https://www.0dtq.com/datongshi/
 推荐查看天气：https://www.0dtq.com/datongshi/zuotian.html
 推荐查看天气：https://www.0dtq.com/datongshi/7tian.html
 推荐查看天气：https://www.0dtq.com/datongshi/10tian.html
 推荐查看天气：https://www.0dtq.com/datongshi/15tian.html
 推荐查看天气：https://www.0dtq.com/datongshi/40tian.html
 推荐查看天气：https://www.0dtq.com/nanjiao/
 推荐查看天气：https://www.0dtq.com/nanjiao/zuotian.html
 推荐查看天气：https://www.0dtq.com/nanjiao/7tian.html
 推荐查看天气：https://www.0dtq.com/nanjiao/10tian.html
 推荐查看天气：https://www.0dtq.com/nanjiao/15tian.html
 推荐查看天气：https://www.0dtq.com/nanjiao/40tian.html
 推荐查看天气：https://www.0dtq.com/xinrong/
 推荐查看天气：https://www.0dtq.com/xinrong/zuotian.html
 推荐查看天气：https://www.0dtq.com/xinrong/7tian.html
 推荐查看天气：https://www.0dtq.com/xinrong/10tian.html
 推荐查看天气：https://www.0dtq.com/xinrong/15tian.html
 推荐查看天气：https://www.0dtq.com/xinrong/40tian.html
 推荐查看天气：https://www.0dtq.com/yanggao/
 推荐查看天气：https://www.0dtq.com/yanggao/zuotian.html
 推荐查看天气：https://www.0dtq.com/yanggao/7tian.html
 推荐查看天气：https://www.0dtq.com/yanggao/10tian.html
 推荐查看天气：https://www.0dtq.com/yanggao/15tian.html
 推荐查看天气：https://www.0dtq.com/yanggao/40tian.html
 推荐查看天气：https://www.0dtq.com/tianzhen/
 推荐查看天气：https://www.0dtq.com/tianzhen/zuotian.html
 推荐查看天气：https://www.0dtq.com/tianzhen/7tian.html
 推荐查看天气：https://www.0dtq.com/tianzhen/10tian.html
 推荐查看天气：https://www.0dtq.com/tianzhen/15tian.html
 推荐查看天气：https://www.0dtq.com/tianzhen/40tian.html
 推荐查看天气：https://www.0dtq.com/datongguangling/
 推荐查看天气：https://www.0dtq.com/datongguangling/zuotian.html
 推荐查看天气：https://www.0dtq.com/datongguangling/7tian.html
 推荐查看天气：https://www.0dtq.com/datongguangling/10tian.html
 推荐查看天气：https://www.0dtq.com/datongguangling/15tian.html
 推荐查看天气：https://www.0dtq.com/datongguangling/40tian.html
 推荐查看天气：https://www.0dtq.com/lingqiu/
 推荐查看天气：https://www.0dtq.com/lingqiu/zuotian.html
 推荐查看天气：https://www.0dtq.com/lingqiu/7tian.html
 推荐查看天气：https://www.0dtq.com/lingqiu/10tian.html
 推荐查看天气：https://www.0dtq.com/lingqiu/15tian.html
 推荐查看天气：https://www.0dtq.com/lingqiu/40tian.html
 推荐查看天气：https://www.0dtq.com/hunyuan/
 推荐查看天气：https://www.0dtq.com/hunyuan/zuotian.html
 推荐查看天气：https://www.0dtq.com/hunyuan/7tian.html
 推荐查看天气：https://www.0dtq.com/hunyuan/10tian.html
 推荐查看天气：https://www.0dtq.com/hunyuan/15tian.html
 推荐查看天气：https://www.0dtq.com/hunyuan/40tian.html
 推荐查看天气：https://www.0dtq.com/zuoyun/
 推荐查看天气：https://www.0dtq.com/zuoyun/zuotian.html
 推荐查看天气：https://www.0dtq.com/zuoyun/7tian.html
 推荐查看天气：https://www.0dtq.com/zuoyun/10tian.html
 推荐查看天气：https://www.0dtq.com/zuoyun/15tian.html
 推荐查看天气：https://www.0dtq.com/zuoyun/40tian.html
 推荐查看天气：https://www.0dtq.com/datongxian/
 推荐查看天气：https://www.0dtq.com/datongxian/zuotian.html
 推荐查看天气：https://www.0dtq.com/datongxian/7tian.html
 推荐查看天气：https://www.0dtq.com/datongxian/10tian.html
 推荐查看天气：https://www.0dtq.com/datongxian/15tian.html
 推荐查看天气：https://www.0dtq.com/datongxian/40tian.html
 推荐查看天气：https://www.0dtq.com/yangquan/
 推荐查看天气：https://www.0dtq.com/yangquan/zuotian.html
 推荐查看天气：https://www.0dtq.com/yangquan/7tian.html
 推荐查看天气：https://www.0dtq.com/yangquan/10tian.html
 推荐查看天气：https://www.0dtq.com/yangquan/15tian.html
 推荐查看天气：https://www.0dtq.com/yangquan/40tian.html
 推荐查看天气：https://www.0dtq.com/kuangqu/
 推荐查看天气：https://www.0dtq.com/kuangqu/zuotian.html
 推荐查看天气：https://www.0dtq.com/kuangqu/7tian.html
 推荐查看天气：https://www.0dtq.com/kuangqu/10tian.html
 推荐查看天气：https://www.0dtq.com/kuangqu/15tian.html
 推荐查看天气：https://www.0dtq.com/kuangqu/40tian.html
 推荐查看天气：https://www.0dtq.com/pingding/
 推荐查看天气：https://www.0dtq.com/pingding/zuotian.html
 推荐查看天气：https://www.0dtq.com/pingding/7tian.html
 推荐查看天气：https://www.0dtq.com/pingding/10tian.html
 推荐查看天气：https://www.0dtq.com/pingding/15tian.html
 推荐查看天气：https://www.0dtq.com/pingding/40tian.html
 推荐查看天气：https://www.0dtq.com/yuxian/
 推荐查看天气：https://www.0dtq.com/yuxian/zuotian.html
 推荐查看天气：https://www.0dtq.com/yuxian/7tian.html
 推荐查看天气：https://www.0dtq.com/yuxian/10tian.html
 推荐查看天气：https://www.0dtq.com/yuxian/15tian.html
 推荐查看天气：https://www.0dtq.com/yuxian/40tian.html
 推荐查看天气：https://www.0dtq.com/changzhi/
 推荐查看天气：https://www.0dtq.com/changzhi/zuotian.html
 推荐查看天气：https://www.0dtq.com/changzhi/7tian.html
 推荐查看天气：https://www.0dtq.com/changzhi/10tian.html
 推荐查看天气：https://www.0dtq.com/changzhi/15tian.html
 推荐查看天气：https://www.0dtq.com/changzhi/40tian.html
 推荐查看天气：https://www.0dtq.com/xiangyuan/
 推荐查看天气：https://www.0dtq.com/xiangyuan/zuotian.html
 推荐查看天气：https://www.0dtq.com/xiangyuan/7tian.html
 推荐查看天气：https://www.0dtq.com/xiangyuan/10tian.html
 推荐查看天气：https://www.0dtq.com/xiangyuan/15tian.html
 推荐查看天气：https://www.0dtq.com/xiangyuan/40tian.html
 推荐查看天气：https://www.0dtq.com/tunliu/
 推荐查看天气：https://www.0dtq.com/tunliu/zuotian.html
 推荐查看天气：https://www.0dtq.com/tunliu/7tian.html
 推荐查看天气：https://www.0dtq.com/tunliu/10tian.html
 推荐查看天气：https://www.0dtq.com/tunliu/15tian.html
 推荐查看天气：https://www.0dtq.com/tunliu/40tian.html
 推荐查看天气：https://www.0dtq.com/pingshun/
 推荐查看天气：https://www.0dtq.com/pingshun/zuotian.html
 推荐查看天气：https://www.0dtq.com/pingshun/7tian.html
 推荐查看天气：https://www.0dtq.com/pingshun/10tian.html
 推荐查看天气：https://www.0dtq.com/pingshun/15tian.html
 推荐查看天气：https://www.0dtq.com/pingshun/40tian.html
 推荐查看天气：https://www.0dtq.com/changzhilicheng/
 推荐查看天气：https://www.0dtq.com/changzhilicheng/zuotian.html
 推荐查看天气：https://www.0dtq.com/changzhilicheng/7tian.html
 推荐查看天气：https://www.0dtq.com/changzhilicheng/10tian.html
 推荐查看天气：https://www.0dtq.com/changzhilicheng/15tian.html
 推荐查看天气：https://www.0dtq.com/changzhilicheng/40tian.html
 推荐查看天气：https://www.0dtq.com/huguan/
 推荐查看天气：https://www.0dtq.com/huguan/zuotian.html
 推荐查看天气：https://www.0dtq.com/huguan/7tian.html
 推荐查看天气：https://www.0dtq.com/huguan/10tian.html
 推荐查看天气：https://www.0dtq.com/huguan/15tian.html
 推荐查看天气：https://www.0dtq.com/huguan/40tian.html
 推荐查看天气：https://www.0dtq.com/changzi/
 推荐查看天气：https://www.0dtq.com/changzi/zuotian.html
 推荐查看天气：https://www.0dtq.com/changzi/7tian.html
 推荐查看天气：https://www.0dtq.com/changzi/10tian.html
 推荐查看天气：https://www.0dtq.com/changzi/15tian.html
 推荐查看天气：https://www.0dtq.com/changzi/40tian.html
 推荐查看天气：https://www.0dtq.com/wuxiang/
 推荐查看天气：https://www.0dtq.com/wuxiang/zuotian.html
 推荐查看天气：https://www.0dtq.com/wuxiang/7tian.html
 推荐查看天气：https://www.0dtq.com/wuxiang/10tian.html
 推荐查看天气：https://www.0dtq.com/wuxiang/15tian.html
 推荐查看天气：https://www.0dtq.com/wuxiang/40tian.html
 推荐查看天气：https://www.0dtq.com/qinxian/
 推荐查看天气：https://www.0dtq.com/qinxian/zuotian.html
 推荐查看天气：https://www.0dtq.com/qinxian/7tian.html
 推荐查看天气：https://www.0dtq.com/qinxian/10tian.html
 推荐查看天气：https://www.0dtq.com/qinxian/15tian.html
 推荐查看天气：https://www.0dtq.com/qinxian/40tian.html
 推荐查看天气：https://www.0dtq.com/qinyuan/
 推荐查看天气：https://www.0dtq.com/qinyuan/zuotian.html
 推荐查看天气：https://www.0dtq.com/qinyuan/7tian.html
 推荐查看天气：https://www.0dtq.com/qinyuan/10tian.html
 推荐查看天气：https://www.0dtq.com/qinyuan/15tian.html
 推荐查看天气：https://www.0dtq.com/qinyuan/40tian.html
 推荐查看天气：https://www.0dtq.com/shuozhou/
 推荐查看天气：https://www.0dtq.com/shuozhou/zuotian.html
 推荐查看天气：https://www.0dtq.com/shuozhou/7tian.html
 推荐查看天气：https://www.0dtq.com/shuozhou/10tian.html
 推荐查看天气：https://www.0dtq.com/shuozhou/15tian.html
 推荐查看天气：https://www.0dtq.com/shuozhou/40tian.html
 推荐查看天气：https://www.0dtq.com/shuocheng/
 推荐查看天气：https://www.0dtq.com/shuocheng/zuotian.html
 推荐查看天气：https://www.0dtq.com/shuocheng/7tian.html
 推荐查看天气：https://www.0dtq.com/shuocheng/10tian.html
 推荐查看天气：https://www.0dtq.com/shuocheng/15tian.html
 推荐查看天气：https://www.0dtq.com/shuocheng/40tian.html
 推荐查看天气：https://www.0dtq.com/shuozhoupinglu/
 推荐查看天气：https://www.0dtq.com/shuozhoupinglu/zuotian.html

在 Vue 3 的 Composition API 里，ref 和 reactive 是最常用的两个响应式声明方式。实际开发中常遇到一种情况：把 reactive 对象的某个属性重新赋值后，模板不更新；或者从 setup 返回一个 ref 后，在模板里不加 .value 就能用，但换到 reactive 对象里嵌套的 ref，行为又不一样。这些差异并不来自响应式系统本身，而是 Vue 对模板表达式做了一层“自动解包”的编译处理。理解这层机制能避开很多“数据改了页面没动”的问题，也能解释为什么在 watch 里拿到的是原始 ref 而在模板里拿到的是值。下面从模板编译、运行时解包和常见错误场景拆开说。

Vue 3 中 ref 和 reactive 在模板自动解包上的差异与踩坑记录

在 Vue 3 的 Composition API 里，ref 和 reactive 是最常用的两个响应式声明方式。实际开发中常遇到一种情况：把 reactive 对象的某个属性重新赋值后，模板不更新；或者从 setup 返回一个 ref 后，在模板里不加 .value 就能用，但换到 reactive 对象里嵌套的 ref，行为又不一样。这些差异并不来自响应式系统本身，而是 Vue 对模板表达式

前端

编程语言

Vue3中ref与reactive响应式解包机制全解析，详解模板编译自动解包、reactive嵌套ref不解包、watch取值差异等常见问题，助你避开数据更新但页面不渲染的坑，附组合式函数最佳实践。

代码解释

编译器

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

Vue 3 中 ref 和 reactive 在模板自动解包上的差异与踩坑记录-腾讯云开发者社区-腾讯云

Vue 3 中 ref 和 reactive 在模板自动解包上的差异与踩坑记录

Vue 3 中 ref 和 reactive 在模板自动解包上的差异与踩坑记录

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐