Vue3 的 setup 返回值看起来只是return { ... }一行代码但在实际项目里大量问题都出在这一步模板空白、数据不更新、父组件拿不到方法、ref 被渲染成对象。你可能会怀疑是版本问题或者是依赖没装对但多数时候原因就是返回值没有按 Vue3 的规则暴露。我的结论很简单setup 返回值是组合式 API 与模板渲染上下文、组件实例之间的核心通道。它决定哪些数据和方法能出现在模板里也决定父组件通过 ref 拿到子组件的哪些能力。理解了返回值的几种形态、自动解包规则和响应式丢失场景很多 Vue3 的“怪现象”会直接消失。下面按实际开发顺序拆开讲。1. setup 返回值在组件里到底管什么1.1 一句话理解 setup 返回值用 Vue3 Composition API 写组件时setup是组件的初始化入口一般负责创建响应式数据、声明函数、绑定生命周期、设置监听。之后组件必须通过setup的返回值告诉 Vue哪些内容要暴露到模板里哪些内容要暴露给 Options API 的其他选项。看一个最基础的例子script import { ref } from vue export default { setup() { const count ref(0) const increment () { count.value } return { count, increment } } } /script template button clickincrement{{ count }}/button /template这里return { count, increment }做的事情就是在渲染上下文里注册两个属性一个响应式数据count一个事件函数increment。模板里能直接用count和increment不是因为它们是全局变量而是因为它们被setup返回了。再换一种说法setup返回值就是组件对外暴露的“公共接口”。它在模板里可读在 Options API 的computed、methods、watch里也可能通过this读到甚至在父组件拿到子组件实例后也能访问到一部分内容。1.2 返回值不是普通对象而是一套访问代理很多人误以为setup返回的就是一个普通 JavaScript 对象模板访问的是这个对象里的属性。实际上Vue3 会把返回值包装成组件渲染上下文的一部分或者说setupState再通过代理对象让模板表达式正常读取。这意味着两件事模板每次渲染时访问的是代理对象上的属性不是 return 时的一次性快照。只有返回值中真正保留了响应式引用模板才能事后更新。比如这样写const count ref(0) return { count }模板渲染时会去读取count这个 refVue 的自动解包机制会拿到0。当count.value改变时因为渲染时建立过依赖收集组件会自动重新渲染。但如果这样写const count ref(0) return { count: count.value }return 时把 ref 的当前值0赋给了普通属性后续count.value再变化模板依然只会显示旧的0。从语法上看没有报错但响应式已经丢了。这就是新手最容易踩的坑之一。1.3 返回值与 data、computed、methods 的优先级问题在同一个组件里如果既写了data、computed、methods又写了setup返回对象模板和this可能会同时访问多套来源。Vue3 内部会按照一定优先级处理这些属性一旦出现同名冲突结果会变得很隐蔽。我不建议在正式项目里依赖“同名时谁覆盖谁”的规则。更稳妥的做法是一个组件内数据来源保持统一。要么全部走setup返回要么全部走 Options API尽量不要同一个模板里既有data里的title又有setup返回的title。如果你确实在迁移老项目也要先在代码里搜索一遍同名变量。否则很容易出现“模板读到的值和我在 setup 里准备的值不一样”的诡异问题。2. 四种常见返回值形态分别用在什么场景2.1 返回对象绝大多数组件的工作方式最常用的形态是返回一个对象对象的属性会暴露到模板渲染上下文中。对象里可以放ref响应式数据reactive响应式对象computed计算结果普通常量普通函数emit包装后的方法一个典型例子script import { reactive, computed } from vue export default { setup(props, { emit }) { const form reactive({ name: , age: 0 }) const canSubmit computed(() { return form.name.trim().length 0 }) const submit () { emit(submit, { ...form }) } return { form, canSubmit, submit } } } /script template form submit.preventsubmit input v-modelform.name / span{{ form.age }}/span button :disabled!canSubmit提交/button /form /template这里form是reactive对象模板里访问form.name不需要写.value。canSubmit是computed模板里直接当普通变量用。submit是函数可以直接绑定到事件上。需要注意模板里的自动解包只对顶层 ref 生效。如果你的返回值里有reactive对象对象里面的属性当然不用写.value。但如果返回一个普通对象而这个普通对象内部嵌套了 ref情况就会复杂一些。我建议在setup返回前就把数据结构理清楚顶层用 ref 还是 reactive内部字段用普通值还是 ref尽量固定一种风格。2.2 返回函数当组件确实想走渲染函数setup不一定要返回对象也可以返回一个函数。这个函数会被当作组件的render函数处理。看一个返回渲染函数的例子import { h, ref } from vue export default { setup() { const list ref([Vue, React, Svelte]) return () { return h(ul, list.value.map((item) h(li, item))) } } }使用 JSX 时写法更直观import { ref } from vue export default { setup() { const list ref([Vue, React, Svelte]) return () ( ul {list.value.map((item) ( li{item}/li ))} /ul ) } }如果你返回函数Vue 会把它当成渲染函数来用模板文件里的内容会被忽略。不要写一半模板又返回一个渲染函数那样容易让人误以为“模板没生效”。返回函数的场景通常有函数式组件的替代写法。需要动态生成内部节点不适合在模板里堆v-if的地方。需要非常精细地控制渲染结构。返回函数时渲染函数是通过闭包访问setup里声明的变量不是通过模板上下文。所以你在setup里声明了countreturn 函数内部直接用count.value即可不再有自动解包这种保护。写的时候要留意。2.3 不返回或返回 undefined只做副作用处理setup不是必须返回内容。如果组件只是做一些初始化逻辑不依赖模板展示任何本地状态可以直接不写return。例如export default { setup(props, { emit }) { // 只做初始化不暴露数据给模板 console.log(组件初始化) // 也可以在这设置 provide } }还有一种情况组件使用外部传入的render或者完全由父组件控制内容setup返回undefined也合法。但要注意如果在setup里声明了几个变量却忘记return模板里访问这些变量时只会得到undefined并且不会有特别明显的编译报错。这种问题在真实项目中出现频率很高。所以我的习惯是setup里凡是模板要用的变量和函数统一放在return里不用的变量不要放进return。如果一段逻辑完全不需要暴露给模板就正常写在setup内部不写进返回对象。2.4 async setup 返回 Promise配合 Suspense 使用Vue3 的setup还可以是异步函数。异步setup最终返回的不再是普通对象而是一个 Promise。常规组件直接渲染这个组件会出问题因为 Vue 不知道 Promise 什么时候结束。这时候需要外层用Suspense包裹。示例script const getData () { return new Promise((resolve) { setTimeout(() { resolve({ name: Vue3 }) }, 1000) }) } export default { async setup() { const info await getData() return { info } } } /script template div{{ info.name }}/div /template父组件template Suspense AsyncComponent / /Suspense /template如果异步setup没有外层Suspense控制台通常会出现类似警告setup 返回了一个 Promise但没有找到 Suspense 边界。这种情况下页面可能白屏或者出现“Promise”相关信息。不要把它当成普通组件直接挂载就完事要确认异步边界是否配好。3. 返回对象时最容易踩的坑解包、解构和作用域3.1 ref 和 reactive 在返回值中的差异这是 Vue3 面试和实战里都绕不开的点。setup返回值中ref 和 reactive 的模板写法不同返回 ref模板里直接写变量名不需要写.value。返回 reactive模板里要按对象属性访问比如state.count。返回 computed模板里直接使用 computed 变量名但在setup内部修改或读取要写.value。返回普通常量模板里能显示但后续不会自动更新。可以用一张表归纳返回内容setup 内部访问模板访问是否能触发更新ref(0)count.value{{ count }}能reactive({ count: 0 })state.count{{ state.count }}能computed(() ...)double.value{{ double }}能普通值123const a 123{{ a }}不能普通函数fn()clickfn看内部逻辑在模板里ref 的自动解包只对顶层属性可靠。如果setup返回的是一个普通对象对象内部又放了 refconst user { name: ref(Tom) } return { user }那么模板里写{{ user.name }}就不能保证拿到Tom更安全的是在setup内部就处理成普通值或者把user改成reactive对象。不要依赖“模板会自动解包嵌套 ref”这种模糊行为。3.2 不要在 return 时手动解构 reactive这是响应式丢失最经典的场景。看这段代码const state reactive({ count: 0, name: Vue }) return { ...state }看起来似乎没问题在模板里能用{{ count }}、{{ name }}但实际上count和name已经被展开了和state不再有响应式关联。后续state.count页面不会更新。还有一种写法也会丢return { count: state.count }在 return 执行的那一刻state.count被读取成普通数字之后state.count变化无法反向影响这个普通数字。正确做法是import { toRefs } from vue const state reactive({ count: 0, name: Vue }) return { ...toRefs(state) }toRefs把reactive对象里的每个属性转成独立 ref再展开返回这样模板里既可以直接访问count又能保持响应式。这里的底层原因是Vue3 的响应式基于 Proxy对象被解构后标签和引用关系就断了。凡是遇到“从响应式对象里拆出属性再返回”都要先想清楚是否需要用toRefs或toRef。3.3 返回了函数但函数内部作用域绑错setup返回对象里的函数本质是普通函数。只要它通过闭包访问了响应式数据就能正常操作响应式状态。比如const count ref(0) const add () { count.value } return { count, add }点击模板里的按钮add能修改count因为add闭包捕获的是count这个 ref 引用。但如果写成const count ref(0) const add () { count.value } return { count: count.value, add }模板里count只是初始值 0点按钮时虽然count.value变了但模板里的count已经不是 ref所以不会更新。这里问题出在返回值而不是函数本身。4. 选项式 API 中 setup 返回值如何和 this 联动4.1 setup 内部不能用 this但返回值会挂到实例上Vue3 的setup函数在执行时组件实例还没有完全创建所以setup内部无法像 Options API 那样使用this。你如果在setup里写this.xxx大概率会拿到undefined或者直接报错。正确的做法是使用setup的参数export default { props: [name], setup(props, { emit }) { console.log(props.name) emit(update, 1) } }props里可以访问父组件传入的 propscontext里有emit、slots、attrs等能力。这些在 Vue3 里是替代this的主要手段。但是组件实例创建完成后setup返回的内容会被挂到组件实例上。也就是说同一个组件里如果你在methods、computed中使用this是有可能访问到setup返回值的。看一下这个混合写法export default { setup() { const base ref(2) return { base } }, computed: { double() { return this.base * 2 } } }这里this.base能读到setup返回的base。不过我不建议在项目里大量混用因为this上的属性来源太多排查时很难快速定位。4.2 父组件通过 ref 拿到子组件的哪些能力如果子组件使用的是显式setup()写法setup返回的所有属性都会被暴露到组件实例上父组件通过模板 ref 可以访问到这些返回内容。例子script export default { setup() { const open () { console.log(open) } return { open } } } /script父组件template Child refchildRef / /template script import { ref, onMounted } from vue export default { setup() { const childRef ref(null) onMounted(() { childRef.value.open() }) return { childRef } } } /script这种方式在非script setup组件里比较直接。但使用script setup时默认不会把内部变量自动暴露给父组件需要显式调用defineExpose这是下一节要讲的重点。5. script setup 的“隐式返回值”和 defineExpose5.1 script setup 不用 return但效果类似script setup是 Vue3 SFC 的推荐写法。在script setup中顶层的变量、函数、import 引入的组件都会自动暴露给模板使用不需要写return。script setup import { ref } from vue const count ref(0) const increment () { count.value } /script template button clickincrement{{ count }}/button /template这里count和increment没有写在return里但模板可以直接使用。它的本质是 Vue 编译器帮我们处理了隐式暴露和显式setup()返回对象在模板层面对用户来说是等价的。5.2 defineExpose 控制暴露给父组件的内容script setup的自动暴露是对模板的不是对父组件的。子组件内部定义的变量默认不会全部暴露到父组件能访问的实例上。如果父组件通过ref拿子组件实例想调用子组件里的某个方法子组件需要显式声明defineExposescript setup import { ref } from vue const count ref(0) const open () { console.log(open, count.value) } defineExpose({ open }) /script父组件拿到childRef.value后能访问到open但不能直接访问count除非你把count也放进defineExpose。很多新手遇到“父组件拿不到子组件方法”的问题第一反应是查 ref 绑定实际上更常见的原因是script setup默认关闭了对外暴露。5.3 显式 setup 和 script setup 怎么选在全新项目里默认推荐script setup写法更简洁模板里少维护一个return块。defineExpose也不是很复杂遇到需要父组件调用的方法单独暴露即可。但如果你在写这样几类组件显式setup()仍然有用需要动态返回渲染函数时script setup里写返回函数不够直观。要让 Options API 的methods或computed访问setup里的数据时显式setup()更容易理解。迁移老项目时还要保留大量 Options API显式setup()可以让迁移粒度更小。团队落地时建议统一风格不要在同一个项目里一部分组件用显式setup一部分用script setup。混用不是不行但维护成本会明显上升。6. 围绕返回值的面试题和实战排查6.1 高频面试题怎么答关于setup返回值面试题经常从这几个角度问问setup 返回值有哪几种可以答常见有对象、函数、undefined异步 setup 还会返回 Promise。返回对象时对象属性暴露到模板和组件实例返回函数时函数作为渲染函数返回 undefined 时只做初始化逻辑async setup 需要配合 Suspense。问setup 返回的 ref 在模板中为什么不用写 .value可以答Vue3 模板渲染上下文对顶层 ref 有自动解包机制。但要注意嵌套在普通对象里的 ref 不会可靠解包所以尽量保持顶层 ref 或使用 reactive 对象。问return { ...reactiveObject } 为什么不更新可以答解构会丢失 Proxy 响应式连接。应该 return 原对象或使用toRefs展开后返回。问setup 里能用 this 吗可以答不能直接使用 this。可以用 props 和 context 参数需要组件实例时用getCurrentInstance。问script setup 如何暴露方法给父组件可以答使用defineExpose只暴露需要的方法或数据。这些题目并不是很难但如果没有亲手踩过坑很容易答得模棱两可。尤其“响应式丢失”和“顶层 ref 解包”这两点是面试官最爱追问的细节。6.2 模板不显示或渲染异常时按顺序排查我在实际开发中遇到setup返回值导致的问题会按下面这个顺序查看现象是空白、报错、不更新还是父组件调用不到方法。看 setup 是否 return如果声明了变量但没 return模板里一定访问不到。看返回类型是不是不小心返回了渲染函数导致模板被忽略。看响应式是否丢失检查是不是在 return 时展开了 ref 或 reactive。看模板访问路径确认是顶层属性还是嵌套在普通对象里的 ref。看组件暴露范围如果是script setup确认有没有defineExpose。看异步边界如果setup是 async确认外层有没有Suspense。举例模板显示空白但控制台没有明显报错优先看 return 的变量名是否和模板一致。模板把一个对象渲染出来了比如显示{ count: 0 }或Proxy(Object)说明你访问的是对象本身不是对象里的具体属性。页面能显示初始值但点击按钮后不更新大概率是在 return 时解构了响应式对象或者把 ref 的.value当成普通值返回了。父组件调用子组件方法时提示 undefined优先查子组件是否使用script setup以及是否写了defineExpose。控制台出现 Promise 相关警告查外层 Suspense。这个排查顺序并不只针对 setup 返回值也适用于大多数 Vue3 渲染异常。先想清楚“数据有没有真正跑到渲染上下文里”再考虑参数和依赖问题。6.3 一套稳定可复用的 setup 返回写法最后给一个我自己常用的稳定模板。普通业务组件推荐这样组织setupscript import { ref, computed, onMounted } from vue export default { setup(props, { emit }) { // 1. 数据 const count ref(0) // 2. 计算属性 const double computed(() count.value * 2) // 3. 方法 const add () { count.value emit(change, count.value) } // 4. 生命周期 onMounted(() { console.log(组件挂载完成) }) // 5. 最后统一返回 return { count, double, add } } } /script使用script setup时结构一样只是省略 returnscript setup import { ref, computed, onMounted } from vue const count ref(0) const double computed(() count.value * 2) const add () { count.value } onMounted(() { console.log(组件挂载完成) }) defineExpose({ add }) /script真正落地时最该盯住的不是功能列表而是返回值的类型、解包规则和响应式解构。很多问题看起来像 Vue 版本差异实际上都是返回值暴露协议没理清。下次遇到模板不渲染别急着改依赖先从setup的 return 那一行开始查。