企业官网建设流程全解析

写 Vue 3 写了几年，ref 早就成了每天打交道最多的 API。但说实话，真正把 ref 的自动解包机制吃透，还是在踩了好几个坑之后。这个机制设计得很巧妙，能让你在模板里少写一堆.value，可它又没那么“智能”，在特定场景下绕过你、坑你一把，而且是那种报错都找不到原因的坑。

这篇文章就把 ref 的特殊处理与解包机制完整拆一遍。我会从它的设计逻辑讲起，再逐个场景过，包括模板、reactive 对象、数组、嵌套 ref，以及和 uni-app 这类框架结合时的实际情况。最后还会把我踩过的坑整理成速查表，照着对就能少走弯路。

1. 内容整体设计与思路拆解

1.1 ref 的“双重视角”：数据容器与响应式代理

ref 本质上做了一件很朴素的事：把普通值包装成一个带响应式能力的对象。这个对象内部维护一个value属性，真正的数据存在value里，访问和修改都绕不开它。但如果你在模板里写{{ count }}，却能直接拿到数值，不需要写{{ count.value }}——这就是自动解包机制的功劳。

理解 ref 最好的方式，是把它想象成一个“带监控的盒子”。你把东西放进盒子里，盒子本身不能直接用，但当你把它拿到特定场景（比如模板）时，盒子会自动打开，把里面的东西取出来给你用。这个“特定场景”就是解包机制生效的边界。

这个设计和 Vue 2.x 的data返回对象有着本质区别。Vue 2 里数据是“透明”的，对象里有什么就能拿到什么，响应式是通过Object.defineProperty对属性做拦截实现的。Vue 3 把数据访问统一到.value上，让响应式追踪变得更可控——至少在 JavaScript 层面是可控的。

1.2 解包机制的设计意图：让模板更干净，让逻辑更清晰

你可能会有疑问：既然 ref 已经通过.value管理数据了，为什么模板里还要自动解包，这不是多此一举吗？

答案是模板的“读取频率”远高于逻辑代码。在页面上展示一个数据，可能是在插值表达式、事件绑定、条件渲染、循环渲染里同时用到。如果每一处都要写.value，模板会变得非常啰嗦，可读性也会急剧下降。试想一下：

<template> <div>{{ count.value > 0 ? count.value * 2 : 0 }}</div> </template>

而有了自动解包：

<template> <div>{{ count > 0 ? count * 2 : 0 }}</div> </template>

两者都能运行，但后面的代码明显清爽得多。这个设计的目的，就是把模板场景下的“取值”简化为最自然的方式，让模板关注展示，把复杂的数据操作留在逻辑层。

与之对应的是，在<script setup>或setup()函数内部，ref 的解包规则就完全不同了。你声明const count = ref(0)，然后count += 1是行不通的，因为此时count是 Ref 对象，不是数值。JavaScript 的语法规则不会因为你用了 Vue 就改变，所以这里必须老老实实写count.value += 1。

1.3 “万能对象”的真相：ref 到底能包什么

网上有关“ref 万能对象”的讨论不少，这其实说的是 ref 对数据类型的包容度。ref 的底层是通过ref()函数创建一个 RefImpl 实例，这个实例的value可以是任何值——基本类型、对象、数组，甚至是另一个 ref。

const num = ref(0) const obj = ref({ name: 'vue', version: 3 }) const arr = ref([1, 2, 3]) const nested = ref(ref(0))

关键在于，当ref()接收一个对象时，它会用reactive()对这个对象做深度响应式代理。也就是说：

const obj = ref({ name: 'vue', nested: { a: 1 } })

你改变obj.value.name或obj.value.nested.a，都会触发响应式更新。所以“万能对象”并不是说 ref 变成了 Reactive 那种直接代理对象，而是说ref 不仅能管基本类型，也能管复杂结构，而且内部的响应式能力是完整的。

拿这个特性去做全局状态管理、表单数据维护、复杂配置对象管理，都比 reactive 更灵活。因为 ref 的数据访问方式统一（都得.value），在某些场景下反而更容易理解和维护。

2. 核心细节解析与实操要点

2.1 模板中的自动解包：顶层属性与嵌套属性的差异

模板中的自动解包有个很重要的前提：只能是顶层属性。这句话怎么理解？

假设你有这样的 setup 返回值：

setup() { const count = ref(0) const obj = { count: ref(0) } return { count, obj } }

在模板里：

<template> <div>{{ count }}</div> <div>{{ obj.count }}</div> </template>

第一行count是 setup 返回的顶层属性，会被自动解包，显示数字。第二行obj.count就不是顶层属性了，它是对象obj的属性，而obj是一个普通对象（不是 reactive），此时obj.count是 Ref 对象，不会自动解包。模板会显示[object Object]或者直接渲染空，看具体版本和渲染方式。

这就有点反直觉了：我没写.value，为什么不出来？原因在于模板编译器的解包逻辑。Vue 3 的模板编译器会将{{ count }}编译为类似_ctx.count的访问，然后对 ref 做unref处理。但对于obj.count，编译器是按普通对象属性访问来处理的，它不知道obj.count本身是一个 ref。

在<script setup>语法中，有一个类似但更严格的规则：只有顶层变量才会在模板中自动解包。比如：

<script setup> import { ref } from 'vue' const count = ref(0) </script> <template> <div>{{ count }}</div> <!-- 自动解包，显示 0 --> </template>

但如果嵌套在一个非 ref 对象里：

<script setup> import { ref } from 'vue' const obj = { count: ref(0) } </script> <template> <div>{{ obj.count }}</div> <!-- 不会解包 --> </template>

这里官网文档建议大家用toRefs或者直接ref声明来进行状态管理，尽量不要把 ref 塞进普通对象里，不然模板里的显示会和你预期不一致。

2.2 reactive 对象中的解包规则：浅层解包与覆盖行为

reactive 对象内部对 ref 有一套更“聪明”但也更严格的解包规则。当一个 ref 作为属性被放进 reactive 对象时，访问该属性时会自动解包：

const count = ref(0) const state = reactive({ count }) console.log(state.count) // 0，自动解包，不需要 .value state.count = 1 console.log(state.count) // 1 console.log(count.value) // 1，同步更新

这个机制依赖于 reactive 对象的属性访问拦截。当你访问state.count时，Vue 内部会检测到这个属性值是一个 ref，就自动帮你做了unref。

但这个解包有两个关键限制：

第一，只发生在 reactive 对象内部，不发生在 set 的时候。如果你直接给state.count赋一个新的 ref：

state.count = ref(2) console.log(state.count) // 2 console.log(state.count.value) // undefined

赋值时不会自动把ref(2)包一层再解包，而是直接替换为新值。这里要注意，state.count和原始的count已经脱离了联系，因为 reactive 对象内部存储的是ref(2)这个引用，而访问时解包得到2。

第二，解包是浅层的。reactive 对象的第一层属性如果是 ref，访问时会解包。但是如果 ref 嵌套在更深的地方：

const state = reactive({ nested: { deepRef: ref(1) } }) console.log(state.nested.deepRef) // Ref 对象，不解包

ref(1)存在于nested对象内部，nested是被 reactive 代理过的，但属性deepRef并不会被自动解包——解包只发生在reactive(obj)的自身属性层面，reactive 对嵌套对象的代理不会继续“透传”解包逻辑。

我在实际开发中遇到过最典型的情况：把多个 ref 组织成一个 reactive 的 store 对象，然后在某个异步回调里给其中一个属性赋值，另一个模块读取时发现是 ref 对象而不是值，报错很难定位。后来养成了习惯：统一从 ref 的.value层面取数据，或者明确只通过 reactive 的第一层属性访问数据，混用模式下很难保证行为的稳定。

2.3 数组与集合容器：为什么不会被解包

这是解包机制里最经典的一个“坑”：ref 包出来的数组，如果放进 reactive 对象，数组里的 ref 不会被自动解包。

const arr = reactive([ref(0), ref(1), ref(2)]) console.log(arr[0]) // Ref 对象 { value: 0 }，不是 0 console.log(arr[0].value) // 0

你可能会想，数组也是对象，reactive 代理了数组之后，访问arr[0]应该自动解包才对。但 Vue 的源码里并没有为数组元素做解包处理。原因可能有两个：一是数组索引访问是一种“非常热”的操作，如果每个索引访问都要做一次 isRef 判断，性能会明显下降；二是数组元素的语义更复杂——你可能真的要存一个 ref 对象在数组里，如果自动解包了，反而会破坏这种用途。

这个行为在日常开发中的影响是巨大的。很多人会用数组来管理表单字段、列表行数据，想在数组里放 ref 来维护每一行的状态，结果取出来全是 ref 对象，还得手动.value，代码变得很丑。

我的实用建议是：数组里不要放 ref，直接放普通值或者 reactive 对象。如果要给每个数组项维护独立状态，那就把整项做成 reactive 对象：

const list = reactive([ { name: 'a', count: 1 }, { name: 'b', count: 2 } ])

或者用 ref 包裹整个数组：

const list = ref([{ name: 'a', count: 1 }]) console.log(list.value[0].name) // 需要 .value

这样至少数据结构是一致的，不会出现数组里有 ref 和非 ref 混在一起的混乱局面。

2.4 嵌套 ref 与解包边界：什么时候不自动解包

再来看看嵌套 ref 的情况。嵌套 ref 就是“ref 里面套 ref”：

const outer = ref(0) const inner = ref(outer) console.log(inner.value) // 0，而不是 Ref 对象

这是 Vue 3 的一个特殊设计：ref 初始化时，如果 value 是一个 ref，会自动解包一层。也就是说inner.value直接拿到的是数字0。

这个设计在源码里体现为：

class RefImpl { constructor(value) { this._value = toRawReactive(value) } get value() { return toRaw(this._value) } }

流程很简单：ref 接收值后，如果值是 ref，就通过toRaw取出内部值；如果isRef(value)为真，toRawReactive会返回value.value。所以嵌套 ref 最多解一层，不会递归无限解包。

对应地在模板里：

<template> <div>{{ inner }}</div> <!-- 显示 0 --> </template>

但如果嵌套层级更深呢？

const a = ref(0) const b = ref(a) const c = ref(b) console.log(c.value) // 0，仍然解包

这里的处理方式是把c.value用unref解包后再作为 Ref 的 value 存储。不过说实话，我在实际业务里没见过有人真的写这么深的嵌套，这更多是库内部实现逻辑。了解它能帮你理解“为什么 ref 的 value 拿到的值是数字而不是 Ref 对象”，这在调试第三方库代码时很有用。

3. 实操过程与核心环节实现

3.1 场景一：setup 返回 ref 与模板绑定

先看最经典的日常用法。用标准的setup()函数组织逻辑，并配合模板绑定：

<template> <div class="counter"> <p>当前计数：{{ count }}</p> <p>翻倍计数：{{ doubleCount }}</p> <button @click="increment">增加</button> </div> </template> <script> import { ref, computed } from 'vue' export default { setup() { const count = ref(0) const doubleCount = computed(() => count.value * 2) function increment() { count.value++ } return { count, doubleCount, increment } } } </script>

这里模板里的{{ count }}是 setup 返回的顶层属性，自动解包，显示数字。{{ doubleCount }}同理，computed 返回的也是 ref 对象，在模板里解包为数值。

关键点在于，函数的返回值如果是 setup 的顶层属性，解包机制才会生效。但因为increment是一个函数，它不会被解包，可以直接在模板里绑定事件。

这种写法和<script setup>的差异主要在于代码组织粒度。<script setup>相当于自动把这个模块里所有顶层声明暴露给模板，少一层手动 return，但语义是相似的。

3.2 场景二：复杂对象管理中的 ref 解包

我在实际项目中做过一个配置管理模块，用 ref 封装整个配置对象，然后通过 computed 派生出需要的数据。代码大致是这样：

<script setup> import { ref, computed, watch } from 'vue' const config = ref({ theme: 'dark', fontSize: 14, ui: { showSidebar: true, density: 'medium' }, behaviors: [] }) const fontSizePx = computed(() => `${config.value.fontSize}px`) function updateTheme(newTheme) { config.value.theme = newTheme // 这里不需要深层逐层加 .value，因为 config.value 是 reactive 代理 } </script> <template> <div class="settings"> <p>当前主题：{{ config.theme }}</p> <p>字号：{{ fontSizePx }}</p> <button @click="updateTheme('light')">切换主题</button> </div> </template>

这里有个很多人会搞混的细节：ref 包裹对象时，只有第一层需要用.value访问，内部属性访问不需要。因为ref({ ... })的底层实现会把对象转为 reactive 代理，config.value本身就是一个 reactive 对象，访问config.value.theme会触发响应式追踪，同时config.value.ui.showSidebar这种深层访问也有效。

注意模板里的{{ config.theme }}——它不是自动解包的结果，而是因为config在模板里先解包为 reactive 对象，然后.theme才能取到值。如果你在模板里只写{{ config }}，会看到一个 Proxy 对象，不会自动变成字符串。

这一点很容易被忽略：自动解包只发生在 ref 对象本身这一层，解包后的对象如果有内部属性，属性访问的逻辑按普通 JS 对象规则走。

3.3 场景三：switch 场景中的解包逻辑与强制绑定

解包机制不只是取值，它还会影响赋值。最典型的就是v-model和事件绑定中的表现。先看一个我认为能解释“ref 解包是响应式核心”的案例。

在switch场景里，比如设置页的开关切换：

<script setup> import { ref } from 'vue' const notifications = { email: ref(true), sms: ref(false), push: ref(true) } </script> <template> <el-switch v-model="notifications.email" /> </template>

这段代码有问题吗？从语法上看没问题，但实际运行时你会发现，开关状态改变后，模板里的其他绑定可能不生效。原因就是前面提到的：notifications是普通对象，notifications.email作为其属性，在响应式系统内部不会自动解包。

最安全的做法是直接使用 reactive：

<script setup> import { reactive } from 'vue' const notifications = reactive({ email: true, sms: false, push: true }) </script> <template> <el-switch v-model="notifications.email" /> </template>

或者用 toRefs 把 reactive 对象拆成多个 ref 再组合：

<script setup> import { reactive, toRefs } from 'vue' const notifications = reactive({ email: true, sms: false, push: true }) const { email, sms, push } = toRefs(notifications) </script> <template> <el-switch v-model="email" /> </template>

在 uni-app + Vue 3 项目中，这个场景更常见。页面数据放reactive，配合toRefs在模板里使用。因为 uni-app 的页面生命周期和普通 Vue 组件有差异，数据必须以可预测的方式暴露给视图层，这时候模板解包机制的可靠性就很重要——它不能依赖“某种情况下解包，某种情况下不解包”的不确定性。

3.4 热词里的“强势区域”和 ref 计算

在热词里有一条看起来像量化交易条件的字符串：“强势区域1:=(count(every(bmacd0=0,1),7)=3 or count(every(bmacd0=ref(bmacd0,1) ...”，这里出现了ref作为计算函数名的用法。

我要明确地指出一个概念边界：量化/技术分析框架中的 ref 函数，和 Vue 3 里的 ref API 不是一回事。在股票或期货数据分析软件里，ref(X, N)表示取 X 在 N 个周期前的值。比如ref(close, 1)是昨天的收盘价。它和前端框架的 ref 只是名称相同，语义完全不同。

但这两个领域有个共同点：都是对“取值”的处理。技术分析里的ref(close, 1)是在时间轴上取前值，Vue 里的 ref 是在响应式数据上取值。如果你们团队同时做前端和量化分析，文档里看到ref时，一定要先确认上下文是哪个领域，别被相同的函数名带偏。

就拿every(bmacd0=0,1)来说，它的意思是“最近 1 根K线满足 bmacd0=0”，而count(...,7)=3表示“近 7 根K线里满足该条件的天数为 3”。整体条件组合了多个时间窗口的判断，这种写法的时间序列逻辑和响应式拆包是完全不同的思维模式。在量化领域，ref 取前值后通常不会改写原值，而 Vue 的 ref 是可以双向绑定的。写代码时别混着用。

3.5 数组循环中的 ref 解包处理

这是我最想分享的实战细节之一。平时用v-for循环渲染列表数据时，如果数组由 ref 包裹，循环内你要访问的是item而不是item.value：

<script setup> import { ref } from 'vue' const todos = ref([ { id: 1, text: '学习 ref', done: false }, { id: 2, text: '掌握解包', done: false } ]) </script> <template> <ul> <li v-for="todo in todos" :key="todo.id"> <input type="checkbox" v-model="todo.done" /> <span :class="{ done: todo.done }">{{ todo.text }}</span> </li> </ul> </template>

这里的v-for="todo in todos"就涉及对象解包的边界。todos是 ref 包裹的数组，在模板里是第一层属性，自动解包，所以todo是数组元素——普通对象。接下来todo.done的访问就是普通对象属性访问，不需要再写.value。

这个场景容易出问题的版本是：把 ref 放在数组里再循环。比如：

<script setup> import { ref } from 'vue' const list = ref([ref({ name: 'a' }), ref({ name: 'b' })]) </script> <template> <ul> <li v-for="item in list" :key="item"> {{ item.name }} </li> </ul> </template>

这里模板里{{ item.name }}一定能生效吗？不一定。关键在于list解包出来的数组里的元素是 ref 对象，但v-for 循环内不会继续解包，所以item仍是 Ref 对象，item.name是undefined。模板里的{{ item.name }}实际上访问的对象属性根本不存在。

我在写这类逻辑时，如果发现列表超预期地没有渲染出内容，第一反应就是排查数据层级。合理的方式是写v-for="item in list.value"—— 但这在模板里做不到，因为模板里list已经解包过了。所以最好的方式还是保证数组元素本身不是 ref，普通对象加 ref 包裹外层才是正道。

4. 常见问题与排查技巧实录

4.1 为什么模板里显示 [object Object]

这是最常见的问题，没有之一。模板中原本应该显示对象里某个字段，结果渲染成了[object Object]。排查思路很直接：

1. 确认模板里访问的是否是顶层 ref 属性。
2. 如果不是顶层属性，检查它是否在普通对象里。
3. 如果是{{ obj.refProp }}的形式，说明obj.refProp是 Ref 对象，模板不会自动解包。

修复方式有两种：

• 模板里手动加.value：{{ obj.refProp.value }}
• 数据结构上避免这种写法，直接用toRefs或 setup 顶层返回

<script setup> import { ref, toRefs } from 'vue' const obj = reactive({ count: ref(0) }) const { count } = toRefs({ count: obj.count }) // 提取为独立 ref 顶层返回 </script> <template> <div>{{ count }}</div> </template>

我在实际开发中倾向用 toRefs 或直接多写几个 ref 变量，而不用“普通对象 + ref 属性”的组合。因为模板问题排查太浪费时间了，不如一开始就规避。

4.2 为什么 ref 赋值后视图不更新

这个问题的坑不在 ref 本身，而在它对对象的处理方式。先看代码：

const obj = ref({}) obj.value.name = 'vue'

这行代码能触发视图更新吗？能，前提是obj.value一开始就是 reactive 代理。因为ref({})内部已经把空对象转成了 reactive，之后给obj.value.name赋值会走 reactive 的 set 拦截，触发更新。

但另一种写法不行：

const obj = ref({}) obj.value = { name: 'vue' }

这种会触发更新吗？也会。因为 ref 的.value赋值本身就是响应式行为。两种情况都正常，真正不正常的场景是把 ref 塞进普通对象却不触发：

const myRef = ref(0) const plainObj = { myRef } plainObj.myRef = 1 // 不会触发任何响应式更新

这个坑在跨组件传参时往往爆出来。你把 ref 放在普通对象里传给子组件，子组件修改它，父组件没有反应，因为普通对象没有响应式能力。要解决就得用 reactive、toRefs、provide/inject、状态管理库等正式方案，千万别把响应式数据塞进“普通容器”里就完事了。

4.3 为什么 v-model 绑定的值变成了 ref 对象本身

在使用自定义组件时，v-model 的默认 prop 是modelValue，默认事件是update:modelValue。如果你把 ref 作为 modelValue 传给子组件，子组件内部对它做赋值操作，那么：

<!-- 父组件 --> <ChildComponent v-model="count" /> <!-- 子组件 --> <script setup> const props = defineProps(['modelValue']) const emit = defineEmits(['update:modelValue']) function onChange(e) { emit('update:modelValue', props.modelValue + 1) } </script>

正常情况下，父组件的count是 ref，v-model会在模板里自动解包，所以在子组件里props.modelValue是数值而不是 ref 对象。这里解包机制已经生效了，没有坑。

但当你完全绕过 v-model，手动传整个 ref 对象时：

<ChildComponent :model-value="count" />

在子组件里props.modelValue就是 ref 对象，不是数值。如果你不知道这一点，拿它去加减乘除、显示，就会得到奇怪的结果。

所以自查清单就一条：模板绑定里 v-model 自动解包，但 props 穿对象时不会自动解包 ref 本身。

4.4 ref 与 reactive 混用时的监听失衡问题

混用 ref 和 reactive 时，watch 行为也可能出问题。看这段：

const countRef = ref(0) const state = reactive({ countRef }) watch(countRef, (val) => { console.log('countRef changed', val) }) watch( () => state.countRef, (val) => { console.log('state.countRef changed', val) } ) state.countRef++

这个例子中两个 watch 都能触发吗？取决于你修改的是哪个引用。如果通过countRef.value++，两个 watch 都会触发，因为state.countRef解包后访问的是同一个内部值。但如果直接赋值state.countRef = 10，那countRef本身没变，第一个 watch 不会触发，第二个 watch 会触发。

这类监听失衡问题在状态联动比较复杂时非常隐蔽。我的建议是：一个数据源，一条修改路径。如果一定要同时存在 ref 和 reactive 的访问，那就统一用ref.value的方式修改，避免走 reactive 属性赋值绕开了原始 ref 的更新通知。

4.5 常见问题速查表

4.6 我的排查方法论

说点实在的。遇到 ref 相关的显示或更新问题，我有一套固定排查顺序，基本能解决九成问题：

第一步，确认数据的存储方式。是 ref、reactive，还是拼在普通对象里？这个决定了解包机制是否参与。

第二步，确认访问路径。是直接访问顶层 setup 返回的 ref，还是通过对象属性/数组索引间接访问？这决定解包是否生效。

第三步，确认修改路径。改的是.value，还是 reactive 的某个属性，还是普通对象的属性？这决定响应式系统能否捕获到变化。

第四步，用控制台验证。打开浏览器控制台，打印一下访问的值，看它是不是 Ref 对象。如果是，就按前面的规则去找为什么解包没生效。这个方法最朴素但最有效，没有例外。

5. uni-app 场景下的 ref 解包实战

5.1 uni-app Vue 3 中 ref 的表现差异

uni-app 的 Vue 3 版本，底层是基于 Vue 3 的响应式系统的，所以 ref 的解包机制和纯 Vue 3 大体一致。但在小程序端和 H5 端，存在一些细微差异，主要在于模板编译的差异——uni-app 的模板编译器会针对不同平台生成不同的渲染代码，个别场景下解包行为的边界可能和纯 Web 端略有不同。

比较典型的场景是：在小程序端，ref包reactive对象再传给子组件，子组件里通过props拿到的行为，在微信小程序里可能会多一些序列化/反序列化的步骤，导致 ref 解包后的对象不再是原来的 Proxy。这种问题在真机调试时非常容易出现。

我通常的做法是：状态管理统一用 ref 或 reactive 之一，不混用；组件通信保持最小化，能不用 props 传复杂对象就不用。

5.2 uni-app 页面生命周期与 ref 解包的配合

uni-app 的页面有个特点：它的生命周期（onLoad、onShow等）是框架层面的方法，不是 Vue 组件钩子。页面里用ref()声明的数据，在onLoad中赋值，在模板中使用，走的仍然是 Vue 的响应式流程，解包机制完全生效。

但要注意一个边界：onLoad中如果有异步操作，比如网络请求回来后再给 ref 赋值，那么模板中绑定这个 ref 的地方会正常响应。因为响应式系统的依托是 Proxy 和依赖收集，和时间是否异步没关系。

我在实际项目里遇到过一个问题：在onLoad里给ref([])赋值一个普通数组，页面模板里v-for渲染正常。但如果我直接在onLoad里写data.value.push(...)，在某些低版本微信基础库上，动态插入元素会导致渲染异常。排查后发现，这是setter 触发依赖更新的滞后期造成的，不是 ref 本身的问题。

所以 uni-app 下的一个经验是：组件数据变更宁可多走一步“整值替换”，也不要依赖数组/对象的局部突变。这虽然牺牲了一点响应式的“精细度”，但换来了跨端渲染的稳定性。

5.3 跨端数据管理的推荐组合

我推荐一个在 uni-app 项目中稳定跑了很久的状态管理组合：

• 全局状态：用 reactive 定义 store 对象，配合 computed 派生数据
• 组件内页面数据：用 ref 管理，模板直接访问
• 跨组件传递：用 provide/inject，但保证注入的不是普通对象，而是 ref 或 reactive

// store.js import { reactive, computed } from 'vue' export const store = reactive({ userInfo: null, settings: {}, theme: computed(() => store.settings.theme || 'light') }) export function setUserInfo(info) { store.userInfo = info }

组件内：

<script setup> import { ref, computed } from 'vue' import { store } from '@/store' const pageTitle = ref('首页') const displayName = computed(() => store.userInfo?.name || '游客') </script> <template> <view>{{ pageTitle }}</view> <view>{{ displayName }}</view> </template>

这样组合的优点是：状态源清晰、解包边界稳定、模板层的自动解包机制能顺畅工作。同一个数据如果既出现在全局 store 又出现在局部 ref 里，最糟糕的情况就是“一个数据、两个源头”，改动时必须手动同步。

6. 解包机制的边界与上手经验总结

如果把所有规律浓缩成一句话，那就是：ref 的自动解包是“按容器”的，不是“按类型”的。模板只解包 setup 顶层属性，reactive 只解包自身属性，数组不解包，普通对象不解包。记住这个底层规律，大部分问题都不再是问题。

在实际开发中，我总结了几条经验，可能对你有帮助。

第一条，能不用普通对象装 ref，就别用。普通对象没有响应式能力，里面放 ref 只会制造混乱。会用reactive就用，喜欢ref就坚持 ref，别混搭。

第二条，** ref 包对象后，内部属性访问很自然，但对象替换要谨慎**。ref({ a: 1 })之后，你可以直接改ref.value.a，响应式没问题。但如果你整体替换ref.value = { b: 2 }，那原来对ref.value.a的依赖关系会断开，模板里绑定ref.value.a的地方会变成 undefined，这种错误在运行时不会报红，只会静默出 bug，很难查。

第三条，数组场景下用 ref 包整个数组，而不是每个元素各一个 ref。这不仅是解包规则的要求，也是性能考虑——每个 ref 都需要建立代理和依赖关系，一百个元素一百个 ref 的开销远大于一个数组包一层 reactive。

第四条，组合式函数返回响应式数据时，注意返回值的形态。如果你写一个useCounter，返回{ count: ref(0), increment }，那调用方在模板里必须通过count顶层属性访问。如果你返回的是ref({ count: 0 })，模板里就要访问count.count。这两种形态在文档、类型定义和调用方式上都不同，最好在函数设计阶段就统一风格。

我更喜欢返回一个 ref 对象本身，然后让调用方决定怎么解包：

function useCounter() { const state = ref({ count: 0 }) function increment() { state.value.count++ } return { state, increment } }

或者：

function useCounter() { const count = ref(0) function increment() { count.value++ } return { count, increment } }

两种风格都能用，关键是一致性。团队里不统一，才是最大的坑。

最后分享一个小技巧：如果你在写代码时拿不准某个值在模板里会不会被自动解包，可以在模板里放一个测试输出：

<template> <pre>{{ JSON.stringify(someRef) }}</pre> </template>

如果输出了对象而不是值，那说明它在这个场景下没有被解包。这个方法本质上不过是“打印出来看看”，但它能在开发初期就帮你确定解包边界，省掉后面大量的排错时间。ref 的解包机制并不是一个需要死记硬背的规则表——它不过是一套“哪些容器对 ref 更友好”的设计策略。理解了容器的边界，就理解了整个机制。