Vue.js 安装教程:Node.js 环境检查与 Vite 项目初始化步骤
针对 Vue.js 初学者与前端工程师的实用安装教程。详细说明 Node.js 版本要求与检查方法、create-vue 脚手架交互式初始化步骤、依赖安装与开发服务启动,以及常见环境故障排查指南。
一、Node.js 与 npm 环境检查与版本要求
在创建 Vue 3 项目之前,首先需要明确一个核心问题:为什么必须先核验本机的 Node.js 环境?
现代前端工程已全面转向基于工具链的模块化开发,Vue 3 的官方构建体系深度依赖 Vite。Vite 在开发阶段依托现代浏览器原生的 ES 模块(ESM)规范,同时在底层使用 esbuild 完成第三方依赖的高性能预构建。这些现代化构建工具均需要调用较新版本的 Node.js 原生 API(例如 node:fs/promises 以及原生 fetch)。当前 Vue 3 与 Vite(Vite 5/6)官方设定的硬性要求是:Node.js 版本不得低于 18.0.0,官方长期维护推荐选用 Node.js 20.x 或更高版本的 LTS(长期支持版)。若本地 Node.js 处于 14.x 或 16.x 等旧版环境,在后续执行脚手架或安装依赖时会直接触发语法解析错误或模块缺失异常。
1. 查看已安装版本
打开操作系统的终端工具(Windows 用户可使用 PowerShell 或命令提示符,macOS / Linux 用户使用系统自带的 Terminal),输入以下命令检查 Node.js 与 npm 的版本号:
node -v
npm -v
10.5.0
如果终端输出的版本号如示例所示大于等于 v18.0.0,并且 npm 版本大于等于 9.0.0,说明当前环境完全达标,可以直接进入项目创建阶段。
2. 未安装或版本过低的处理办法
如果执行上述命令时,终端返回了两种常见异常情况之一:
- 提示
'node' 不是内部或外部命令,也不是可运行的程序:说明当前系统尚未安装 Node.js,或者安装后未将可执行文件目录加入系统的系统环境变量PATH中。 - 输出的版本号低于
v18.0.0(例如v14.17.0或v16.20.1):说明当前安装的运行时过旧,无法正常支持 Vite 最新版本的语法特性。
针对上述情况,推荐采取以下两种方式更新或安装运行环境:
方式一:官方安装包直接安装(适合新手)
访问 Node.js 官方网站(nodejs.org),在首页直接下载标有 LTS(Long Term Support,长期支持) 的安装包。下载后运行安装向导,按照默认配置逐步点击下一步完成安装。安装程序会自动更新系统 PATH 环境变量。安装完成后,需彻底关闭并重新打开终端窗口,再次运行 node -v 确认版本号已更新。
方式二:使用版本管理工具(适合多项目维护者)
若本地环境中需要同时维护旧有的 Webpack 项目(需要旧版 Node.js)与新的 Vue 3 项目,推荐使用 Node 版本管理工具(如 Windows 下的 nvm-windows,或跨平台的 fnm / nvm)。通过版本管理工具可以在不同版本之间即时切换,例如:
# 使用 nvm 安装并切换至最新 LTS 版本
nvm install --lts
nvm use --lts
二、使用 Vite 快速初始化 Vue.js 项目
在 Node.js 环境准备就绪后,即可着手生成 Vue.js 项目工程。在早期 Vue 2 时代,开发者普遍使用 @vue/cli;而对于 Vue 3,官方已全面转向以 Vite 为底层驱动的全新脚手架 create-vue。
1. 初始化命令选择
在终端中切换到打算存放项目的父级文件夹(例如 projects 目录),运行 Vue 官方推荐的标准脚手架命令:
npm create vue@latest
npm create vue@latest 是 npm init vue@latest 的等效简写。npm 会自动下载并临时执行官方的 create-vue 工具包,该工具包内部集成了 Vite 并预置了针对 Vue 3 的官方构建插件与模板。另一种常见的替代命令是通用脚手架 npm create vite@latest my-vue-app -- --template vue。两者的核心区别在于:通用 Vite 模板只生成极简的单一页面空白模板,而官方的 create-vue 提供了完善的生态交互选择(如 Router、Pinia、ESLint 等),更贴合实际项目需求。
2. 交互式配置项详解与选择依据
执行该命令后,脚手架会在终端中展示一系列交互式问答。根据开发目标,每个选项的含义与推荐选择如下:
| 配置提示项 | 功能含义 | 新手/初学推荐 | 工程化生产推荐 |
|---|---|---|---|
| Project name | 项目目录名称,也是生成的 package.json 中的 name 字段 | 输入自定义名称(如 my-vue-app) |
按业务模块命名(英文小写、短横线) |
| Add TypeScript? | 是否引入 TypeScript 强类型校验与语法支持 | No(专注理解 Vue 核心响应式概念) | Yes(提供编译期类型安全与自动补全) |
| Add JSX Support? | 是否支持在 JS 代码中书写类似 React 的 JSX 语法 | No(Vue 官方推荐模板语法 template) | 根据团队习惯选择,一般为 No |
| Add Vue Router? | 是否引入官方单页面路由管理库(vue-router) | No(初学基础组件时无需路由) | Yes(多页面/多视图应用必备) |
| Add Pinia? | 是否引入官方推荐的集中式状态管理库 | No(单组件练习通过 ref/reactive 即可) | Yes(管理跨组件用户态或全局数据) |
| Add Vitest / E2E? | 是否集成单元测试与端到端自动化测试框架 | No | 根据企业质量标准选配 |
| Add ESLint & Prettier? | 是否集成代码静态检查与代码风格自动格式化 | Yes(培养规范的代码编写习惯) | Yes(团队协作强制规范) |
若读者是首次学习 Vue 3,建议除了 ESLint 外,其余选项全部选择 No。这样生成的项目最为纯净精简,不会产生大量多余的示例代码,方便直观理清 Vue 3 的核心结构。
3. 生成的工程目录结构与核心文件解析
配置选项确认完成后,脚手架会迅速在当前路径下创建指定名称的项目文件夹。其生成的标准文件目录结构如下:
my-vue-app/
├── index.html # HTML 宿主页面与应用挂载入口
├── package.json # 项目清单,声明依赖包与 npm 运行脚本
├── vite.config.js # Vite 构建配置,注册 Vue 插件
├── public/ # 静态资源目录(打包时不经过处理直接拷贝)
│ └── favicon.ico
└── src/ # 业务代码核心目录
├── assets/ # 样式、图片等静态模块
├── components/ # 自定义可复用 Vue 组件
├── App.vue # 根组件(顶级单文件组件 SFC)
└── main.js # JavaScript 主入口文件
理解这几个核心文件之间的串联关系至关重要:
- index.html:与传统 Webpack 项目将 HTML 放在 public 目录不同,Vite 将
index.html直接放在项目根目录。它作为整个前端应用的原生入口点,内部声明了一个挂载容器<div id="app"></div>,并通过<script type="module" src="/src/main.js"></script>指令让浏览器直接发起对入口 JS 的请求。 - vite.config.js:负责配置 Vite 的行为。默认生成的配置中包含了
plugins: [vue()],该插件赋予了 Vite 编译和解析.vue单文件组件的能力。 - src/main.js:应用的引导逻辑。通过调用 Vue 导出的
createApp方法引入根组件App.vue,并通过app.mount('#app')将组件渲染并挂载到 HTML 页面上。 - src/App.vue:遵循 Vue 3 单文件组件(SFC)标准,分为
<script setup>(逻辑层)、<template>(结构层)和<style scoped>(样式层),是编写组件视图的主要载体。
三、依赖安装与本地开发服务器启动
脚手架执行完毕后,仅仅是在磁盘上生成了代码文件模板,并没有自动下载任何运行时库。此时项目中并没有 node_modules 文件夹,无法直接运行。必须按以下步骤进入项目目录并完成依赖安装。
1. 进入项目并安装依赖
在终端中执行以下命令进入项目根目录,并调用 npm 安装全部声明依赖:
cd my-vue-app
npm install
原理解析:执行 npm install 时,npm 会读取 package.json 中的 dependencies(生产依赖,包含 vue)和 devDependencies(开发依赖,包含 vite 和 @vitejs/plugin-vue 等)。npm 会递归解析这些包的依赖关系并下载到新生成的 node_modules/ 目录下,同时生成 package-lock.json 锁定具体版本与校验值。
registry.npmjs.org 拉取包。若在中国大陆网络环境下出现长时间卡顿或报错 ETIMEDOUT,建议设置合规的官方镜像源:npm config set registry https://registry.npmmirror.com配置完成后重新运行
npm install 即可明显提升下载速度。
2. 启动本地开发服务
依赖安装成功后,在项目根目录下执行开发启动脚本:
npm run dev
执行后,Vite 将会在极短时间内(通常在 200~400 毫秒左右)完成冷启动,并在终端中输出本地监听地址:
➜ Local: http://localhost:5173/
➜ Network: use --host to expose
➜ press h + enter to show help
按住键盘 Ctrl 键(macOS 用户按住 Command 键)并用鼠标左键点击终端中的 http://localhost:5173/ 链接,或者直接在浏览器地址栏手动输入该 URL,即可看到带有 Vue 官方标志和绿色标题的欢迎页面。这表明 Vue.js 项目已成功初始化并正常运行。
3. 热模块替换(HMR)实测与运作机理
为了直观体会 Vite 带来的开发效率提升,可以进行一次简单的热更新测试:
- 保持终端中的
npm run dev持续运行,不要关闭。 - 使用代码编辑器(如 VS Code)打开该项目中的
src/App.vue文件。 - 在
<template>区域找到标题文字,任意修改为<h1>我的第一个 Vue 3 应用</h1>并保存文件。 - 切回浏览器窗口,可以看到页面文字在瞬间完成了更新,而浏览器的刷新图标并未旋转。
机制解释:传统构建工具在文件变动时需要重新编译打包整个模块依赖树,而 Vite 内置了基于 WebSocket 的轻量级通信通道。当某个 .vue 文件发生变化时,Vite 的 Dev Server 仅精确对该文件进行重新编译,并通过 WebSocket 向浏览器推送差量模块更新包,浏览器端只替换变动的虚拟 DOM 节点。这使得不论项目规模扩展到几百还是几千个组件,其更新反馈速度始终保持在毫秒级。
四、安装与初始化过程中的常见故障排查
初次接触 Node.js 与 Vite 的开发者在不同操作系统或网络环境下,可能会遭遇几类高频问题。以下按照具体报错表现、根本原因与修复方法进行归纳:
1. Node.js 版本不匹配抛出语法错误
具体表现:在执行 npm run dev 或 npm install 时,终端输出类似以下错误:
或者:Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'node:fs'
产生原因:当前运行环境的 Node.js 版本低于 18.0.0。Node.js 14/16 对现代 ECMAScript 语法(如空值合并操作符 ??、可选链操作符 ?.)或带有 node: 前缀的原生内置模块支持不全,导致 Vite 核心脚本无法执行。
解决方法:先用 node -v 确认当前版本。通过 Node.js 官网下载最新的 LTS 版本安装包重新安装,或使用 nvm use --lts 切换版本。切换成功后,务必删除项目下的 node_modules 文件夹与 package-lock.json,然后重新运行 npm install。
2. 网络环境受阻导致依赖安装超时
具体表现:执行 npm install 时终端停顿在 [sill idealTree buildDeps] 长达数分钟不推进,最终报错 ETIMEDOUT 或 fetch failed。
产生原因:默认 npm 官方仓库服务器位于海外,国内部分网络环境对国外服务器访问受限或连接不稳定。
解决方法:将 npm 的注册源切换为中国大陆官方合规镜像源。在终端中执行:
# 设置镜像源
npm config set registry https://registry.npmmirror.com
# 检查当前生效源
npm config get registry
若输出为 https://registry.npmmirror.com/,说明镜像设置成功,此时再次执行 npm install 即可高速完成安装。注意不要轻易使用已经停止维护的旧版 cnpm 命令行工具,直接配置 npm 的 registry 是兼容性最好的方案。
3. Windows 平台 PowerShell 脚本执行策略受限
具体表现:在 Windows 系统的 PowerShell 中执行 npm run dev 或全局命令时,终端红字报错:
产生原因:Windows 默认将 PowerShell 的执行策略(Execution Policy)设定为 Restricted,禁止运行任何脚本文件(.ps1),这是系统的安全防御机制。
解决方法:以管理员身份打开 PowerShell 窗口,执行以下命令放宽当前用户的脚本执行限制:
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
在终端弹出提示时输入 Y 并回车确认。完成后关闭终端重新打开,即可正常执行 npm 与 Vite 的相关脚本。
4. 默认 5173 端口冲突
具体表现:执行 npm run dev 后,终端提示:Port 5173 is in use, trying another one...,且 Local 访问地址变为了 http://localhost:5174/。
产生原因与对策:这说明本机此前已经启动了另一个 Vite 项目且未退出,占用了 5173 端口。Vite 具备自动冲突规避机制,会自动尝试递增到 5174、5175 等可用端口,直接访问新端口即可正常开发,无需额外干预。若必须固定端口,可以在 vite.config.js 中配置 server: { port: 3000, strictPort: true }。
五、全流程关键检查点总结
回顾本篇教程,搭建一个规范的 Vue.js 3 工程由四个不可跳过的阶段构成。读者在实际操作中,可以对照下表快速核查各个环节的执行指标与交付物:
| 阶段序号 | 核心操作任务 | 对应执行命令 | 合格判定指标 |
|---|---|---|---|
| 01. 环境检查 | 确认 Node.js 与 npm 运行时 | node -v / npm -v |
Node.js >= 18.0.0 LTS,能够正常打印版本号 |
| 02. 脚手架拉取 | 初始化工程模板与交互选项 | npm create vue@latest |
成功生成包含 index.html 与 vite.config.js 的目录 |
| 03. 依赖装配 | 进入项目目录并下载依赖 | cd <app> && npm install |
生成完整的 node_modules/ 目录和 package-lock.json |
| 04. 本地验证 | 唤醒开发服务器并在浏览器核验 | npm run dev |
终端显示 localhost:5173,浏览器成功渲染欢迎页且 HMR 响应敏捷 |
当上述四个步骤全部顺利走通后,本地的 Vue.js + Vite 现代化开发基底便已全部构筑完成。接下来即可在 src/ 目录下创建业务组件、设计单页面路由或集成 Pinia 状态流,正式开展项目业务逻辑的编码工作。
JavaScript生成验证码后怎么与后端进行校验交互
2026-11-19 19:56:57
Node.js中http模块与Axios请求超时的配置区别
2026-11-18 17:17:24
LangChain Core 1.8.2 会影响哪些 Python 后端网关配置?
2026-11-18 11:53:55
Node.js使用Nodemailer通过SMTP发送邮件教程
2026-11-18 11:06:05
Node.js异步创建文件的最佳实践:async/await用法
2026-11-17 18:00:50








