Vue3从零入门完整指南：核心语法、组件通信与实战项目

最近有不少刚开始学前端的小伙伴问我都 2026 年了新手学 Vue 到底该学 Vue2 还是直接学 Vue3我的建议非常明确直接上手 Vue3。Vue3 是当前 Vue 生态的绝对主流社区组件库、企业级项目、招聘要求都已经全面转向 Vue3。即使你完全零基础只要按照一条清晰的学习路线走也能在短时间内独立写出可用的前端项目。这篇文章我会从零开始完整梳理 Vue3 的入门路径包括环境搭建、核心语法、组件通信、路由、实战案例和常见报错排查。全文代码均来自可运行的示例你可以直接复制到本地项目里试验。1. 先认识 Vue3它到底是什么1.1 一句话理解 Vue3Vue 是一个用于构建用户界面的渐进式 JavaScript 框架。所谓“渐进式”指的是你可以只用它做页面上的一个小模块也可以用 Vue 全家桶构建一个完整的大型单页应用。Vue3 是 Vue 团队在 2020 年发布的下一代主版本。相比 Vue2Vue3 用 TypeScript 重写了核心源码底层响应式系统也从 Object.defineProperty 换成基于 Proxy 的实现同时引入了 Composition API组合式 API。这些改变带来的直接收益是更好的性能、更强的类型支持、更灵活的代码组织方式。1.2 Vue3 到底解决了什么问题先说一个 Vue2 中很典型的痛点。当组件逻辑复杂时data、methods、computed、watch 里的代码分散在不同选项中一个业务功能的相关代码会被拆得七零八落。比如一个搜索功能它的数据可能放在 data 里方法放在 methods 里监听器放在 watch 里维护起来非常痛苦。Vue3 的组合式 API 允许你把同一业务功能的代码写在一起通过一个 setup 函数集中组织逻辑。这种方式在小项目中看不出太大差距但在中大型项目中可维护性和代码复用性会有非常明显的提升。1.3 Vue2 和 Vue3 的核心差异入门阶段你不需要立刻掌握所有底层原理但至少应该清楚这两个版本的关键区别因为面试和日常看文档都会遇到对比维度Vue2Vue3响应式原理Object.defineProperty 逐个劫持属性Proxy 代理整个对象性能更高API 风格Options API选项式为主兼顾 Options API主推 Composition API逻辑复用mixins容易命名冲突自定义 Hook类似函数的组合方式TypeScript支持很差类型推导困难原生支持体验优秀数据绑定语法v-model 直接修改 prop 传入值支持多个 v-model 绑定组件通信更灵活异步组件写法通过对象配置使用 defineAsyncComponent构建工具主要是 WebpackVite 为主流启动极快全局 APIVue.use、Vue.component 等挂在构造函数上createApp 创建应用实例API 变得模块化2. 环境准备与项目创建2.1 必需工具Node.jsVue3 项目依赖 Node.js 环境。无论你用 npm、yarn 还是 pnpm都需要先安装 Node.js。打开 Node.js 官网下载 LTS 长期支持版本即可。安装完成后在命令行终端执行node -v npm -v如果能看到版本号说明安装成功。不同电脑版本号可能不同这不重要。需要提醒的是不要特意追求最新版 Node.jsLTS 版本在稳定性上更适合学习开发。2.2 使用 Vite 创建项目Vite 是 Vue3 官方推荐的构建工具。相比 WebpackVite 开发服务器启动极快因为它在开发环境下使用原生 ES Modules无需像 Webpack 那样预先打包全部模块。在空目录中执行npm create vuelatest这是官方脚手架命令会自动生成一套 Vue3 Vite 标准项目。执行过程中会出现几个交互式询问✔ Project name: … vue3-demo ✔ Add TypeScript? … No / Yes ✔ Add JSX Support? … No / Yes ✔ Add Vue Router for Single Page Application? … No / Yes ✔ Add Pinia for state management? … No / Yes ✔ Add ESLint for code quality? … No / Yes初学者建议先不引入 TypeScript等掌握 JavaScript 写法后再过渡。路由和状态管理工具如果当前用不到也可以先不勾选。然后进入项目目录安装依赖并启动cd vue3-demo npm install npm run dev启动成功后终端会输出一个本地访问地址默认是http://localhost:5173/在浏览器打开就能看到默认页面。2.3 项目目录结构说明创建好的项目结构大致如下vue3-demo/ ├── node_modules # 项目依赖包目录 ├── public # 公共静态资源不会被构建处理 ├── src # 核心源码目录 │ ├── assets # 静态资源如图片、样式 │ ├── components # 组件目录 │ ├── router # 路由配置如果创建时勾选了路由 │ ├── stores # Pinia 状态管理如果勾选 │ ├── views # 页面级组件 │ ├── App.vue # 根组件 │ └── main.js # 应用入口文件 ├── index.html # 页面入口 ├── package.json # 依赖和脚本配置 └── vite.config.js # Vite 配置文件入口文件src/main.js的默认内容如下// 文件路径src/main.js import { createApp } from vue import App from ./App.vue createApp(App).mount(#app)这段代码的含义是通过createApp创建 Vue 应用实例然后把根组件App.vue挂载到index.html中 id 为app的 DOM 节点上。3. Vue3 核心语法快速拆解3.1 认识 SFC 单文件组件Vue3 中一个页面或一个模块通常写在一个.vue文件中。这种文件叫 SFCSingle File Component单文件组件内部通常包含三部分template !-- 页面结构 -- /template script setup // 业务逻辑 /script style scoped /* 本组件专属样式 */ /stylescoped关键字表示样式只作用于当前组件避免样式污染其他组件是实战中默认写法。这里重点说一下script setup。它是 Vue3.2 开始提供的语法糖用来简化 Composition API 的书写。在script setup中声明的变量、函数、组件不需要额外的export default导出模板中可以直接使用。3.2 模板语法与事件绑定在.vue文件的template中使用{{ }}插值显示变量template div h1{{ message }}/h1 button clickhandleClick点击按钮/button /div /template script setup import { ref } from vue const message ref(你好Vue3) function handleClick() { message.value 你点击了按钮 } /script{{ message }}是插值表达式内容会响应式更新。click是v-on:click的简写形式用于绑定事件。ref()创建一个响应式变量在 JavaScript 中通过.value访问和修改在模板中会自动解包直接写message。3.3 ref 和 reactive两种响应式声明方式ref和reactive是 Vue3 中最常用的两个响应式 API。ref适用于基本类型和对象类型取值时需要.valueimport { ref } from vue const count ref(0) console.log(count.value) // 0 count.value console.log(count.value) // 1reactive只适用于对象类型可以省去.value直接通过属性访问import { reactive } from vue const user reactive({ name: 张三, age: 20 }) console.log(user.name) // 张三 user.age 21一个常见问题是什么时候用ref什么时候用reactive我的建议是简单场景直接用ref即使存对象也可以。ref语义更统一而且在模板中使用完全无需关心解包问题。reactive适合深层嵌套对象但如果你用解构赋值或展开运算符很容易丢失响应式连接这也是新手经常踩坑的地方。3.4 computed 计算属性computed用来生成依赖其他响应式数据的派生值。它和方法的区别在于computed有缓存只有依赖的数据变化时才会重新计算性能更好。下面是一个订单金额计算的例子template div p单价{{ price }} 元/p p数量{{ quantity }}/p p总价{{ totalPrice }} 元/p button clickquantity增加数量/button /div /template script setup import { ref, computed } from vue const price ref(99) const quantity ref(1) const totalPrice computed(() { return price.value * quantity.value }) /scripttotalPrice会随着price或quantity的变化自动更新。在模板中不需要调用totalPrice()直接当成变量使用即可。3.5 watch 和 watchEffectwatch用来监听响应式数据变化执行副作用逻辑比如请求接口、存储数据。import { ref, watch } from vue const keyword ref() watch(keyword, (newValue, oldValue) { console.log(搜索关键字从, oldValue, 变为, newValue) })watch还支持监听多个数据源传入数组即可watch([keyword, page], ([newKeyword, newPage], [oldKeyword, oldPage]) { console.log(keyword 和 page 都变化了) })与watch类似的还有watchEffect。它不需要明确指定监听谁而是自动追踪内部用到的所有响应式依赖import { ref, watchEffect } from vue const id ref(1) watchEffect(() { console.log(当前 id 是, id.value) })watchEffect适合不关心旧值、只需要执行副作用的场景。需要注意它一启动就会自动执行一次不像watch默认只在数据变化时才触发。3.6 生命周期钩子Vue3 组合式 API 的生命周期钩子名称需要加on前缀import { onMounted, onUnmounted } from vue onMounted(() { console.log(组件挂载完成可以操作 DOM 或请求接口) }) onUnmounted(() { console.log(组件销毁时执行清理工作如清除定时器) })高频使用的生命周期主要是onMounted因为数据请求通常放在这里执行。4. 组件通信父子组件传值组件化开发的本质是拆分功能再通过通信协作。以下三种通信方式是 Vue3 开发中使用频率最高的。4.1 父组件传值给子组件props父组件通过自定义属性传值子组件通过defineProps声明接收!-- 文件路径src/components/ChildCard.vue -- template div classcard h3{{ title }}/h3 p{{ content }}/p /div /template script setup defineProps({ title: { type: String, required: true }, content: { type: String, default: 暂无内容 } }) /script父组件使用子组件时!-- 文件路径src/App.vue -- script setup import ChildCard from ./components/ChildCard.vue /script template ChildCard titleVue3教程 content从入门到精通 / /template需要注意props 是单向数据流子组件不能直接修改 props 的值。如果子组件需要基于某个 prop 做修改应该通过事件通知父组件。4.2 子组件通知父组件defineEmits子组件通过defineEmits声明可以触发的事件并通过emit方法把数据传给父组件!-- 文件路径src/components/QuantityInput.vue -- template div button clickdecrease-/button span{{ modelValue }}/span button clickincrease/button /div /template script setup const props defineProps({ modelValue: { type: Number, default: 0 } }) const emit defineEmits([update:modelValue]) function increase() { emit(update:modelValue, props.modelValue 1) } function decrease() { emit(update:modelValue, props.modelValue - 1) } /script父组件中可以用v-model直接绑定数据template QuantityInput v-modelquantity / p当前数量{{ quantity }}/p /template script setup import { ref } from vue import QuantityInput from ./components/QuantityInput.vue const quantity ref(0) /script这里的update:modelValue是 Vue3v-model的约定事件名称。掌握了这种方式就明白 Vue3 中v-model的本质其实是 props 加事件的语法糖。4.3 跨层组件通信provide 和 inject当组件层级较深比如爷爷组件要传值给孙组件如果逐层通过 props 传递会非常繁琐。这时可以使用provide和inject。祖先组件中提供数据import { provide, ref } from vue const theme ref(dark) provide(theme, theme)任意后代组件中注入数据import { inject } from vue const theme inject(theme) console.log(theme.value) // dark这样无论跨越多少层组件都能直接拿到数据。需要注意的是provide和inject只适合祖先和后代之间通信不适合毫无嵌套关系的兄弟组件。4.4 组件通信总结通信场景推荐方案父组件传子组件props子组件传父组件defineEmits 触发事件父子双向绑定v-model defineModel跨多级组件传值provide / inject复杂全局状态Pinia 状态管理库5. Vue Router实现页面跳转5.1 安装与基础配置在命令行中安装路由npm install vue-router4Vue3 对应的路由版本是 Vue Router 4。创建路由配置文件// 文件路径src/router/index.js import { createRouter, createWebHistory } from vue-router import Home from ../views/Home.vue import About from ../views/About.vue const router createRouter({ history: createWebHistory(), routes: [ { path: /, name: home, component: Home }, { path: /about, name: about, component: About } ] }) export default router在入口文件main.js中注册路由// 文件路径src/main.js import { createApp } from vue import App from ./App.vue import router from ./router createApp(App).use(router).mount(#app)5.2 页面跳转的两种方式使用router-link组件进行页面导航template nav router-link to/首页/router-link router-link to/about关于/router-link /nav router-view / /templaterouter-view是路由出口当前匹配的组件会渲染在这个位置。在 JavaScript 中通过编程式导航跳转import { useRouter } from vue-router const router useRouter() function goHome() { router.push(/) }5.3 动态路由与路由参数动态路由适合详情页、个人主页这类需要根据 ID 展示不同内容的场景const routes [ { path: /user/:id, name: user, component: UserDetail } ]页面中获取参数import { useRoute } from vue-router const route useRoute() console.log(route.params.id)技术点本身不复杂但要注意一个高频问题路由跳转不刷新页面。如果从/user/1跳转到/user/2组件默认会被复用route.params变化不会触发组件重新初始化。解决办法是在组件中监听route参数import { watch } from vue import { useRoute } from vue-router const route useRoute() watch(() route.params.id, (newId) { // 根据新 id 重新请求数据 fetchUser(newId) })5.4 动态路由的进阶思考在后台管理系统中动态路由是一个绕不开的话题核心诉求是不同角色的用户登录后看到的菜单和可用页面不同。实现思路一般是用户登录后后端返回该用户的角色和对应路由权限。前端通过addRoute方法将路由动态添加到路由实例。同时根据路由信息渲染侧边栏菜单。这属于进阶实战内容入门阶段先掌握基础路由跳转和参数传递即可后续做后台项目时再深入。6. 完整实战从零实现一个待办事项到此为止基础语法已经讲完。接下来用一个完整的待办事项应用把前面学的知识点串起来。6.1 需求分析这个项目需要实现以下功能输入内容添加待办事项标记待办事项为完成状态删除待办事项根据“全部 / 未完成 / 已完成”筛选显示显示未完成数量6.2 组件结构设计src/ ├── App.vue # 根组件负责整体状态管理 ├── components/ │ ├── TodoInput.vue # 输入组件添加待办 │ ├── TodoList.vue # 列表组件接收数据和事件 │ └── TodoFilter.vue # 筛选组件6.3 实现代码App.vue 核心逻辑!-- 文件路径src/App.vue -- template div classtodo-container h1Vue3 待办事项/h1 p未完成{{ remainingCount }} 项/p TodoInput add-todoaddTodo / TodoFilter v-modelfilter / TodoList :todosfilteredTodos toggle-todotoggleTodo delete-tododeleteTodo / /div /template script setup import { ref, computed } from vue import TodoInput from ./components/TodoInput.vue import TodoFilter from ./components/TodoFilter.vue import TodoList from ./components/TodoList.vue const todos ref([ { id: 1, text: 学习 Vue3 基础语法, done: false }, { id: 2, text: 练习组件通信, done: true }, { id: 3, text: 完成一个实战项目, done: false } ]) const filter ref(all) const remainingCount computed(() { return todos.value.filter(todo !todo.done).length }) const filteredTodos computed(() { switch (filter.value) { case active: return todos.value.filter(todo !todo.done) case completed: return todos.value.filter(todo todo.done) default: return todos.value } }) function addTodo(text) { todos.value.push({ id: Date.now(), text, done: false }) } function toggleTodo(id) { const todo todos.value.find(item item.id id) if (todo) { todo.done !todo.done } } function deleteTodo(id) { todos.value todos.value.filter(item item.id ! id) } /script style scoped .todo-container { max-width: 500px; margin: 50px auto; padding: 20px; border: 1px solid #ddd; border-radius: 8px; } /styleTodoInput.vue 输入组件!-- 文件路径src/components/TodoInput.vue -- template div input v-modeltext placeholder请输入待办事项 keyup.entersubmit / button clicksubmit添加/button /div /template script setup import { ref } from vue const text ref() const emit defineEmits([add-todo]) function submit() { const trimText text.value.trim() if (!trimText) return emit(add-todo, trimText) text.value } /scriptTodoFilter.vue 筛选组件!-- 文件路径src/components/TodoFilter.vue -- template div button v-foritem in filters :keyitem.value :class{ active: modelValue item.value } click$emit(update:modelValue, item.value) {{ item.label }} /button /div /template script setup defineProps({ modelValue: { type: String, default: all } }) defineEmits([update:modelValue]) const filters [ { label: 全部, value: all }, { label: 未完成, value: active }, { label: 已完成, value: completed } ] /script style scoped .active { background-color: #42b983; color: white; } /styleTodoList.vue 列表组件!-- 文件路径src/components/TodoList.vue -- template ul li v-fortodo in todos :keytodo.id input typecheckbox :checkedtodo.done change$emit(toggle-todo, todo.id) / span :class{ done: todo.done }{{ todo.text }}/span button click$emit(delete-todo, todo.id)删除/button /li li v-iftodos.length 0暂无数据/li /ul /template script setup defineProps({ todos: { type: Array, required: true } }) defineEmits([toggle-todo, delete-todo]) /script style scoped .done { text-decoration: line-through; color: #999; } /style6.4 运行验证在项目根目录执行npm run dev打开浏览器你应该可以看到完整的待办事项功能可以添加、删除、标记完成、按条件筛选。未完成数量也会随着操作自动更新。这个项目虽然简单但已经覆盖了 Vue3 中最重要的几个知识点ref 响应式状态、computed 计算属性、组件化拆分、props 传递、defineEmits 事件通信、v-model 双向绑定。7. 深入进阶组合式函数与状态管理7.1 什么是组合式函数组合式函数Composable是利用 Composition API 封装的、带有响应式状态和副作用逻辑的函数。它的命名约定以use开头比如useUserList、useCountDown。举个简单例子。假设多个组件都需要执行倒计时逻辑可以把这段逻辑抽取成组合式函数// 文件路径src/composables/useCountDown.js import { ref, onUnmounted } from vue export function useCountDown(initialSeconds) { const seconds ref(initialSeconds) let timer null function start() { if (timer) return timer setInterval(() { if (seconds.value 0) { seconds.value-- } }, 1000) } onUnmounted(() { clearInterval(timer) }) return { seconds, start } }在组件中使用script setup import { useCountDown } from ../composables/useCountDown const { seconds, start } useCountDown(60) /script template p{{ seconds }} 秒后重新发送/p button clickstart开始倒计时/button /template把逻辑抽成组合式函数后任何组件都可以复用这段倒计时功能。相比 Vue2 时代的 mixins组合式函数不会有命名冲突逻辑来源也更清晰。7.2 状态管理Pinia当多个不相关的组件需要共享同一份全局状态时比如用户登录信息、购物车数据组合式函数就不够用了。这时需要引入状态管理库。Vue3 官方推荐的状态管理库是 Pinia。它的 API 设计非常简洁// 文件路径src/stores/counter.js import { defineStore } from pinia import { ref, computed } from vue export const useCounterStore defineStore(counter, () { const count ref(0) const doubleCount computed(() count.value * 2) function increment() { count.value } return { count, doubleCount, increment } })组件中使用 Pinia storescript setup import { useCounterStore } from ../stores/counter const counterStore useCounterStore() /script template p当前 count{{ counterStore.count }}/p p两倍{{ counterStore.doubleCount }}/p button clickcounterStore.increment()1/button /template可以看到Pinia 的写法与普通组合式函数几乎没有区别学习成本很低是 Vue3 状态管理的最佳选择。8. 高频问题排查与解决思路初学 Vue3 时几乎每个人都会遇到以下问题。这里整理成表格方便你对照排查。问题现象常见原因解决思路模板中显示 [object Object]直接在插值中输出对象没有访问具体属性用点语法访问对象属性或使用 JSON.stringify 临时查看ref 声明的变量在 JS 中修改后页面不更新忘记使用.value在 script 中访问 ref 变量必须写.value模板中会自动解包reactive 对象解构后丢失响应式直接解构 reactive 对象使用toRefs将响应式对象转为 ref 集合再解构v-for 报错提示 key 重复key 使用了 index优先使用 id 等唯一值作为 key组件标签名显示为自定义元素警告使用了未注册的组件或标签拼写错误检查组件是否 import 并在script setup中正确引入路由跳转后组件内容不更新复用了同一路由的组件实例使用 watch 监听route.params或route.fullPath变化后重新请求数据修改 props 的值为 undefined在子组件中直接修改 props应该通过 emit 事件通知父组件修改defineEmits 在模板中 $emit 失效事件名大小写不一致自定义事件名统一使用 kebab-case短横线或 camelCase 并在引用处保持一致后端接口跨域请求失败前后端域名不同服务器未配置 CORS开发环境下在 Vite 中配置 server.proxy 代理解决在 setup 中使用 axios 请求后页面不渲染响应式变量被覆盖且未使用 ref/reactive确认数据声明为ref或reactive赋值时修改.value8.1 排查顺序建议遇到页面与预期不符的情况推荐的排查顺序是打开浏览器开发者工具查看 Console 是否有报错信息。在script setup中打印数据和事件确认逻辑执行顺序。检查数据是否响应式直接在 JS 中修改后模板能否感知。检查组件之间的事件名和 prop 名是否拼写一致。查看 Network 面板确认接口请求是否正常返回。9. 实战开发中的最佳实践9.1 组件设计规范一个组件只做一件事。页面级组件放在views可复用的业务组件和通用组件放在components。组件内部代码量过大时优先拆分子组件而不是在同一个文件中堆积几百行代码。9.2 逻辑复用优先使用组合式函数抽函数时如果某段逻辑涉及到响应式状态且会被多个组件使用优先封装为use开头的组合式函数。比复制粘贴代码或混用 mixins 更可靠也更利于单元测试。9.3 命名规范组件文件使用 PascalCase例如UserCard.vue。变量和方法使用 camelCase例如userList、fetchUserList。自定义事件名使用 kebab-case例如update:modelValue、delete-todo。组合式函数命名以use开头。9.4 合理使用 computed 和 watch能用computed的派生值就不要放在 watch 中修改。watch适合处理异步副作用比如搜索防抖、接口请求。尽量避免在 watch 回调中修改自己监听的响应式源容易造成死循环。9.5 接口请求的错误处理在实际项目中在setup中请求接口是高频场景。axios 和 fetch 都可以但一定要做错误处理不能只写成功回调script setup import { ref, onMounted } from vue import axios from axios const list ref([]) const loading ref(false) async function fetchList() { loading.value true try { const { data } await axios.get(/api/list) list.value data } catch (error) { console.error(请求列表失败, error) } finally { loading.value false } } onMounted(fetchList) /script同时要注意在onMounted中调用异步函数时组件可能已被销毁赋值操作会引发非必要警告。学习阶段不必处理这个边界问题但进入大项目后要保持敏感。9.6 生产环境构建与部署开发完成后执行构建命令npm run build构建产物默认输出到dist目录里面是压缩优化后的静态文件。将dist目录中的文件部署到 Nginx、静态服务器或对象存储中即可。如果路由使用了createWebHistory部署后刷新二级页面容易出现 404。这是因为前端路由依赖服务器回退到index.html。实战中要么后端配置 history 回退要么改用createWebHashHistory。10. 从入门到精通的完整学习路线如果你完全零基础建议按以下顺序推进JavaScript 基础Vue 本质上是对原生 JS 的封装。数组方法、对象解构、异步函数、Promise 这些知识点要先掌握否则会卡在业务逻辑上。Vue3 核心语法ref、reactive、computed、watch、生命周期。组件化开发props、defineEmits、provide/inject、插槽 slot。构建工具使用Vite 常用配置、环境变量、路径别名。路由与状态管理Vue Router 4、Pinia。实战项目从待办事项出发逐步挑战后台管理系统、H5 商城、内容管理平台等完整项目。工程化进阶TypeScript、ESLint、自动化测试、性能优化、组件库二次封装。每学一个新知识点都尝试写一个最小示例并运行。前端是一个“练”比“看”更重要的领域代码只有自己敲一遍、报错再排查才能形成真正的理解。Vue3 的官方文档目前比较完善包含中文版和交互式教程遇到不确定的 API 时优先查阅官方文档那里永远是信息最准确的地方。开始动手创建你的第一个 Vue3 项目吧遇到报错不要怕每个报错都是你提升定位问题的好机会。如果你在实践过程中遇到文档中没写清楚的坑欢迎在评论区留言交流我会尽力帮你一起排查。