Vue3组合式API的核心概念是setup函数而setup函数的返回值决定了组件模板最终能访问哪些数据、方法、计算属性以及渲染内容。很多初学者从Vue2迁移到Vue3时最容易卡住的问题不是怎么写ref而是为什么写了setup之后模板里总是拿不到变量为什么setup里不能用this为什么别人的setup返回一个函数自己返回的是对象为什么在setup里调用axios之后页面永远不渲染。这些问题背后本质上都是同一个问题对setup函数“返回什么、返回之后发生什么”没有建立起完整的认知模型。这篇文章以setup函数的返回值作为主线从返回值形态、渲染优先级、响应式解包、异步场景、script setup编译原理、常见报错六个方面展开。看完后你既能完成一个最小Vue3项目的环境搭建与开发也能在面试中把“setup返回值”这类题目解释清楚。1. setup函数为什么是Vue3组合式API的“总入口”1.1 从选项式API到setup逻辑聚合方式的转变在Vue2的选项式API中组件的逻辑被拆成了data、methods、computed、watch、mounted等选项。一个小功能比如“点击按钮加载用户列表”通常需要在data里声明字段在methods里写方法在mounted里调用方法在computed里派生状态。功能少的时候还能接受组件一复杂同一个业务逻辑的代码就会分散在多个选项中维护时需要不断上下跳转。Vue3引入组合式API后setup成为组件的逻辑入口。它不是一个生命周期函数而是在组件实例创建过程中更早执行的一个普通函数。所有响应式状态、函数、计算属性、监听器、生命周期逻辑都可以写在这个函数体内最后通过返回值把需要暴露给模板的内容交出去。import { ref, computed } from vue export default { setup() { const count ref(0) const double computed(() count.value * 2) const increment () { count.value } return { count, double, increment } } }这段代码的关键点是count、double、increment定义在setup函数内部作用域只在setup内模板要使用它们必须在return中显式导出。如果少写了count模板里的{{ count }}就会显示为空或警告。1.2 setup的执行时机比beforeCreate更早Vue组件实例化过程中setup在beforeCreate之前执行。这意味着在setup体内访问不到组件实例this是undefined。这是Vue3设计上的一个关键取舍不再依赖实例上的this去挂载数据而是依赖闭包和返回值进行数据传递。好处是逻辑可以自由提取成独立的组合式函数不需要依赖实例上下文坏处是从Vue2迁过来的开发者需要改变“写methods就想到this.xxx”的习惯。执行顺序可以理解为组件实例创建props和context初始化执行setup函数根据setup返回值决定渲染上下文继续后续组件生命周期所以setup内如果写了console.log(this)控制台输出undefined这不是bug而是设计使然。1.3 setup的两个参数props 与 contextsetup函数接收两个参数props和context。export default { props: { title: String }, setup(props, context) { console.log(props.title) const { attrs, slots, emit, expose } context return { propsTitle: props.title } } }props是组件接收的外部属性它是响应式对象。但要注意对props对象进行结构会导致响应性丢失比如const { title } props之后title只是一个普通字符串父组件更新title时这个局部变量不会跟着变。推荐的做法是直接用props.title或者通过toRefs把需要拆的属性转成ref。context是一个普通对象包含四个常用成员attrs没有在props中声明的非props属性例如class、id、自定义透传属性。slots插槽内容。emit用于触发自定义事件。expose用于控制父组件通过模板ref访问子组件实例时可访问的内容。在这四个成员里expose和setup返回值的关系最紧密。如果setup返回的对象中包含了大量内部方法但你又不想全部暴露给父组件可以使用expose指定暴露清单。在普通setup写法中返回对象默认会混入渲染上下文而expose决定的是父组件拿ref时能访问到什么。2. setup的返回值有哪几种形态分别决定了什么2.1 返回对象最常见也是模板数据来源setup返回一个普通对象时对象中的每个属性都会成为渲染上下文的一部分。模板可以直接使用这些属性不需要加额外前缀。export default { setup() { const user { name: zhangsan, age: 18 } return { user } } }模板中既可以访问整个对象也可以访问对象属性template div{{ user.name }} - {{ user.age }}/div /template这个对象还可以包含函数比如事件处理方法。函数返回给模板后可以直接绑定到事件上export default { setup() { const count ref(0) const add (step 1) { count.value step } return { count, add } } }template button clickadd(2)加2/button span{{ count }}/span /template这里add使用箭头函数是因为模板调用时不想依赖this。如果你在setup内写普通函数并依赖this比如this.count.value 1这里的this是渲染上下文代理虽然模板调用时能拿到一个实例代理角色但依赖它会让逻辑变得难以维护。组合式API的推荐风格是方法直接访问setup作用域内的变量而不是通过this。2.2 返回函数把渲染函数交给Vuesetup也可以返回一个函数这个函数会被当作组件的渲染函数使用。script import { h } from vue export default { setup() { const title 通过渲染函数渲染的标题 return () h(div, { class: render-box }, title) } } /script这个例子中setup没有返回对象而是返回了一个箭头函数箭头函数内部调用h函数生成虚拟DOM。组件最终渲染的内容就是这个h函数描述的内容。如果组件同时写了template模板setup返回渲染函数时渲染函数的优先级更高template中的内容会被忽略。这是初学阶段最容易困惑的一个地方现象是“模板明明写了内容页面却只渲染h函数里的内容”原因就是setup返回了渲染函数。2.3 返回函数时如何写JSX更常见的渲染函数写法是JSX。Vue3中使用JSX需要安装插件vitejs/plugin-vue-jsx。npm install vitejs/plugin-vue-jsx -D在vite.config.js中注册插件import { defineConfig } from vite import vue from vitejs/plugin-vue import vueJsx from vitejs/plugin-vue-jsx export default defineConfig({ plugins: [vue(), vueJsx()] })启用JSX后setup可以直接返回JSX片段import { ref } from vue export default { setup() { const visible ref(false) return () ( div p状态{visible.value ? 已开启 : 已关闭}/p button onClick{() (visible.value !visible.value)}切换/button /div ) } }注意这里和模板中有一个明显差异在模板中ref会自动解包不需要写.value但在JSX的setup返回函数里你需要写visible.value来读取值因为这段代码运行在JavaScript上下文中。2.4 对象的返回范围和渲染函数的选择返回对象适合大多数业务组件因为模板语法简单、可读性好。返回渲染函数适合以下场景组件结构高度动态需要根据数据和条件生成不同层级的节点。需要深度操作虚拟DOM例如给某个节点批量添加子节点。编写通用渲染组件或库组件时希望避免模板编译开销。对于普通业务项目优先返回对象把复杂结构拆成子组件。渲染函数是Vue提供的底层能力能用好它但不建议在整个项目中大量手写h函数可维护性会明显下降。3. 返回值中ref、reactive、computed的解包规则3.1 ref返回后为什么模板中不用写.valuesetup返回一个ref对象时模板中访问的是ref内部的值而不是ref对象本身。import { ref } from vue export default { setup() { const count ref(0) return { count } } }template p{{ count }}/p button clickcount增加/button /template这里模板中的count会自动解包。之所以能做到这一点是因为Vue在处理setup返回的对象时会对返回对象中的ref值做一层浅层解包处理。注意“浅层”这个词只有对象顶层是ref时才会自动解包嵌套在对象内部的ref不会。const store reactive({ list: ref([]) })模板中访问store.list时可以直接拿到数组因为reactive内部也会自动解包。但如果写的是const state { nested: { value: ref(0) } }state.nested.value在模板中的表现就不会那么直观需要通过.value访问。3.2 reactive返回对象不用手动解开返回reactive对象时模板访问属性直接通过点号import { reactive } from vue export default { setup() { const form reactive({ username: , password: }) const submit () { console.log(form.username, form.password) } return { form, submit } } }template input v-modelform.username / input v-modelform.password / button clicksubmit提交/button /templatereactive对象本身是一个Proxy包装的响应式对象无需在模板里再调用.value。和ref相比reactive更适合表示一组结构化数据而ref更适合表示单个基础值。但两者可以混合使用关键是理解返回值在模板中的访问方式。3.3 computed返回值本质上是refcomputed创建的实例是一个只读ref对象所以setup返回computed后模板中可以直接访问值import { ref, computed } from vue export default { setup() { const price ref(100) const count ref(2) const total computed(() price.value * count.value) return { total, price, count } } }template p单价{{ price }}/p p数量{{ count }}/p p总价{{ total }}/p /template这里total在模板中可以直接使用而不是total.value。但如果在setup函数体内访问computed的结果必须写成total.value。这一条很容易踩坑在setup里写了console.log(total)结果输出的是一个ComputedRefImpl对象而不是数字于是怀疑computed用错了。实际上没有用错只是你没有在JavaScript环境中加.value。3.4 返回方法时建议使用闭包而不是this方法是返回值的一部分。在模板中可以通过事件绑定调用。推荐将所有方法定义为普通函数或箭头函数直接使用setup作用域中的响应式变量。export default { setup() { const list ref([]) const addItem () { list.value.push(item-${list.value.length 1}) } return { list, addItem } } }不建议这样写export default { setup() { const list ref([]) return { list, addItem() { this.list.push(item) } } } }虽然在模板调用时this可能指向渲染上下文代理可以访问到list但这个行为依赖Vue内部实现机制不如闭包直接引用list.value稳定。4. 用一个真实接口案例演示setup返回值的完整链路4.1 使用Vite搭建最小Vue3项目setup返回值脱离真实项目理解起来比较抽象这里用一个Vite Vue3项目演示完整链路。环境要求工具版本建议说明Node.js18及以上Vite 5以上要求Node 18npm8及以上包管理器Vue3.4核心库创建项目npm create vitelatest vue3-setup-demo -- --template vue cd vue3-setup-demo npm install npm install axios npm run dev访问终端输出的本地地址看到Vue默认页面说明项目环境正常。4.2 数据展示组件定义状态、请求方法并返回在src/components/UserList.vue中写一个用户列表组件通过axios请求接口把loading和数据状态保存在setup中。template div p v-ifloading加载中.../p p v-else-iferror{{ error }}/p ul v-else li v-foruser in users :keyuser.id {{ user.name }} - {{ user.email }} /li /ul /div /template script import { ref, onMounted } from vue import axios from axios export default { setup() { const loading ref(true) const error ref() const users ref([]) const loadUsers async () { loading.value true error.value try { const { data } await axios.get(https://jsonplaceholder.typicode.com/users) users.value data } catch (err) { error.value 请求失败 err.message } finally { loading.value false } } onMounted(loadUsers) return { loading, error, users, loadUsers } } } /script这个组件展示了setup返回值的几个典型特点loading、error、users是三个独立状态分别控制页面不同分支。loadUsers是一个需要在生命周期中执行的函数它被定义后既在onMounted中调用也返回给模板作为刷新按钮的事件处理。模板访问的都是return出来的名字没有return的变量不会在模板中生效。添加刷新按钮template div button clickloadUsers重新加载/button p v-ifloading加载中.../p p v-else-iferror{{ error }}/p ul v-else li v-foruser in users :keyuser.id {{ user.name }} - {{ user.email }} /li /ul /div /template这样loadUsers不仅用于初始化还用于用户交互函数复用一次定义多处使用是setup返回函数的典型场景。4.3 setup内直接执行异步请求和onMounted的区别有人会把请求直接写在setup函数体中setup() { const users ref([]) axios.get(/api/users).then(res { users.value res.data }) return { users } }这种写法在简单场景下能工作但它有两个问题请求时机不在可控生命周期内如果组件被缓存或切换路由请求可能被重复触发或提前触发。无法统一处理loading状态。推荐使用onMounted中调用请求函数明确请求生命周期。如果需要在页面加载前获取数据并用数据控制路由跳转才考虑async setup配合Suspense这点下一部分展开。5. async setup返回Promise为什么必须配合Suspense5.1 async setup直接使用会看到什么现象把setup标记为asyncexport default { async setup() { const res await fetch(https://jsonplaceholder.typicode.com/todos/1) const data await res.json() return { data } } }页面会渲染空内容同时控制台出现警告Component Anonymous setup() returned a Promise, but no Suspense boundary was found意思是setup返回了一个Promise但组件外部没有Suspense边界来处理异步状态。原因在于async函数必然返回Promise。模板渲染时如果setup结果是一个PromiseVue不知道什么时候算“数据准备好”自然无法同步渲染组件内容。Suspense组件就是用来包裹这种异步组件让Vue知道在Promise resolve之前展示fallback内容resolve之后再渲染正式内容。5.2 用Suspense包裹异步组件父组件中template Suspense template #default AsyncTodo / /template template #fallback p正在加载异步数据.../p /template /Suspense /template script import AsyncTodo from ./AsyncTodo.vue export default { components: { AsyncTodo } } /script子组件AsyncTodo.vuetemplate div pID: {{ todo.id }}/p p标题: {{ todo.title }}/p p完成状态: {{ todo.completed }}/p /div /template script export default { async setup() { const res await fetch(https://jsonplaceholder.typicode.com/todos/1) const todo await res.json() return { todo } } } /script运行后页面先显示“正在加载异步数据...”请求完成后显示数据。Suspense的出现解决了异步组合式逻辑返回值的渲染时机问题。5.3 生产项目中更常见的做法虽然async setup Suspense可以工作但生产项目中更常见的是用ref声明数据源。用loading控制加载状态。利用onMounted或路由守卫触发请求。数据请求失败时通过error状态渲染错误提示。这种方式对加载、错误、重试的掌控更细也更容易写单元测试。async setup适合组件本身就依赖异步资源才能渲染的场景例如“进入页面时数据不存在就不展示组件主体”。实际项目如果团队对Suspense还不熟悉优先使用onMounted loading模式。6. 从setup返回到