Vue3——第 2 篇：开发环境搭建与第一个 Vue 应用

本篇定位在理解 Vue 的基本概念之后我们需要真正把代码跑起来。本篇将带你从零开始一步步搭建 Vue 3 开发环境创建并运行你的第一个 Vue 应用并深入理解项目目录结构。读完本篇你将拥有一个可以持续开发的 Vue 工作台。一、环境准备Node.js 与包管理器Vue 3 项目依赖Node.js环境。Node.js 是一个基于 Chrome V8 引擎的 JavaScript 运行时它让我们可以在服务器端运行 JavaScript更重要的是它带来了npmNode Package Manager——JavaScript 世界的包管理工具我们可以通过它下载和管理 Vue 及其生态依赖。1.1 安装 Node.js版本要求Vue 3 要求 Node.js16.0 及以上版本推荐使用最新的18.x LTS或20.x LTS长期支持版本。下载安装访问 Node.js 官网nodejs.org下载对应操作系统的 LTS 版本安装包.msi/.pkg/.tar.gz双击安装一路默认选项即可建议勾选自动安装必要工具安装完成后打开终端Terminal / CMD / PowerShell输入以下命令验证安装是否成功node-v# 输出类似v20.10.0npm-v# 输出类似10.2.3 进阶推荐建议使用nvmNode Version Manager来管理 Node.js 版本这样可以在不同项目间灵活切换 Node 版本避免版本冲突。macOS/Linuxcurl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bashWindows使用 nvm-windows1.2 选择你的包管理器有了 Node.js你就自动拥有了npm。但除了 npmVue 生态中还常用到另外两个包管理器你可以根据自己的喜好选择包管理器特点命令示例npmNode 官方默认稳定可靠npm installyarnMeta 出品速度快有 lock 文件保证一致性yarn addpnpm极力推荐速度快、节省磁盘空间、天然支持 monorepopnpm install本教程统一使用pnpm作为包管理器Vue 官方团队也普遍推荐。如果你尚未安装 pnpm可以通过npm install -g pnpm全局安装。二、编辑器配置VSCode Volar工欲善其事必先利其器。一个强大的编辑器配置能让 Vue 开发体验提升十倍。2.1 安装 Visual Studio Code如果你还没有安装编辑器请前往 code.visualstudio.com 下载并安装 VSCode。它是目前全球最流行的前端开发编辑器免费、开源、生态极其丰富。2.2 安装 Vue 专用插件核心必装在 VSCode 的扩展面板快捷键CtrlShiftX/CmdShiftX中搜索并安装以下插件① Vue - Official原 Volar—— 必装插件 IDVue.volar这是 Vue 3 的官方语言支持插件提供 Vue 单文件组件.vue的语法高亮、智能提示、类型检查、自动补全、格式化等核心能力。⚠️ 重要提醒如果你之前安装过VeturVue 2 时代的流行插件请务必禁用或卸载它。Vetur 与 Volar 会相互冲突导致 Vue 3 项目中出现各种奇怪的报错和语法提示错乱。Volar 对 Vue 3 TypeScript 的支持远超 Vetur。② TypeScript Vue PluginVolar 的 TS 辅助插件 IDVue.vscode-typescript-vue-plugin这个插件让 VSCode 内置的 TypeScript 语言服务能够识别.vue文件中的类型提供更精准的跨文件类型推导。③ 其他推荐辅助插件可选但强烈推荐插件名称插件 ID作用ESLintdbaeumer.vscode-eslint代码规范检查保持代码风格一致Prettieresbenp.prettier-vscode自动格式化代码一键美化Auto Close Tagformulahendry.auto-close-tag自动闭合 HTML 标签Auto Rename Tagformulahendry.auto-rename-tag自动同步修改对应的配对标签名Viteantfu.viteVite 项目的快捷运行与调试三、创建你的第一个 Vue 3 项目过去创建 Vue 项目需要手动配置 Webpack 等复杂构建工具。如今Vue 官方提供了新一代脚手架工具create-vue它基于 Vite 构建开箱即用秒级启动。3.1 使用 create-vue 创建项目打开终端进入你希望存放项目的目录如桌面或~/projects然后运行以下命令# 使用 npmnpmcreate vuelatest# 或使用 pnpm (推荐)pnpmcreate vuelatest命令解读create-vue是 Vue 官方最新一代的项目脚手架工具它会自动拉取模板并引导你进行项目配置。latest表示使用最新版本。3.2 交互式配置选项运行命令后终端会进入交互式问答模式。你只需按键盘的方向键和回车键进行选择✔ Project name: … my-first-vue-app ✔ Add TypeScript? … No / Yes (推荐选 Yes本教程全系列使用 TS) ✔ Add JSX Support? … No / Yes (一般选 No) ✔ Add Vue Router for Single Page Application development? … No / Yes (后续再讲先选 No) ✔ Add Pinia for state management? … No / Yes (后续再讲先选 No) ✔ Add Vitest for Unit Testing? … No / Yes (后续再讲先选 No) ✔ Add an End-to-End Testing Solution? … No / Cypress / Playwright (暂选 No) ✔ Add ESLint for code quality? … No / Yes (强烈建议选 Yes) ✔ Add Prettier for code formatting? … No / Yes (强烈建议选 Yes)推荐选择为了后续学习顺畅建议参考以下配置配置项选择说明Project namemy-first-vue-app项目名只能小写字母、数字、连字符TypeScript✅Yes后续教程全面基于 TS请一定开启JSX❌ NoVue 生态基本不用 JSX用模板语法Vue Router❌ No第 20 篇专项讲解届时再添加Pinia❌ No第 22 篇专项讲解Vitest❌ No第 33 篇专项讲解E2E Test❌ No暂不涉及ESLint✅ Yes保持代码规范Prettier✅ Yes自动格式化代码选择完毕后create-vue会自动生成项目结构并安装依赖这个过程可能需要几十秒到几分钟取决于网络状况。3.3 如果安装依赖失败怎么办由于网络原因特别是访问 npm 官方源较慢有时依赖安装会失败。此时可以尝试以下解决方案方案一使用国内镜像源# 设置淘宝镜像源pnpmconfigsetregistry https://registry.npmmirror.com# 重新安装依赖pnpminstall方案二使用官方脚手架手动安装在生成项目后进入项目目录手动执行安装cdmy-first-vue-apppnpminstall四、项目目录结构深度解析让我们进入刚刚创建的项目文件夹用 VSCode 打开它看看里面都有些什么。my-first-vue-app/ ├── .vscode/ # VSCode 配置目录 │ └── extensions.json # 推荐插件列表 ├── public/ # 静态资源目录不经过构建处理 │ └── favicon.ico # 网站图标 ├── src/ # 核心源代码目录重中之重 │ ├── assets/ # 资源目录图片、样式等会经过构建处理 │ │ ├── base.css # 基础全局样式 │ │ ├── logo.svg # Vue logo │ │ └── main.css # 主样式文件 │ ├── components/ # 公共组件目录 │ │ └── HelloWorld.vue # 示例组件 │ ├── App.vue # 根组件整个应用的入口组件 │ ├── main.ts # 应用入口文件创建 Vue 实例 │ └── vite-env.d.ts # Vite 环境变量类型声明 ├── .eslintrc.cjs # ESLint 配置文件代码规范 ├── .gitignore # Git 忽略文件配置 ├── .prettierrc.json # Prettier 配置文件代码格式化 ├── index.html # 宿主 HTML 文件真正的浏览器入口 ├── package.json # 项目配置文件依赖列表、脚本命令 ├── pnpm-lock.yaml # 依赖版本锁定文件pnpm 专用 ├── README.md # 项目说明文档 ├── tsconfig.json # TypeScript 编译配置 └── vite.config.ts # Vite 构建配置⚠️ 极简项目揭示一个 Vue 3 项目虽然文件众多但最核心的只有index.html容器、src/main.ts入口和src/App.vue根组件。其他文件都属于基础设施。下面我们逐一深入解析几个最重要的文件4.1 index.html —— 应用的容器!DOCTYPEhtmlhtmllangzh-CNheadmetacharsetUTF-8/linkrelicontypeimage/svgxmlhref/vite.svg/metanameviewportcontentwidthdevice-width, initial-scale1.0/titleVite Vue TS/title/headbody!-- Vue 应用的挂载点容器 --dividapp/divscripttypemodulesrc/src/main.ts/script/body/html关键点div idapp/div—— 这是 Vue 将要接管并渲染内容的挂载点。所有 Vue 生成的 DOM 内容都会插入到这个 div 内部。script typemodule src/src/main.ts—— 浏览器原生支持 ES Module直接加载入口文件main.tsVite 利用这一点实现了极速开发服务器。4.2 src/main.ts —— 应用的入口import{createApp}fromvue// 导入全局样式import./assets/main.css// 导入根组件importAppfrom./App.vue// 创建 Vue 应用实例挂载到 #app 元素上createApp(App).mount(#app)逐行解读createApp(App)—— Vue 3 的入口函数。它接收根组件App返回一个应用实例。.mount(#app)—— 将应用实例挂载到index.html中 id 为app的元素上。Vue 会接管该元素内部的所有内容。注意对比 Vue 2 的写法new Vue({...}).$mount(#app)Vue 3 的createAppAPI 更加清晰且避免了全局配置污染这是 Vue 3 的重要改进。 深入理解在 Vue 3 中createApp返回的应用实例是一个独立的应用上下文。如果你在同一页面中有多个 Vue 应用如微前端场景可以多次调用createApp它们互不干扰——这是与 Vue 2new Vue()全局单例的根本不同。4.3 src/App.vue —— 根组件单文件组件App.vue是一个单文件组件Single File Component简称 SFC它把模板、脚本、样式聚合在一个文件中script setup langts import HelloWorld from ./components/HelloWorld.vue import TheWelcome from ./components/TheWelcome.vue /script template header img altVue logo classlogo src./assets/logo.svg width125 height125 / div classwrapper HelloWorld msgYou did it! / TheWelcome / /div /header /template style scoped /* scoped 表示样式只作用于当前组件不会泄露到全局 */ header { line-height: 1.5; } /* ... 更多样式 */ /style结构拆解script setup—— Vue 3 的组合式 API 语法糖。setup表示代码在组件实例创建前执行处于beforeCreate和created之间。langts表示使用 TypeScript。template—— 组件的 HTML 模板。你在模板中写的任何内容都会被 Vue 编译并渲染。style scoped—— 样式部分。scoped属性使得样式仅对当前组件生效Vue 会自动为元素添加唯一属性如data-v-xxxxx来实现样式隔离。4.4 package.json —— 项目的身份证打开package.json我们可以看到项目的依赖和脚本命令{name:my-first-vue-app,version:0.0.0,private:true,scripts:{dev:vite,// 启动开发服务器build:vue-tsc vite build,// 构建生产版本先做类型检查preview:vite preview// 预览生产构建结果},dependencies:{vue:^3.4.0// 生产依赖Vue 核心库},devDependencies:{vitejs/plugin-vue:^5.0.0,// Vite 的 Vue 插件typescript:^5.2.0,// TypeScriptvite:^5.0.0,// Vite 构建工具vue-tsc:^2.0.0// Vue 的 TypeScript 命令行工具}}重点关注的scripts字段你后续开发最常用的命令命令功能使用场景pnpm run dev启动开发服务器热更新秒级启动开发阶段99% 的时间都在用它pnpm run build构建生产环境打包文件输出到 dist 目录上线部署前执行pnpm run preview本地预览生产包打包后检查效果五、运行项目看见 Hello World5.1 启动开发服务器在项目根目录下执行pnpmrun dev终端中将会输出类似以下信息VITE v5.0.10 ready in 356 ms ➜ Local: http://localhost:5173/ ➜ Network: use --host to expose ➜ press h enter to show help打开浏览器访问http://localhost:5173/你将看到 Vue 官方的欢迎页面恭喜你你的第一个 Vue 应用已经成功运行了5.2 体验热更新HMR保持服务器运行状态打开src/App.vue将template中的内容做简单修改template div h1我的第一个 Vue 应用/h1 pHello, Vue 3 World! /p /div /template保存文件CtrlS/CmdS神奇的事情发生了浏览器页面自动刷新并立即显示你刚刚修改的内容整个过程不到 1 秒。这便是Vite 的热模块替换HMR能力。它不同于传统的整页刷新F5而是只替换更新的模块保留页面状态开发体验极其流畅。5.3 修改 HelloWorld 看看完整流程我们尝试删除src/components/HelloWorld.vue中的示例代码改为我们自己的内容script setup langts // 定义父组件传递的属性 defineProps{ msg: string }() /script template div classcard h2{{ msg }}/h2 p这是从父组件传递过来的消息/p /div /template style scoped .card { padding: 20px; border-radius: 8px; background-color: #f9f9f9; } /style然后回到App.vue修改调用方式template div HelloWorld msg欢迎进入 Vue 的世界 / /div /template保存后页面即刻更新显示欢迎进入 Vue 的世界这是从父组件传递过来的消息这个简单的修改流程实际上已经完整地展示了一个 Vue 组件的运作模式父组件App通过prop属性msg向子组件HelloWorld传递数据。子组件使用defineProps接收数据并在模板中通过插值表达式{{ msg }}渲染。六、常见问题排查初次搭建环境难免会遇到一些问题。以下是几个高频问题及解决方案问题现象可能原因解决方案pnpm: command not found未全局安装 pnpm执行npm install -g pnpmvite命令无法识别依赖未安装成功删除node_modules和pnpm-lock.yaml重新执行pnpm install页面显示空白且无报错端口被占用或挂载点错误检查index.html中是否存在div idapp换用pnpm run dev -- --port 3000指定端口TypeScript 报红但能运行Volar 未正确识别项目在项目根目录执行pnpm run vue-tsc -- --noEmit或重启 VSCodeCtrlShiftP执行Developer: Reload Window保存后页面不自动刷新HMR 失效或文件监听未开启检查是否使用了网络驱动器重启开发服务器查看终端是否有错误日志七、本篇小结在本篇中我们完成了 Vue 3 开发环境从零到一的完整搭建主要成果步骤关键动作核心知识点环境准备安装 Node.js pnpmVue 3 要求 Node 16pnpm 是高效包管理器编辑器配置安装 VSCode Volar务必禁用 Vetur否则会冲突创建项目pnpm create vuelatest交互式配置推荐开启 TypeScript ESLint Prettier目录理解解析index.html/main.ts/App.vue#app是挂载点createApp创建 Vue 实例.vue是单文件组件运行项目pnpm run devVite 提供秒级启动和 HMR 热更新首轮修改修改模板内容直观体验「数据驱动视图」的响应式流程八、思考与练习动手实验尝试修改src/components/HelloWorld.vue的样式背景色为蓝色并观察修改后页面是否立即变化。加深理解在main.ts中把.mount(#app)改成.mount(#non-exist)保存后看页面会发生什么解释原因。版本升级尝试在package.json中将vue的版本号手动改成^3.5.0然后运行pnpm install升级到最新次版本观察是否存在兼容性问题。探索思考为什么 Vue 3 要设计createApp函数而不是像 Vue 2 那样直接new Vue()这解决了什么问题提示想想全局配置的污染问题下篇预告到目前为止我们已经有了一个可运行的项目环境。第 3 篇我们将正式进入 Vue 的模板语法学习——你将掌握{{ }}插值表达式如何渲染数据v-bind如何动态绑定 HTML 属性在模板中写 JavaScript 表达式的规则Vue 指令系统的全面概览准备好迎接 Vue 语法的核心魅力吧