很多同學(xué)在從 Vue2 切換到 Vue3 的時(shí)候第一個(gè)繞不開(kāi)的坎就是組合式 API 中的setup函數(shù)。而在setup里寫(xiě)完一堆變量和方法之后到底要return什么、不return什么、為什么模板里拿不到數(shù)據(jù)這些問(wèn)題在初學(xué)階段非常容易讓人懵。本文將圍繞setup函數(shù)的返回值這一核心知識(shí)點(diǎn)從概念、寫(xiě)法、原理到實(shí)戰(zhàn)和排錯(cuò)完整梳理一遍“返回值”在 Vue3 中的真實(shí)作用。無(wú)論你是剛開(kāi)始學(xué) Vue3 的新手還是準(zhǔn)備面試時(shí)被問(wèn)到“setup 返回對(duì)象和返回渲染函數(shù)有什么區(qū)別”的進(jìn)階開(kāi)發(fā)者這篇文章都值得收藏備用。1. 背景與核心概念setup 到底是什么1.1 從 Options API 到 Composition APIVue2 時(shí)代我們寫(xiě)組件主要靠data、methods、computed、watch、生命周期鉤子這些選項(xiàng)組合出一個(gè)組件這種寫(xiě)法被稱為 Options API選項(xiàng)式 API。它的優(yōu)點(diǎn)是結(jié)構(gòu)清晰、約定明確缺點(diǎn)也很明顯當(dāng)一個(gè)組件邏輯變復(fù)雜時(shí)同一個(gè)功能的代碼往往被拆散在data、methods、watch等多個(gè)選項(xiàng)中維護(hù)起來(lái)非常割裂。比如一個(gè)搜索功能數(shù)據(jù)在data里方法在methods里監(jiān)聽(tīng)在watch里你要同時(shí)修改搜索邏輯就得來(lái)回跳轉(zhuǎn)。Vue3 引入了 Composition API組合式 API它的核心思想是把同一個(gè)邏輯關(guān)注點(diǎn)的代碼放在一起。而setup函數(shù)就是組合式 API 的入口。1.2 setup 函數(shù)的基本定位在 Vue3 組件中setup是一個(gè)特殊的選項(xiàng)它在組件創(chuàng)建之前執(zhí)行?？梢园裺etup理解為組件內(nèi)部的一塊“邏輯組織區(qū)域”所有組合式 API 的能力比如響應(yīng)式數(shù)據(jù)、計(jì)算屬性、監(jiān)聽(tīng)器、生命周期鉤子都可以在這個(gè)函數(shù)里使用。template div{{ message }}/div /template script import { ref } from vue export default { setup() { const message ref(Hello Vue3) return { message } } } /script這里最核心的一行就是return { message }。如果沒(méi)有這個(gè) return模板里就完全拿不到message。1.3 為什么 setup 需要返回值setup函數(shù)本質(zhì)上是組件實(shí)例內(nèi)部的初始化邏輯而模板中要使用的數(shù)據(jù)和方法必須通過(guò)返回值暴露給模板渲染上下文。也就是說(shuō)在setup內(nèi)部定義的變量默認(rèn)是“私有的”。只有通過(guò)return返回出去的內(nèi)容模板才能訪問(wèn)。返回的對(duì)象會(huì)被“展開(kāi)”到模板渲染上下文中相當(dāng)于 Vue2 中data和methods合并后的效果。這個(gè)設(shè)計(jì)也解釋了為什么很多新手第一次寫(xiě) Vue3 時(shí)會(huì)發(fā)現(xiàn)“數(shù)據(jù)定義了但頁(yè)面上什么都沒(méi)有”絕大多數(shù)情況都是忘記return了。2. 環(huán)境準(zhǔn)備與版本說(shuō)明2.1 開(kāi)發(fā)環(huán)境要求在開(kāi)始寫(xiě)代碼之前建議先確認(rèn)本地環(huán)境滿足基本要求工具版本建議說(shuō)明Node.js18 或更高Vite 構(gòu)建工具對(duì) Node 版本有要求建議使用 LTS 版本npm / pnpm / yarn最新穩(wěn)定版包管理器任選一種即可Vue CLI / ViteVite 推薦Vue3 官方腳手架create-vue底層就是 ViteVSCode最新版配合 Volar 插件獲得完整的模板類型提示注意版本需要根據(jù)你的項(xiàng)目實(shí)際情況調(diào)整本文示例以常見(jiàn)環(huán)境為例重點(diǎn)演示配置思路。2.2 創(chuàng)建 Vue3 項(xiàng)目推薦使用官方腳手架創(chuàng)建項(xiàng)目npm create vuelatest執(zhí)行后按提示輸入項(xiàng)目名稱選擇需要的功能如 TypeScript、Router、Pinia等待依賴安裝完成即可。cd vue3-setup-demo npm install npm run dev如果你更習(xí)慣 Vite 直接創(chuàng)建npm create vitelatest vue3-setup-demo -- --template vue2.3 示例項(xiàng)目結(jié)構(gòu)本文后面的代碼示例都基于下面這個(gè)精簡(jiǎn)結(jié)構(gòu)vue3-setup-demo/ ├── index.html ├── package.json ├── vite.config.js └── src/ ├── main.js ├── App.vue └── components/ └── UserCard.vue重點(diǎn)是components/UserCard.vue我們會(huì)一步步演示 setup 返回值的各種用法。3. setup 函數(shù)的返回值類型詳解3.1 返回對(duì)象最常用形態(tài)setup最常見(jiàn)的返回值類型是普通對(duì)象。對(duì)象的屬性會(huì)暴露給模板并且被模板自動(dòng)解包。template div p{{ name }}/p p{{ age }}/p button clickhandleClick點(diǎn)擊/button /div /template script import { ref } from vue export default { setup() { const name ref(張三) const age ref(28) const handleClick () { age.value } return { name, age, handleClick } } } /script這里需要注意幾個(gè)點(diǎn)name、age是ref對(duì)象模板中會(huì)自動(dòng)解包所以直接寫(xiě){{ name }}而不是{{ name.value }}。handleClick是普通函數(shù)直接返回即可。返回對(duì)象中的 key 名就是模板中的變量名。3.2 返回渲染函數(shù)非常規(guī)用法setup除了返回對(duì)象也可以返回一個(gè)渲染函數(shù)。這種寫(xiě)法比較少見(jiàn)但了解它有助于理解 Vue3 內(nèi)部渲染機(jī)制。script import { h } from vue export default { setup() { const msg 我是渲染函數(shù)輸出的內(nèi)容 return () h(div, msg) } } /script當(dāng)setup返回一個(gè)函數(shù)時(shí)這個(gè)函數(shù)會(huì)被當(dāng)作組件的 render 函數(shù)使用組件模板內(nèi)容會(huì)被完全忽略。也就是說(shuō)如果在這個(gè)組件里同時(shí)寫(xiě)了template和返回渲染函數(shù)最終渲染以渲染函數(shù)為準(zhǔn)。3.3 返回值的響應(yīng)式規(guī)則setup的返回值中只有響應(yīng)式數(shù)據(jù)才能觸發(fā)視圖更新。如果你返回一個(gè)普通變量模板雖然能顯示初始值但后續(xù)修改不會(huì)更新頁(yè)面。template div{{ count }}/div /template script export default { setup() { // 普通變量不是響應(yīng)式 let count 0 setTimeout(() { count 100 }, 1000) return { count } } } /script這段代碼運(yùn)行后頁(yè)面顯示 01 秒后變量count雖然變成了 100但頁(yè)面不會(huì)重新渲染。因?yàn)閏ount是普通變量Vue 無(wú)法追蹤它的變化。正確的做法是使用ref或reactive創(chuàng)建響應(yīng)式數(shù)據(jù)。3.4 返回值與模板編譯的關(guān)系從 Vue3 編譯原理來(lái)看模板會(huì)被編譯成基于渲染上下文的函數(shù)。return出去的對(duì)象本質(zhì)上成為渲染上下文的一部分。當(dāng)組件狀態(tài)發(fā)生變化時(shí)Vue 會(huì)重新執(zhí)行渲染函數(shù)并對(duì)比新舊虛擬 DOM最終更新視圖。因此“返回值”不只是給模板用的它還決定了組件的響應(yīng)式更新鏈路是否完整。4. 完整實(shí)戰(zhàn)案例用戶信息卡片組件這一節(jié)我們通過(guò)一個(gè)完整的用戶信息卡片組件把 setup 返回值的常見(jiàn)場(chǎng)景全部串起來(lái)。4.1 組件需求實(shí)現(xiàn)一個(gè)用戶卡片展示用戶名、年齡、簡(jiǎn)介支持點(diǎn)擊按鈕修改年齡同時(shí)展示“簡(jiǎn)介字?jǐn)?shù)”這一計(jì)算屬性。4.2 編寫(xiě) UserCard.vuetemplate div classuser-card h2{{ user.name }}/h2 p年齡{{ user.age }}/p p簡(jiǎn)介{{ user.bio }}/p p簡(jiǎn)介字?jǐn)?shù){{ bioLength }}/p button clickincreaseAge年齡 1/button button clickresetUser重置/button /div /template script import { reactive, ref, computed } from vue export default { setup() { // reactive 定義對(duì)象類型響應(yīng)式數(shù)據(jù) const user reactive({ name: 李四, age: 25, bio: 前端開(kāi)發(fā)工程師喜歡 Vue3 和 TypeScript }) // 獨(dú)立 ref 數(shù)據(jù) const count ref(0) // 計(jì)算屬性 const bioLength computed(() user.bio.length) // 方法 const increaseAge () { user.age } const resetUser () { user.age 25 count.value 0 } // 把所有需要在模板中使用的數(shù)據(jù)和方法返回出去 return { user, count, bioLength, increaseAge, resetUser } } } /script style scoped .user-card { border: 1px solid #ddd; border-radius: 8px; padding: 20px; max-width: 360px; } button { margin-right: 10px; padding: 6px 14px; cursor: pointer; } /style4.3 在 App.vue 中引入組件template div UserCard / /div /template script import UserCard from ./components/UserCard.vue export default { components: { UserCard } } /script4.4 運(yùn)行與驗(yàn)證執(zhí)行npm run dev打開(kāi)瀏覽器訪問(wèn)本地地址你應(yīng)該能看到用戶卡片展示李四的基本信息。點(diǎn)擊“年齡 1”按鈕年齡數(shù)字遞增頁(yè)面同步刷新。簡(jiǎn)介字?jǐn)?shù)由computed自動(dòng)計(jì)算。點(diǎn)擊“重置”按鈕年齡恢復(fù)為 25。4.5 關(guān)鍵點(diǎn)總結(jié)這個(gè)示例展示了setup返回值的幾個(gè)核心類型返回內(nèi)容類型模板中的使用方式userreactive 對(duì)象user.name、user.age直接訪問(wèn)屬性countref 對(duì)象模板自動(dòng)解包直接寫(xiě){{ count }}bioLengthcomputed 對(duì)象像普通變量一樣使用increaseAge函數(shù)綁定給事件如click5. setup 返回值與生命周期、this 的關(guān)系5.1 setup 的執(zhí)行時(shí)機(jī)setup是在組件實(shí)例創(chuàng)建之前執(zhí)行的早于beforeCreate鉤子。所以在setup內(nèi)部無(wú)法通過(guò)this訪問(wèn)組件實(shí)例。export default { setup() { // 這里拿不到 this console.log(this) // undefined } }這一點(diǎn)和 Vue2 的寫(xiě)法差別很大新手很容易踩坑。5.2 在 setup 中使用生命周期鉤子Vue3 的組合式 API 提供了一套帶on前綴的生命周期函數(shù)比如onMounted、onUpdated、onUnmounted。它們需要在setup函數(shù)內(nèi)同步調(diào)用注冊(cè)的生命周期邏輯會(huì)與組件實(shí)例關(guān)聯(lián)。template div{{ message }}/div /template script import { ref, onMounted, onUnmounted } from vue export default { setup() { const message ref() onMounted(() { message.value 組件掛載完成 console.log(mounted in setup) }) onUnmounted(() { console.log(組件卸載了) }) return { message } } } /script這里可以看到onMounted不是通過(guò)return暴露給模板的它只是注冊(cè)了一個(gè)回調(diào)因此不需要出現(xiàn)在返回值中。這也是理解“返回值”邊界的重點(diǎn)返回值只負(fù)責(zé)供模板渲染和事件綁定訪問(wèn)內(nèi)部邏輯和生命周期不需要返回。5.3 生命周期對(duì)比表Vue2 選項(xiàng)Vue3 組合式 API說(shuō)明beforeCreate不需要寫(xiě)setup本身就在實(shí)例創(chuàng)建前執(zhí)行created不需要寫(xiě)setup內(nèi)直接寫(xiě)邏輯beforeMountonBeforeMount掛載前mountedonMounted掛載后beforeDestroyonBeforeUnmount銷毀前destroyedonUnmounted銷毀后從使用角度你只需要記住Vue2 中寫(xiě)在created里的邏輯現(xiàn)在直接寫(xiě)在setup函數(shù)里其他生命周期需求用對(duì)應(yīng)的onXxx函數(shù)注冊(cè)。6. 深入拆解setup 返回值的“內(nèi)部機(jī)制”6.1 返回對(duì)象如何暴露給模板setup返回對(duì)象的屬性會(huì)被代理到渲染上下文。源碼層面Vue 會(huì)調(diào)用applyOptions處理組件選項(xiàng)把setup的結(jié)果合并到實(shí)例的setupState中。模板編譯后生成的渲染函數(shù)就是從這個(gè)上下文中取值的。用一句話概括return的對(duì)象是組件模板的“數(shù)據(jù)源”。6.2 模板解包機(jī)制要注意的邊界當(dāng)setup返回的對(duì)象中嵌套了ref對(duì)象時(shí)模板訪問(wèn)不需要加.value但在setup函數(shù)內(nèi)部操作時(shí)必須明確使用.value。const count ref(0) // setup 內(nèi)部修改 function add() { count.value // 必須寫(xiě) value }模板中則直接寫(xiě)button clickadd{{ count }}/button6.3 返回值與 props 的關(guān)系setup的第一個(gè)參數(shù)是props它包含了父組件傳入的所有屬性。父組件傳入的 props 本身是響應(yīng)式的但這些值不能直接通過(guò)return暴露給模板重新賦值。script export default { props: { title: { type: String, default: } }, setup(props) { console.log(props.title) return { // 不要把 props 的屬性重新賦值 // title: xxx 這種寫(xiě)法不能修改父組件傳入的值 } } } /script如果確實(shí)需要基于 props 派生新值推薦用computedimport { computed } from vue setup(props) { const upperTitle computed(() props.title.toUpperCase()) return { upperTitle } }6.4 返回 context 中的內(nèi)容setup的第二個(gè)參數(shù)是 context它包含attrs、slots、emit、expose等。這些內(nèi)容通常不需要整體返回但emit可以通過(guò)返回的方法暴露給模板使用script export default { emits: [submit], setup(props, context) { const handleSubmit () { context.emit(submit, { ok: true }) } return { handleSubmit } } } /script7. 常見(jiàn)問(wèn)題與排查思路在實(shí)際開(kāi)發(fā)中setup返回值相關(guān)的報(bào)錯(cuò)和異常非常多下面整理幾個(gè)高頻問(wèn)題。問(wèn)題現(xiàn)象常見(jiàn)原因解決思路模板中顯示 undefined 或空白忘記在setup中 return 對(duì)應(yīng)變量檢查 return 對(duì)象是否包含該變量頁(yè)面渲染了但修改數(shù)據(jù)后不更新使用了普通變量而不是ref/reactive改用響應(yīng)式 API 定義數(shù)據(jù)setup中打印this是 undefinedVue3 組合式 API 中不能訪問(wèn) this改用 props、context 或組合式 API返回渲染函數(shù)后模板不生效setup返回函數(shù)時(shí)會(huì)被當(dāng)作 render 函數(shù)刪除返回的渲染函數(shù)或改為返回對(duì)象控制臺(tái)警告Property xxx was accessed during render but is not defined模板中使用了未返回的變量在 return 對(duì)象中補(bǔ)充該變量父組件拿不到子組件內(nèi)部方法子組件沒(méi)有使用defineExpose暴露在script setup中顯式調(diào)用defineExposereactive對(duì)象被解構(gòu)后失去響應(yīng)性直接解構(gòu) reactive 對(duì)象會(huì)丟失代理使用toRefs或避免解構(gòu)7.1 典型報(bào)錯(cuò)案例忘了 returntemplate div{{ name }}/div /template script import { ref } from vue export default { setup() { const name ref(Hello) } } /script運(yùn)行后模板里name不顯示控制臺(tái)報(bào)未定義。修復(fù)方法就是在setup最后加上return { name }7.2 典型報(bào)錯(cuò)案例reactive 解構(gòu)丟失響應(yīng)性setup() { const user reactive({ name: 張三, age: 20 }) // 錯(cuò)誤解構(gòu)出來(lái)的是普通值 return { ...user } }這種寫(xiě)法在模板中雖然能看到初始值但修改user.age不會(huì)更新解構(gòu)后的變量。正確的寫(xiě)法有兩種第一種直接返回整個(gè)對(duì)象return { user }第二種用toRefs保持響應(yīng)性import { reactive, toRefs } from vue setup() { const user reactive({ name: 張三, age: 20 }) return { ...toRefs(user) } }8. 最佳實(shí)踐與工程建議8.1 約定 return 的命名規(guī)范在大型項(xiàng)目中setup返回的變量名就是模板中的變量名命名要盡量語(yǔ)義化。推薦使用數(shù)據(jù)變量用名詞userInfo、tableData、loading。方法用動(dòng)詞短語(yǔ)handleClick、fetchList、submitForm。布爾值用is/has開(kāi)頭isVisible、hasPermission。8.2 不要把所有邏輯都堆在 setup 里setup返回值設(shè)計(jì)得當(dāng)確實(shí)能減少模板中的數(shù)據(jù)來(lái)源混亂但如果把所有邏輯都塞進(jìn)一個(gè)setup組件依然會(huì)變得不可維護(hù)。推薦的做法是抽離組合式函數(shù)。// 文件路徑src/composables/useUser.js import { reactive, computed } from vue export function useUser() { const user reactive({ name: 王五, age: 30 }) const bioLength computed(() user.bio?.length || 0) const increaseAge () { user.age } return { user, bioLength, increaseAge } }然后在組件中直接使用script import { useUser } from ../composables/useUser export default { setup() { const { user, bioLength, increaseAge } useUser() return { user, bioLength, increaseAge } } } /script這樣setup函數(shù)本身變得非常簡(jiǎn)潔邏輯也更容易在多個(gè)組件間復(fù)用。8.3 警惕返回值中混入過(guò)多非響應(yīng)式數(shù)據(jù)對(duì)于模板中不需要變化的數(shù)據(jù)能不放setup返回值就不放。比如靜態(tài)配置、常量數(shù)組如果模板里只是展示一次可以直接寫(xiě)在模板里或者用普通變量導(dǎo)出。8.4 配合script setup減少樣板代碼Vue 3.2 之后官方推薦使用script setup語(yǔ)法糖這種寫(xiě)法最大的優(yōu)勢(shì)就是頂部聲明的變量和函數(shù)默認(rèn)可以在模板中使用無(wú)需手動(dòng) return。script setup import { ref } from vue const count ref(0) const increment () { count.value } /script template button clickincrement{{ count }}/button /template從編譯結(jié)果看script setup本質(zhì)上還是把內(nèi)容轉(zhuǎn)成setup函數(shù)的返回值只是幫我們省略了手動(dòng)編寫(xiě)return的步驟。對(duì)開(kāi)發(fā)體驗(yàn)的提升非常明顯。8.5 defineExpose需要主動(dòng)暴露時(shí)的補(bǔ)丁雖然script setup默認(rèn)對(duì)模板開(kāi)放所有頂層綁定但父組件無(wú)法直接訪問(wèn)子組件內(nèi)部的方法和數(shù)據(jù)。如果確實(shí)需要父組件通過(guò)ref調(diào)用子組件內(nèi)部方法必須使用defineExpose顯式暴露。!-- Child.vue -- script setup import { ref } from vue const count ref(0) const reset () { count.value 0 } defineExpose({ reset }) /script template div{{ count }}/div /template父組件中通過(guò)模板引用拿到子組件實(shí)例后調(diào)用resettemplate Child refchildRef / button clickresetChild重置子組件/button /template script setup import { ref } from vue import Child from ./Child.vue const childRef ref(null) const resetChild () { childRef.value.reset() } /script8.6 性能與可維護(hù)性注意點(diǎn)setup中的函數(shù)每次渲染都會(huì)被重新創(chuàng)建但如果依賴了響應(yīng)式數(shù)據(jù)依賴變化會(huì)觸發(fā)重新執(zhí)行渲染函數(shù)這是正常機(jī)制不需要刻意優(yōu)化。如果return的對(duì)象體積非常大模板中又沒(méi)有使用會(huì)導(dǎo)致渲染上下文中包含多余屬性雖然瀏覽器性能開(kāi)銷不明顯但從代碼整潔角度仍建議精簡(jiǎn)返回值。使用markRaw跳過(guò)不需要轉(zhuǎn)換為響應(yīng)式的對(duì)象可以減少不必要的代理開(kāi)銷。9. 總結(jié)與學(xué)習(xí)路線本文圍繞setup函數(shù)的返回值從概念、類型、原理、實(shí)戰(zhàn)到排查完整拆解了 Vue3 組合式 API 的核心入口。你掌握了幾個(gè)關(guān)鍵點(diǎn)setup是 Composition API 的入口創(chuàng)建時(shí)機(jī)早于beforeCreate。setup可以返回對(duì)象也可以返回渲染函數(shù)實(shí)際開(kāi)發(fā)中以返回對(duì)象為主。返回對(duì)象中的ref在模板中自動(dòng)解包在setup內(nèi)部必須使用.value。普通變量不會(huì)觸發(fā)視圖更新響應(yīng)式數(shù)據(jù)必須用ref或reactive創(chuàng)建。script setup語(yǔ)法糖能省去手動(dòng)return但在父組件訪問(wèn)子組件內(nèi)部方法時(shí)需要defineExpose。關(guān)于setup返回值的自查可以記一個(gè)很實(shí)用的口訣模板里要用的必須 return 出去不是響應(yīng)式數(shù)據(jù)的不要放進(jìn)來(lái)湊數(shù)需要暴露給父組件的記得到 defineExpose 里登記。下一步可以繼續(xù)學(xué)習(xí)ref與reactive的深層區(qū)別、provide/inject跨層級(jí)通信、watch與watchEffect的監(jiān)聽(tīng)策略以及script setup下的組件通信方式。把這幾個(gè)知識(shí)點(diǎn)串起來(lái)Vue3 組合式 API 的主干基本就通了。如果你在本地練習(xí)時(shí)遇到setup返回值相關(guān)的報(bào)錯(cuò)歡迎按文中表格逐條排查也可以多改幾行代碼看看頁(yè)面的實(shí)時(shí)反饋這種“改代碼—看結(jié)果”的循環(huán)對(duì)理解 Vue3 響應(yīng)式機(jī)制非常有幫助。