最近好几个朋友问我同一个问题想学 Vue3第一步环境搭建到底怎么搞网上教程不少但要么版本太老还在用 webpack要么直接甩几条命令让人照着敲敲完也不知道发生了什么。我当年从 Vue2 折腾到 Vue3 的时候也在环境上栽过跟头装完跑不起来、各种安装报错、几十个依赖不知道干嘛用的每一步都是坑。所以这篇系列教程的第一篇我就从 Vue3 初识讲起把环境搭建这件事掰开揉碎讲清楚保证你跟着做完能有个跑得起来的项目也明白每个命令、每个文件到底在干什么。这个内容适合完全没碰过 Vue3 的新手也适合 Vue2 老手想平滑过渡的甚至你只是想搭个 Vite 项目写点小玩意儿前半部分也能直接抄作业。1. Vue3到底新在哪里初识组合式API与响应式变革先不急着敲命令我们得先搞清楚 Vue3 和 Vue2 的根本区别在哪里。很多人学新东西容易陷入“会用但不懂为什么”的状态这会导致你后面看别人的代码、查官方文档时总觉得隔了一层。花个五分钟搞懂 Vue3 的核心设计思路比多敲十条命令都值。1.1 从 Options API 到 Composition API 的思维转变Vue2 时代我们写组件用的是 Options APIdata 放数据methods 放方法computed 放计算属性watch 放侦听器。代码一长你要反复上下拉滚动条因为一个业务逻辑的数据和方法被拆得七零八落。比如一段“用户登录”的逻辑data 里放着 username、passwordmethods 里放着 login 方法watch 里可能还有个监听表单变化的逻辑它们本该在一起却被结构强行拆开了。Vue3 的 Composition API 把“同一件事相关的所有代码”组织在一起。你可以在 setup 函数或script setup中把数据、计算属性、方法、侦听器按照业务逻辑自由组合。这样一段用户登录逻辑从数据声明到提交动作可以完整地写在一个代码块里。项目小的时候你感觉不到差别一旦组件超过三百行这种组织方式的优势就非常明显。再加上 Vue3 的script setup语法糖你甚至不需要写export default直接在script setup里声明变量、函数模板就能用。这让写 Vue 组件的感觉更像在写普通 JavaScript心智负担小了很多。这个语法糖是目前 Vue3 的主流写法本系列教程后面所有代码都会基于它展开。1.2 Proxy 取代 Object.defineProperty 的响应式原理Vue2 的响应式系统用的是Object.defineProperty它只能对对象的属性进行劫持这就导致了几个经典问题新增属性不是响应式的删除属性不是响应式的通过下标修改数组不是响应式的。你要用this.$set这种 API 去补救。Vue3 改用 ES6 的 Proxy 对整个对象进行代理。Proxy 可以拦截对对象属性的读取、赋值、删除、遍历等几乎所有操作所以新增属性、删除属性、数组下标修改这些问题从根上就解决了。代码上我们通过ref和reactive来声明响应式数据不再用data()返回对象。这里的实际经验是ref适合基本类型和需要逐层解构的复杂对象reactive适合嵌套层级较深的普通对象。但reactive有个坑——对函数传参解构后响应式会丢失。比如const { count } reactive({ count: 0 })这个 count 就变成了普通数字改它不会触发视图更新。所以我更习惯统一用ref写代码避免踩这种细碎的坑。2. 环境搭建前必须确认的三件事Node版本、包管理器、编辑器创建 Vue3 项目本身其实就一条命令的事但你选什么工具去执行这条命令往往决定了你后续开发是顺手还是折腾。我先说清楚环境层面最关键的三个前提多数卡壳问题都出在这一步。2.1 Node.js 版本不是越高越好但不能低于底线Vite 作为 Vue3 官方推荐的构建工具对 Node.js 版本有硬性要求。目前最新的 Vite 版本要求 Node.js 18 或 20。如果你用 Node.js 16很可能会在安装依赖或启动开发服务器时直接报错最常见的报错是You are using Node.js 16.x.x, but Vite requires Node.js 18。这里要明确一个原则Node.js 不必追求最新但要用活跃维护的稳定版。我目前主力环境是 Node.js 20 LTS长期支持版本生态兼容性好各类工具链都不会出幺蛾子。在终端里执行以下命令检查你的版本node -v npm -v如果版本低于 18建议去官网下载 LTS 版本重新安装。这里有个小提示如果你用 nvmNode Version Manager管理版本可以随时切换避免不同项目对 Node 版本要求不一致的尴尬。Windows 用户用 nvm-windowsmacOS/Linux 用户用 nvm都是同样的思路。2.2 包管理器选型npm、pnpm 还是 yarn有了 Node.jsnpm 会随之安装所以 npm 是零门槛选择。但 npm 有个明显的短板安装依赖慢node_modules 体积占用也大特别是项目一多磁盘空间会很紧张。我记得以前一个中等规模的 Vue3 项目node_modules 随便就超过 300MB。如果你的项目要长期维护我建议从一开始就使用 pnpm。pnpm 的核心优势是硬链接和内容寻址存储所有项目共享同一个依赖仓库第二次创建项目时依赖安装速度几乎是秒开。同时在磁盘占用上pnpm 能比 npm 节省一半以上的空间。实际测下来同样一个创建 Vue3 项目的流程npm 可能要两三分钟pnpm 基本十几秒就完成了安装。yarn 目前也有不少老项目在用但它的包管理器定位有点尴尬新项目里用的人越来越少。如果你想体验最快的安装速度和最干净的依赖管理走 pnpm 路线。安装 pnpm 的命令很简单npm install -g pnpm安装完可以验证一下版本pnpm -v本文后面的安装命令我会同时标注 npm 和 pnpm 两种写法。2.3 编辑器与 Volar 插件Vue3 开发的核心工具链编辑器我推荐 VSCode倒不是因为它多强大而是 Vue3 生态的工具链对它支持得最默契。这里有一个非常关键的插件取舍问题Vue2 时代大家都在用 Vetur但 Vue3 必须使用 Volar官方插件全称 Vue Language Features两者功能冲突不能同时开启。我第一次在 VSCode 里开 Vue3 项目时因为电脑里 Vetur 还在启用状态导致模板语法高亮错乱、script setup里的变量在模板中报未定义。排查了很久才发现是两个插件打架。解决方案很简单禁用 Vetur安装 Volar。VSCode 在新版中会把 Volar 的推荐状态直接绑定到.vue文件上。建议再装一个 TypeScript Vue Plugin配合 Volar 做类型检查。安装完成之后记得重启 VSCode让插件正常加载。3. 用 Vite 从零创建第一个 Vue3 项目完整实操记录环境确认完毕现在进入正题。创建项目我推荐使用 Vite它是 Vue3 官方推荐的构建工具。原理上可以这样理解Vite 在开发环境下利用浏览器原生 ES Module 加载能力直接按需编译不需要像 webpack 那样启动时就全量打包所以启动速度是毫秒级页面对应代码的更新也能在几百毫秒内完成热替换。这在日常开发中的体感差别非常大尤其是项目复杂度上来以后webpack 开发服务器启动要二十秒Vite 基本三秒内搞定。3.1 使用 create-vue 脚手架创建项目Vue 官方提供了create-vue这个脚手架工具基于 Vite 封装了完整的一套工程化配置能让我们通过交互式问答自动生成项目。比起直接用create-vite创建空白模板再手动配 Router、Pinia 这些create-vue能一步到位对新手友好得多。在目标目录下执行npm create vuelatest或者用 pnpmpnpm create vuelatest执行后终端会进入交互式问答常见选项和我的建议如下✔ Project name: … vue3-demo ✔ Add TypeScript? … No / Yes ✔ Add JSX Support? … No ✔ Add Vue Router for Single Page Application development? … No ✔ Add Pinia for state management? … No ✔ Add Vitest for Unit Testing? … No ✔ Add an End-to-End Testing Solution? … No ✔ Add ESLint for code quality? … Yes ✔ Add Prettier for code formatting? … Yes第一次学的话项目名可以叫vue3-demoTypeScript 可以先选 No省去类型问题的干扰等跑通核心流程之后再回来看类型系统会轻松很多。Router 和 Pinia 现在也别急着加后面系列教程讲路由和状态管理时会单独创建项目演示。ESLint 和 Prettier 建议直接选 Yes代码质量和格式化从第一天就养成好习惯。如果你需要 TypeScript 版本就在第一个 TypeScript 选项选 Yes脚手架会自动生成tsconfig.json以及对应的类型声明文件整体配置十分完整。3.2 安装依赖并启动开发服务器创建完成后命令行的提示信息会告诉你接下来的步骤cd vue3-demo npm install npm run dev用 pnpm 的话就是cd vue3-demo pnpm install pnpm run dev依赖安装完成后启动开发服务器终端会输出类似这样的信息VITE v6.x.x ready in 380 ms ➜ Local: http://localhost:5173/ ➜ Network: use --host to expose浏览器打开http://localhost:5173/你就能看到 Vue3 官方脚手架的默认首页。这个页面里通常会显示 Vue 的标志性 logo以及一堆官方文档和工具的链接。到这里你的第一个 Vue3 项目就跑起来了。整个过程从执行命令到页面出现顺利的话不到一分钟。我第一次用 webpack 配 Vue2 项目光折腾 loader 就花了半天现在这个速度坦白说确实是一种降维打击。4. 拆解新生成的项目结构这些文件和目录到底在干什么项目创建出来很多人第一反应是盯着目录发呆一堆文件和文件夹不知道干什么。别急这一节我就带你逐个拆开。理解这些文件的作用是后面写代码的基础只要搞懂这一层后续的路都好走。4.1 整体目录结构一览创建完成的项目目录长这样├── node_modules # 项目依赖包存放目录无需手动管 ├── public # 公共资源目录放图片、favicon 等 ├── src # 源码目录我们主要在这个目录里开发 │ ├── assets # 静态资源组件中直接引用的图片/样式 │ ├── components # 组件目录存放可复用的组件 │ ├── App.vue # 根组件 │ └── main.ts # 应用入口文件 ├── .vscode # VSCode 推荐配置 ├── index.html # 整个应用的 HTML 入口 ├── package.json # 项目配置与依赖清单 ├── tsconfig.json # TypeScript 配置文件如果选了TS ├── vite.config.ts # Vite 配置文件 └── README.md # 项目说明文档node_modules是依赖包存放的地方永远不需要手动改。public里放的是不经过构建处理的静态文件比如网站的 favicon 和外部图片资源。src目录是核心日常几乎全在 src 里打转。4.2 index.html 为什么是入口而不是 App.vue一个很关键的概念是Vue 应用其实是在 index.html 里挂载的。打开index.html能看到这么一段!DOCTYPE html html langen head meta charsetUTF-8 / meta nameviewport contentwidthdevice-width, initial-scale1.0 / titlevue3-demo/title /head body div idapp/div script typemodule src/src/main.ts/script /body /html注意这里的script typemodule src/src/main.ts它就是整个应用加载的起点。浏览器直接加载src/main.tsmain.ts 再把 Vue 应用挂载到div idapp这个节点上。理解了这一点你就明白了为什么 Vue 是一个“单页应用”index.html 只是空壳真正的内容全部由 JS 动态渲染。4.3 src/main.ts应用的启动脚本打开src/main.ts你会发现代码非常简洁import { createApp } from vue import App from ./App.vue const app createApp(App) app.mount(#app)createApp创建了一个 Vue 应用实例然后.mount(#app)把根组件App.vue挂载到 index.html 中那个idapp的标签上。回顾一下 Vue2 的写法new Vue({ render: h h(App) }).$mount(#app)两相对比Vue3 的写法去掉了一些魔法心智模型更清晰一个应用实例一个根组件一个挂载点干净利落。后续如果需要引入 Router、Pinia都是在这个文件里进行插件注册。4.4 App.vue单文件组件的基本形态打开src/App.vue这是最典型的 Vue3 单文件组件结构由三个部分组成script setup import HelloWorld from ./components/HelloWorld.vue /script template main HelloWorld / /main /template style scoped /* 样式代码 */ /stylescript setup这里写 JavaScript 逻辑template里写 HTML 结构style scoped里写样式。scoped关键字的意思是样式只对当前组件生效不会污染全局。HelloWorld组件通过 import 引进来直接在模板里像原生标签一样去使用。4.5 写一个最小计数器验证响应式链路为了验证响应式链路动手写一个最简单的计数器组件这个能让你对 setup、ref 和事件绑定有直观感受。在src/components/下新建一个文件命名为Counter.vue把App.vue里的 HelloWorld 替换成它script setup import { ref } from vue const count ref(0) function increment() { count.value } /script template div button clickincrement count is {{ count }} /button /div /template style scoped button { padding: 8px 16px; font-size: 16px; cursor: pointer; } /style在App.vue的script setup中引入script setup import Counter from ./components/Counter.vue /script template main Counter / /main /template保存之后回到浏览器你会发现页面几乎不需要任何额外的刷新就自动更新了。点击按钮计数器数字会同步变化。这就是 Vue3 的响应式系统和 Vite 热更新的直观体现。这里分享一个新手容易迷惑的点模板里写{{ count }}不需要加.value但script setup里访问ref数据却必须用count.value。这是因为ref返回的是一个包装对象模板编译器自动做了解包而 JS 代码里没有这个自动解包机制所以必须显式.value。记住这个差异写代码的时候就不会糊涂了。5. 环境搭建阶段的五个常见坑与排查思路环境搭建虽然流程短但每个人机器情况不一样早晚会碰到一些奇奇怪怪的问题。我把这几年来见过、踩过的高频坑集中列出来并附上完整的排查链路你按顺序排查基本都能解决。5.1 坑一Node 版本过低导致 Vite 启动失败这是新手期最常遇到的问题。前面强调过 Vite 对 Node 版本有硬性要求如果你 Node 版本停留在 16 或更低执行npm create vuelatest或者npm run dev时很可能出现Need to install the following packages: create-vuex.x.x Ok to proceed? (y)或者更直观的You are using Node.js 16.x.x, but Vite requires Node.js 18排查思路先node -v查看当前版本。我建议不要试图修改本机唯一的 Node 版本去迁就项目因为旧项目可能需要 Node 16。最佳实践是上一套 nvm按项目切换版本。5.2 坑二npm install 速度极慢或者直接报网络错误很多国内开发者卡在环境搭建第一关不是命令不会敲而是依赖下载慢到怀疑人生。npm 默认使用的 registry 服务器在境外网络波动大的时候一个依赖要下很久甚至直接失败。排查思路先确认是不是 registry 配置的问题。执行npm config get registry如果输出不是https://registry.npmmirror.com建议手动修改为国内镜像源npm config set registry https://registry.npmmirror.com执行完重新npm install速度会明显提升。换 pnpm 的话同样可以设置镜像pnpm config set registry https://registry.npmmirror.com5.3 坑三VSCode 中模板语法高亮失效或变量报未定义前面提到过 Vetur 和 Volar 冲突这个坑在刚接触 Vue3 的时候特别容易踩到因为很多人的 VSCode 是从 Vue2 时代一路用过来的Vetur 早就装好了。具体表现是.vue 文件打开后语法高亮完全错乱模板里使用script setup中定义的变量时VSCode 会提示“无法找到名称 xxx”但浏览器里项目运行正常。排查思路检查 VSCode 扩展列表禁用 Vetur安装 VolarVue Language Features。两个插件不能共存Volar 安装后还需要保证当前工作区用的是 Volar 的服务可以通过右下角状态栏查看。如果还是不行执行Developer: Reload Window命令重载一下窗口一般就能恢复。5.4 坑四默认端口 5173 被占用Vite 默认端口是 5173。如果你同时开着多个前端项目很可能出现端口被占的情况终端会提示Port 5173 is in use, trying another one...Vite 会自动找一个可用端口比如变成 5174不影响使用。但如果你希望固定端口可以在vite.config.ts中配置import { fileURLToPath, URL } from node:url import { defineConfig } from vite import vue from vitejs/plugin-vue export default defineConfig({ plugins: [vue()], server: { port: 5173, strictPort: true } })strictPort: true表示如果 5173 被占用就直接报错而不是静默切换端口这样你就能直观看到是哪个进程占的端口处理掉再启动。5.5 坑五使用 pnpm 时报 “The current path isnt a pnpm project”这个坑的典型情况是你之前用 npm 安装了依赖项目里生成了package-lock.json后来想改用 pnpm 安装执行pnpm install会提示当前不是 pnpm 项目因为检测到锁文件不一致。排查思路把它当成一次项目初始化走删掉旧的node_modules和package-lock.json然后再执行pnpm install。不要混合使用 npm 和 pnpm 的锁文件会让依赖版本不一致最后项目跑起来的行为也千差万别。6. 组合式API初体验用 ref 和 computed 完成一个有意义的组件运行起项目只是起点我们接下来把环境的作用发挥出来用几个核心 API 写一个带过滤功能的待办列表。这个小例子能覆盖 Vue3 组合式 API 最重要的几个概念响应式状态、计算属性、事件处理、列表渲染。6.1 在组件中组织数据与交互逻辑在 src/components 下新建TodoList.vue把之前的计数器替换掉。先定义一个待办任务数组和一个过滤状态script setup import { ref, computed } from 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 filteredTodos computed(() { if (filter.value active) { return todos.value.filter(t !t.done) } if (filter.value completed) { return todos.value.filter(t t.done) } return todos.value }) function addTodo() { const text prompt(请输入待办事项) if (text) { todos.value.push({ id: todos.value.length 1, text: text, done: false }) } } function toggleTodo(id) { const todo todos.value.find(t t.id id) if (todo) { todo.done !todo.done } } /script这里的关键点有三个todos用 ref 包裹整个数组是响应式的push 和修改元素的属性都会触发视图更新filteredTodos是 computed它依赖 todos 和 filter当任一依赖变化时自动重新计算filter同样是 ref模板中切换它的值会触发 filteredTodos 重新求值。6.2 模板渲染与样式联动模板部分这样写template div h3我的待办事项/h3 div button clickfilter all全部/button button clickfilter active未完成/button button clickfilter completed已完成/button /div button clickaddTodo新增待办/button ul li v-fortodo in filteredTodos :keytodo.id input typecheckbox :checkedtodo.done changetoggleTodo(todo.id) / span :style{ textDecoration: todo.done ? line-through : none } {{ todo.text }} /span /li /ul /div /templatev-for渲染列表:keytodo.id给每个列表项一个唯一标识帮助 Vue 高效更新 DOM。:checked是动态绑定属性change绑定事件。:style绑定一个对象根据 done 状态决定是否加删除线。然后回到 App.vue把Counter替换成TodoList。保存后浏览器里点击三个筛选按钮列表会实时切换文本框输入新的任务列表会自动多出该数据。这个过程的响应式链路是完整的数据驱动视图视图交互反过来修改数据中间没有任何手动 DOM 操作。如果你是从 Vue2 迁移过来的做完这个例子应该能明显体会到差别同样的功能Vue2 要在 data、methods、computed 三个选项里反复横跳而这里一切都在 setup 里线性书写代码上下文是连续的。这种体验上的变化是 Vue3 真正的核心价值。7. 后续学习路线与实用建议环境搭完、第一个组件写完你已经具备了自己动手折腾的能力。接下来我以实际经验给你画一条学习路线这是我带过几个新人之后不断打磨出来的流程。第一步花两三天把官方教程里的基础语法过一遍重点搞清楚模板语法、事件处理、组件传参、生命周期这几个部分。不用追求记住每个 API知道有这个东西、能查得到就行。第二步动手改造这个 TodoList。给它加自定义样式、加编辑功能、加重置筛选条件的功能。改代码的过程比看教程有用得多遇到不会的再去查记忆效果翻倍。第三步试着用 Vite 重新创建项目这次加上 Router 和 Pinia做两个页面互相跳转搞一个共享数据的场景。到这一步你对 Vue3 的工程化就有了整体感觉。第四步再回头去研究 Vue3 的原理比如响应式系统到底怎么实现的虚拟 DOM 做了哪些优化diff 算法怎么工作。有了前面的实践经验研究原理不会觉得枯燥反而处处能和你写过的代码对上号。在学习工具方面我习惯在浏览器里装 Vue DevTools 扩展。调试 Vue3 应用的时候它可以看到组件的层级结构、props、响应式数据状态排查问题效率会高很多。首次打开它需要允许在本地 file 协议下访问否则分析选项卡里看不到组件状态。还有一个小建议把这个初始模板项目备份一份。我都是把它推到代码仓库里存一个干净的初始分支。后面每写一个新的 Vue3 项目就从备份复制一份出来再改省去了每次都交互式选配置步骤的重复劳动。最后再啰嗦一句我自己的体会环境搭建这种事遇到报错别慌把报错信息完整读一遍绝大部分问题前面提到的这几类坑已经覆盖了。真遇到没见过的问题优先去看 Vite 和 Vue 的官方文档那上面才是最权威的答案。这篇系列教程的第一篇就到这里后续我会接着写 Vue3 的核心 API 实战、组件通信方案、路由与状态管理一步步把这个生态串起来。