1. 项目概述为什么你需要这份“极速上手手册”如果你正在看这篇文章大概率是带着一个明确的目标来的用最快的时间把 Vue 3 用起来做出点东西。你不是来听我长篇大论讲哲学、对比框架发展史的你关心的是“怎么装”、“怎么写”、“怎么跑”。这正是这份手册的初衷——它不追求大而全而是瞄准“上手”这个核心动作帮你绕过那些初期最容易卡住的坑直接进入能产出代码的状态。Vue 3 发布已经有一段时间了生态日趋成熟。但很多从 Vue 2 转过来的朋友或者刚接触前端的新手面对新的组合式 API、script setup语法糖、Vite 构建工具等一系列变化依然会感到一丝迷茫。官方文档固然详尽但对于追求效率的开发者来说有时需要一份更聚焦于“开干”的路线图。这份手册就是你的路线图。它会假设你有一些 JavaScript 和前端基础哪怕只是了解 Vue 2 的基本概念然后带你完成从环境搭建到写出第一个具备响应式、组件化特性的页面的全过程过程中我会穿插那些官方文档可能一笔带过但实际开发中高频出现的“琐碎”细节。2. 极速环境搭建与项目创建上手的第一步是把“战场”准备好。这里我们抛弃传统的 Webpack 模板直接使用 Vue 官方的下一代前端构建工具Vite。它的优势就是“快”无论是启动速度还是热更新体验都远超传统方案完美契合“极速”的主题。2.1 核心工具链安装与验证你的电脑上需要安装Node.js。这是现代前端开发的基石。前往 Node.js 官网下载 LTS长期支持版本安装即可。安装完成后打开你的终端Windows 的 CMD/PowerShell Mac/Linux 的 Terminal输入以下命令验证node -v npm -v这两条命令应该分别输出 Node.js 和 npmNode 的包管理器的版本号。如果报错“不是内部或外部命令”请检查环境变量或重新安装。接下来我们使用 npm 来安装 Vue 的项目脚手架工具。这里有一个关键选择是使用vue-cli还是create-vuevue-cli是 Vue 2 时代的官方脚手架功能强大但略显笨重。Vue 3 更推荐使用基于 Vite 的create-vue它由 Vue 核心团队维护生成的模板更现代、更轻快。执行以下命令安装并创建项目npm create vuelatest这个命令会下载并执行create-vue工具。接下来它会以交互式问答的方式引导你创建项目。注意你可能会在一些老旧教程里看到npm install -g vue/cli然后使用vue create my-project的方式。这种方式依然可行但生成的默认配置是基于 Webpack 的。对于全新的 Vue 3 项目我强烈推荐create-vue Vite 的组合以获得最佳的开发体验。2.2 项目配置选项的取舍心法执行npm create vuelatest后终端会问你项目名称输入一个你喜欢的比如vue3-quick-start。然后会进入一系列功能选项的勾选✔ Project name: … vue3-quick-start ✔ Add TypeScript? … No / Yes ✔ Add JSX Support? … No / Yes ✔ Add Vue Router for Single Page Application development? … No / Yes ✔ Add Pinia for state management? … No / Yes ✔ Add Vitest for Unit Testing? … No / Yes ✔ Add an End-to-End Testing Solution? … No / Yes ✔ Add ESLint for code quality? … No / Yes ✔ Add Prettier for code formatting? … No / Yes面对这些选项新手很容易犯“全都要”的错误但这会增加初期的理解成本。我的建议是TypeScript如果你是新手可以先选 No。TypeScript 能提供更好的类型安全和开发体验但初期学习 Vue 3 本身的概念已经有一定负担再加上 TS 的语法可能会让你分心。等核心 API 用熟练了再引入 TS 是更平滑的路径。JSX Support选 No。Vue 的核心模板是单文件组件.vue文件中的template。JSX 在 Vue 中是一种可选的、更接近 JavaScript 的书写方式通常在一些需要极强动态渲染能力的复杂组件中才会用到。上手阶段请先掌握好标准的模板语法。Vue Router选 Yes。这是构建单页面应用SPA的标配。即使你第一个项目只有一个页面先把它装上了解一下基本的路由配置对理解 Vue 应用的结构有好处。Pinia选 Yes。这是 Vue 官方推荐的状态管理库可以理解为 Vuex 的升级版API 更简洁。对于稍复杂一点的应用状态管理几乎是必须的。即使初始项目简单先装上它了解如何在组件间共享数据是很好的实践。Vitest E2E Testing都选 No。测试非常重要但在“极速上手”阶段我们的首要目标是让应用跑起来并理解核心概念。测试可以在后续项目迭代中逐步加入。ESLint Prettier都选 Yes。这两个是代码质量和格式化的利器能帮你养成好的编码习惯避免很多低级错误。它们基本是“零配置”生效的对初学者友好。根据以上建议选择后工具会生成项目文件。接着按照终端的提示进入项目目录安装依赖并启动开发服务器cd vue3-quick-start npm install npm run dev如果一切顺利终端会输出本地服务器的地址通常是http://localhost:5173。用浏览器打开它你应该能看到 Vue 的欢迎页面。至此你的开发环境已经就绪。3. 核心概念与组合式 API 快速入门项目跑起来了现在我们聚焦到代码上。Vue 3 最大的变化就是引入了组合式 API (Composition API)。它不再是 Vue 2 中通过data,methods,computed等选项来组织代码而是允许你使用导入的函数如ref,reactive来更灵活地组织和复用逻辑。3.1 响应式基石ref 与 reactive 的选用指南在组合式 API 中你必须显式地创建响应式数据。最常用的两个工具是ref和reactive。ref用于创建响应式的原始值如字符串、数字、布尔值或对象引用。在 JavaScript 中你需要通过.value属性来访问或修改它的值但在模板中Vue 会自动“解包”你直接使用变量名即可。// 在 script setup 中 import { ref } from vue const count ref(0) // 创建一个响应式数字初始值为0 console.log(count.value) // 在 JS 中访问值输出 0 count.value // 在 JS 中修改值 // 在 template 中 // button clickcount{{ count }}/button // 直接使用 count 无需 .value什么时候用ref当你定义的是一个基本类型值或者你不确定后续这个数据会不会被重新赋值时用ref。它是更通用、更安全的选择。reactive用于创建响应式的对象。它返回一个对象的响应式代理。import { reactive } from vue const user reactive({ name: 张三, age: 25 }) console.log(user.name) // 直接访问属性输出 张三 user.age 26 // 直接修改属性什么时候用reactive当你明确要定义的是一个不会整体替换的对象比如表单对象、配置对象并且希望直接通过属性访问无需.value时用reactive会更方便。实操心得很多新手会纠结到底用哪个。我的经验法则是优先使用ref。因为reactive在处理对象解构或函数传递时会失去响应性而ref则没有这个问题。当你需要一个响应式对象时也可以const obj ref({ a: 1 })通过obj.value.a来访问。虽然多了一层.value但心智负担更小更不容易出错。3.2 逻辑组织与复用组合式函数实战组合式 API 的精髓在于你可以把相关的响应式数据、计算属性和函数封装到一个独立的组合式函数中从而实现逻辑的复用。这比 Vue 2 的 mixin 更清晰、更强大。假设我们有一个“计数器”和“用户信息”的逻辑我们可以这样封装// composables/useCounter.js import { ref } from vue export function useCounter(initialValue 0) { const count ref(initialValue) const increment () count.value const decrement () count.value-- const reset () { count.value initialValue } // 返回所有需要暴露给组件的东西 return { count, increment, decrement, reset } } // composables/useUser.js import { reactive } from vue export function useUser() { const user reactive({ name: , age: 0 }) const updateName (newName) { user.name newName } const isAdult () user.age 18 return { user, updateName, isAdult } }然后在组件中你可以像搭积木一样使用它们script setup import { useCounter, useUser } from ./composables const { count, increment } useCounter(10) // 计数器从10开始 const { user, updateName } useUser() /script template div p计数: {{ count }}/p button clickincrement1/button p用户名: {{ user.name }}/p input v-modeluser.name placeholder输入用户名 / /div /template这种方式让组件的逻辑清晰可辨也极大地提高了代码的可测试性和复用性。4. 单文件组件与script setup语法糖详解Vue 的单文件组件.vue文件将模板、逻辑和样式封装在一起。Vue 3 的script setup语法糖让这种封装变得更加简洁。4.1script setup的魔法自动化的样板代码消除在 Vue 3 的早期组合式 API 需要写在setup()函数里并且需要返回模板中需要用到的数据和方法。script setup简化了这一切。!-- 传统 setup() 写法 -- script import { ref } from vue export default { setup() { const message ref(Hello) const changeMessage () { message.value Changed! } // 必须 return return { message, changeMessage } } } /script !-- script setup 语法糖写法 -- script setup import { ref } from vue const message ref(Hello) const changeMessage () { message.value Changed! } // 无需 return 顶层绑定自动暴露给模板 /script template div clickchangeMessage{{ message }}/div /template可以看到所有在script setup顶层声明的变量、函数、import都会自动暴露给模板使用。这减少了大量的样板代码。4.2 组件注册与通信的简化之道在script setup中引入的组件会自动注册无需再通过components选项注册。script setup // 引入的组件可以直接在模板中使用 import MyChildComponent from ./MyChildComponent.vue import { ref } from vue const title ref(父组件标题) /script template div !-- 直接使用 -- MyChildComponent :titletitle / /div /template父子组件通信也变得直观父传子通过props。子组件使用defineProps宏来声明。!-- 子组件 Child.vue -- script setup const props defineProps({ title: String, count: { type: Number, default: 0 } }) // 在 JS 中访问 props.title /script template div{{ title }} - {{ count }}/div /template子传父通过emit事件。子组件使用defineEmits宏来声明。!-- 子组件 Child.vue -- script setup const emit defineEmits([updateTitle]) const handleClick () { emit(updateTitle, 新的标题) } /script template button clickhandleClick点击更新标题/button /template !-- 父组件 Parent.vue -- script setup import { ref } from vue import Child from ./Child.vue const pageTitle ref(原始标题) const updateTitle (newTitle) { pageTitle.value newTitle } /script template Child update-titleupdateTitle / h1{{ pageTitle }}/h1 /template注意事项defineProps和defineEmits是编译器宏它们不需要导入会在script setup处理时被编译掉。你无法在普通的script标签或函数中使用它们。5. 路由与状态管理快速集成一个完整的应用离不开路由和状态管理。我们创建项目时已经选择了 Vue Router 和 Pinia现在来看看如何快速使用它们。5.1 Vue Router 4 基础路由配置与导航项目生成后路由相关的文件通常在src/router/index.js中。一个基本的路由配置如下import { createRouter, createWebHistory } from vue-router import HomeView from ../views/HomeView.vue const router createRouter({ history: createWebHistory(import.meta.env.BASE_URL), // 使用 HTML5 History 模式 routes: [ { path: /, name: home, component: HomeView }, { path: /about, name: about, // 路由级代码分割生成单独的代码块 (about.[hash].js) component: () import(../views/AboutView.vue) } ] }) export default router在根组件App.vue中你需要放置一个router-view组件作为路由内容的出口!-- App.vue -- script setup // 通常不需要在这里写太多逻辑 /script template nav router-link to/Home/router-link | router-link to/aboutAbout/router-link /nav !-- 路由匹配的组件将渲染在这里 -- router-view / /template在任意组件中你可以使用useRouter和useRoute组合式函数来进行编程式导航或访问当前路由信息script setup import { useRouter, useRoute } from vue-router const router useRouter() const route useRoute() // 当前路由对象包含 params, query 等信息 const goToAbout () { // 跳转到关于页面 router.push(/about) // 或者 router.push({ name: about }) } /script template p当前路由路径: {{ route.path }}/p button clickgoToAbout去关于页面/button /template5.2 Pinia 状态管理比 Vuex 更简单的选择Pinia 的 API 设计极其直观。首先我们定义一个 Store状态仓库。通常在src/stores目录下// src/stores/counter.js import { defineStore } from pinia // counter 是 store 的唯一 ID用于在 devtools 中识别 export const useCounterStore defineStore(counter, { // 状态相当于 data state: () ({ count: 0, name: Eduardo }), // 计算属性相当于 computed getters: { doubleCount: (state) state.count * 2, // 带参数的计算属性 greeting: (state) (msg) ${msg}, ${state.name}! }, // 动作相当于 methods可以是异步的 actions: { increment() { this.count // 在 actions 中通过 this 访问整个 store 实例 }, async fetchData() { const res await fetch(/api/data) // ... 处理数据并更新 state } } })在组件中使用这个 Storescript setup import { useCounterStore } from /stores/counter import { storeToRefs } from pinia // 用于解构保持响应性 const counterStore useCounterStore() // 直接从 store 中解构 state 会失去响应性 // const { count, name } counterStore // 错误 // 使用 storeToRefs 来解构 state 和 getter并保持响应性 const { count, name, doubleCount } storeToRefs(counterStore) // actions 可以直接解构因为它们是函数 const { increment } counterStore // 或者直接在模板中使用 counterStore.count const resetCount () { // 直接修改 state counterStore.count 0 // 或者使用 $patch 批量修改 // counterStore.$patch({ count: 0, name: New Name }) // 或者调用 action // counterStore.increment() } /script template div pCount: {{ count }} (来自解构)/p pDouble: {{ doubleCount }}/p pName from store: {{ counterStore.name }}/p button clickincrementIncrement (Action)/button button clickcounterStore.countIncrement (Direct)/button button clickresetCountReset/button /div /template避坑技巧直接解构 Store 的state会导致响应性丢失这是一个高频错误。务必使用storeToRefs工具函数来解构需要响应式的状态。而actions因为是函数引用可以直接解构。6. 常见问题与排查技巧实录在实际开发中你一定会遇到各种各样的问题。这里我记录了几个初期最高频的问题和解决方法。6.1 响应性失效的典型场景与修复这是 Vue 3 组合式 API 下最容易踩的坑。直接解构reactive对象const state reactive({ a: 1, b: 2 }) let { a, b } state // a, b 失去了响应性 a 3 // 不会更新视图修复使用toRefs将reactive对象的每个属性转换为ref。import { reactive, toRefs } from vue const state reactive({ a: 1, b: 2 }) let { a, b } toRefs(state) // a, b 现在是 ref a.value 3 // 视图会更新直接替换reactive对象的值const obj reactive({ nested: { count: 0 } }) obj.nested { count: 1 } // 直接赋值响应性连接会断掉修复避免直接替换嵌套对象而是修改其属性。或者对于深层嵌套考虑使用ref。const obj ref({ nested: { count: 0 } }) obj.value.nested { count: 1 } // 使用 ref 修改 .value 是安全的在异步回调中访问旧的响应式值const count ref(0) setTimeout(() { console.log(count.value) // 如果 count 在此期间被改变这里打印的可能不是最新的 // 对于依赖最新值的逻辑可能需要用 watch 或 watchEffect }, 1000)6.2 开发服务器与构建问题速查npm run dev启动失败端口被占用Vite 默认使用 5173 端口。可以在vite.config.js中配置server.port或者直接通过命令行指定npm run dev -- --port 3000。组件引入路径错误在script setup中引入组件时路径是相对于当前文件的。使用别名通常指向src目录这需要在vite.config.js中配置。create-vue项目默认已经配置好了 - /src。热更新失效或样式不生效尝试强制刷新浏览器CtrlF5。检查是否在style中使用了scoped这可能导致父组件样式无法影响子组件。对于全局样式建议在main.js或根组件中引入。生产构建后页面空白检查路由模式。如果使用了createWebHistoryHTML5 模式并且部署到非根路径如https://example.com/my-app/需要在vite.config.js中设置base: /my-app/并在路由配置中传递import.meta.env.BASE_URL。6.3 生态工具与插件推荐UI 组件库对于需要快速搭建后台管理系统或中后台项目推荐Element Plus对 Vue 2 的 Element UI 用户友好或Ant Design Vue。它们都提供了丰富的、为 Vue 3 优化的组件。图标库Iconify是一个集成了上百个图标集的统一框架配合iconify/vue或unplugin-iconsVite 插件可以按需引入成千上万的图标非常高效。HTTP 客户端Axios依然是主流选择。也可以考虑更现代的ofetchNuxt 团队出品或浏览器原生的fetch。开发调试务必安装Vue Devtools浏览器扩展。它的 Vue 3 版本能让你直观地查看组件树、状态、事件是调试的利器。7. 从“上手”到“实战”一个迷你待办应用示例让我们把上面所有的知识点串联起来构建一个具备增删改查、状态管理和路由的迷你待办事项Todo应用。这将帮助你巩固概念。7.1 项目结构与核心模块设计我们将创建以下文件src/ ├── App.vue ├── main.js ├── router/ │ └── index.js ├── stores/ │ └── todo.js # Pinia Store └── views/ ├── HomeView.vue # 主页展示待办列表 └── AboutView.vue # 关于页面示例用7.2 状态层Pinia Store 实现首先定义 Todo 的状态管理。// src/stores/todo.js import { defineStore } from pinia import { ref, computed } from vue export const useTodoStore defineStore(todo, () { // 使用组合式 API 风格定义 Store (更灵活) const todos ref([]) const filter ref(all) // all, active, completed // 计算属性 const filteredTodos computed(() { switch (filter.value) { case active: return todos.value.filter(t !t.completed) case completed: return todos.value.filter(t t.completed) default: return todos.value } }) const remainingCount computed(() todos.value.filter(t !t.completed).length) // 动作 function addTodo(text) { if (!text.trim()) return todos.value.push({ id: Date.now(), // 简单生成ID text: text.trim(), completed: false }) } function toggleTodo(id) { const todo todos.value.find(t t.id id) if (todo) { todo.completed !todo.completed } } function removeTodo(id) { const index todos.value.findIndex(t t.id id) if (index -1) { todos.value.splice(index, 1) } } function setFilter(newFilter) { filter.value newFilter } function clearCompleted() { todos.value todos.value.filter(t !t.completed) } return { todos, filter, filteredTodos, remainingCount, addTodo, toggleTodo, removeTodo, setFilter, clearCompleted } })7.3 视图层组件与路由联动接着创建主页视图组件。!-- src/views/HomeView.vue -- script setup import { ref } from vue import { useTodoStore } from /stores/todo import { storeToRefs } from pinia const todoStore useTodoStore() const { filteredTodos, remainingCount } storeToRefs(todoStore) const { addTodo, toggleTodo, removeTodo, setFilter, clearCompleted } todoStore const newTodoText ref() const handleAddTodo () { addTodo(newTodoText.value) newTodoText.value } /script template div classtodo-app h1极速待办/h1 div classinput-section input v-modelnewTodoText keyup.enterhandleAddTodo placeholder输入待办事项按回车添加 classtodo-input / button clickhandleAddTodo添加/button /div div classfilters button :class{ active: todoStore.filter all } clicksetFilter(all)全部/button button :class{ active: todoStore.filter active } clicksetFilter(active)未完成/button button :class{ active: todoStore.filter completed } clicksetFilter(completed)已完成/button /div ul classtodo-list li v-fortodo in filteredTodos :keytodo.id :class{ completed: todo.completed } input typecheckbox :checkedtodo.completed changetoggleTodo(todo.id) / span classtodo-text{{ todo.text }}/span button clickremoveTodo(todo.id) classdelete-btn×/button /li /ul div classfooter span{{ remainingCount }} 项待办/span button v-iftodoStore.todos.length remainingCount clickclearCompleted 清除已完成 /button /div div classnav-hint p去看看 router-link to/about关于页面/router-link/p /div /div /template style scoped .todo-app { max-width: 500px; margin: 0 auto; padding: 20px; } .todo-input { width: 70%; padding: 8px; margin-right: 10px; } .filters button { margin: 5px; padding: 5px 10px; } .filters button.active { background-color: #42b983; color: white; } .todo-list { list-style: none; padding: 0; } .todo-list li { padding: 10px; border-bottom: 1px solid #eee; display: flex; align-items: center; } .todo-list li.completed .todo-text { text-decoration: line-through; color: #999; } .todo-text { flex-grow: 1; margin-left: 10px; } .delete-btn { background: none; border: none; color: #ff6b6b; cursor: pointer; font-size: 1.5em; } .footer { margin-top: 20px; display: flex; justify-content: space-between; } .nav-hint { margin-top: 30px; font-size: 0.9em; color: #666; } /style最后配置路由让主页生效。// src/router/index.js import { createRouter, createWebHistory } from vue-router import HomeView from ../views/HomeView.vue const router createRouter({ history: createWebHistory(import.meta.env.BASE_URL), routes: [ { path: /, name: home, component: HomeView }, { path: /about, name: about, component: () import(../views/AboutView.vue) // 懒加载 } ] }) export default router现在运行npm run dev你的第一个功能完整的 Vue 3 应用就诞生了。它包含了响应式状态管理、组件化、路由导航以及基本的用户交互。通过这个实践你应该对 Vue 3 的核心开发流程有了一个扎实的感性认识。记住熟练的关键在于多写、多试、多查文档。当你遇到问题时Vue 的官方文档和其活跃的社区是你最好的后盾。