很多刚开始接触 Vue 的朋友甚至一些写了两年 Vue 的开发者都容易在“开发环境搭建”这一步被折腾得够呛。我见过有人照着两三年前的教程装完环境结果项目跑起来全是红色报错也有人装好了 Node结果npm install卡了半小时没反应最后发现是源没配。我自己在几台新电脑上反复搭过 Vue 环境从 Windows 到 macOS 都踩过一轮今天这篇就把这套“最完整、无坑、一步到位”的 Vue 开发环境搭建流程整理出来从选型到落地每一步都告诉你为什么这么做以及踩坑之后怎么救。不管你用的是 Windows、macOS 还是 Linux照着这套流程走基本能一次跑通。1. 动手装 Node.js 之前先把这三个选型问题定下来很多人一上来就打开浏览器搜“Node.js 下载”装完发现版本不对项目又删了重来。其实真正合理的顺序是先把三个选型问题想清楚再动手。1.1 Node.js 版本别追新认准 LTSNode.js 的版本号分两种Current 和 LTS。Current 是当前开发版功能新但稳定性差很多第三方依赖还没跟上LTS 是长期维护版官方会持续打补丁生态兼容性最好。Vue 3 的官方脚手架和 Vite 都要求 Node 18 或更高版本所以 20 LTS 是目前最稳的选择22 LTS 也已经进入了维护期问题也不大。这里有个教训有次我在新笔记本上直接装了当时最新的 Node 23结果跑npm create vuelatest时一切正常但安装某个依赖时开始报ERR_INVALID_ARG_TYPE查了半天是那个依赖用了旧的原生模块跟新版本 V8 引擎不兼容。换成 Node 20 LTS 后一次通过。所以我的建议很明确不要去官网首页点那个大大的“当前版本”下载按钮点下方 LTS 那个按钮。如果你需要同时维护多个项目有些老项目要 Node 16新项目要 Node 20那就需要用版本管理工具。Windows 上推荐nvm-windowsmacOS/Linux 上推荐nvm后面我会专门说怎么配。1.2 包管理器npm 还是 pnpm先别纠结但你得知道差别官方脚手架默认用的是 npm所以新手直接用 npm 完全没问题。但如果你打算长期做 Vue 开发我建议尽早了解 pnpm。区别在哪npm 安装依赖时会把每个包都完整下载到项目的node_modules里10 个项目就有 10 份重复的依赖pnpm 则是把所有包的实体放在磁盘上一个全局的“内容寻址存储”里每个项目通过硬链接引用安装速度快占用的磁盘空间可能只有 npm 的三分之一。实测同一个 Vue 项目npm 安装耗时两分钟左右pnpm 大概二三十秒。不过 pnpm 对某些冷门依赖的兼容性偶尔会出问题如果你不想到处搜“pnpm 安装 xxx 失败”的解决方案那就老老实实用 npm。反正本文将基于 npm 讲解它是最不容易出幺蛾子的选择。1.3 Vue 版本默认 Vue 3但你要能识别老项目现在新建项目直接用 Vue 3。Vue 2 已经停止维护了别再用vue create那个命令去折腾旧脚手架了。这两个脚手架的区别很关键vue-clivue create是 Vue 2 时代基于 Webpack 的产物现在官方推荐用create-vuenpm create vuelatest它基于 Vite启动速度快、配置简洁体验完全不是一个级别。如果你接手的是一个用vue create创建的旧项目也没关系环境基础是一样的还是 Node npm只是构建工具不同。后面如果打算升级那又是一套独立流程今天先不展开。搞清楚这些之后我们正式开始安装。2. Node.js 安装与 npm 国内镜像配置一次装对不返工这一节是整个搭建流程的地基。地基打歪了后面每一步都会歪。我按系统分场景给你拆开讲。2.1 Windows 与 macOS 下的 Node 安装细节Windows 用户去 Node.js 官网下载.msi安装包双击运行一路 Next。但有两个细节需要注意安装路径尽量不要选C:\Program Files\这种带空格的目录后续某些工具解析路径时容易出幺蛾子建议改成D:\Node.js或者C:\nodejs这种短路径安装向导里默认勾选了“Add to PATH”一定要保证它是勾选状态否则装完在终端里敲node -v会提示“不是内部或外部命令”。macOS 用户如果只是简单安装直接下载.pkg包双击安装即可。但更推荐用 Homebrew 装nvm因为.pkg安装的 Node 不带版本切换能力卸载起来也麻烦。用 Homebrew 安装 nvm 的命令是brew install nvm装完后按照终端提示把三行环境变量加到~/.zshrc里重启终端后就能用nvm install 20安装指定版本了。装完记得在终端验证一下node -v npm -v能输出版本号说明基础环境已经通了。如果node -v有输出但npm -v报错多半是 PATH 配置不全检查一下环境变量里有没有 Node 安装目录。2.2 npm 国内镜像配置解决安装慢和超时问题不配镜像的话npm 默认从官方源下载包在国内网络环境下经常出现网络超时、下载到一半断掉的情况体验非常糟糕。最直接的办法是把 registry 指向国内镜像源。npm config set registry https://registry.npmmirror.com npm config get registry第二条命令能帮你确认是否设置成功输出结果应该是https://registry.npmmirror.com/。这个淘宝 npm 镜像源跟官方源同步频率很高日常开发完全够用。如果你用的是 pnpm对应命令是pnpm config set registry https://registry.npmmirror.com。如果你想在某个项目下单独指定源比如公司私有仓库那就不要用上面的全局命令而是在项目根目录建一个.npmrc文件写上registryhttps://registry.npmmirror.com这样只对当前项目生效不污染全局配置。2.3 多版本切换用 nvm 解决“这个项目要 Node 16那个项目要 Node 20”的问题老项目和新项目通常对 Node 版本要求不一样。我见过最典型的情况公司的旧系统是 Vue 2 Webpack 4Node 版本高了构建直接报opensslErrorStack需要 Node 16而新项目用 Vue 3 Vite 5Node 版本低了又跑不起来。这时候没有版本管理工具你就只能频繁卸载重装太浪费时间了。nvm 的常用命令并不多nvm install 16.20.2 nvm install 20.11.0 nvm use 20.11.0 nvm list安装好之后你可以随时切换nvm use对应的版本。需要注意的一点如果你已经装了 Node再装 nvm可能会冲突。建议先把之前装的 Node 卸载干净再装 nvm然后用nvm install重新装需要用的版本。3. create-vue 跑通第一个项目交互式配置逐项拆解环境装好了接下来就是真正创建 Vue 项目。这是搭环境最直观的验证环节也是新手最容易一脸懵的地方。3.1 为什么用 create-vue 而不是 vue createnpm create vuelatest是 Vue 官方当前推荐的创建方式底层是 Vite。Vite 冷启动速度极快开发服务器几乎秒开改代码热更新也很快还直接在脚手架里内置了 TypeScript、Vue Router、Pinia、ESLint 等选项可以选择性地集成。老牌的vue create属于 Vue CLI是一个 Webpack 封装。虽然还能用但对新项目来说Vue 官方在常规更新中已经明确不再推荐使用它创建新项目。别被旧的博客文章带偏新建项目直接认准create-vue。3.2 交互式命令行选项每个都说明白执行下面这条命令npm create vuelatest终端会先让你填项目名如果你已经建好了目录可以直接用.表示当前目录。然后会问你一系列功能选项。我逐个说下含义和我的推荐选项含义推荐TypeScript是否启用 TS 语法新手选 No进阶选 YesJSX是否支持在 Vue 中使用 JSX不常用选 NoVue Router是否安装路由需要多页面就选 YesPinia状态管理库建议 Yes后面基本都会用到Vitest单元测试框架暂时不需要就 NoEnd-to-End Testing端到端测试选 No需要时再补ESLint代码规范检查强烈建议 YesPrettier代码格式化工具配合 ESLint 一起 Yes如果你不确定可以直接全部选 No 先跑通一个最小项目然后再手动加依赖。不要怕选错这些选项都只是往项目里加依赖和配置文件不会对项目造成不可逆的破坏。3.3 生成目录结构认识了再写代码项目创建完结构大概是这样的my-vue-app/ ├── public/ ├── src/ │ ├── assets/ │ ├── components/ │ ├── App.vue │ └── main.js ├── .vscode/ ├── index.html ├── package.json └── vite.config.jssrc/main.js是应用的入口文件它负责创建 Vue 应用实例并挂载到index.html里的某个元素上App.vue是根组件单文件组件SFC包含了模板、脚本和样式三个部分index.html是整个应用的 HTML 入口Vite 会在这里挂载入口脚本。第一次看到这些文件别慌你现在不需要全部理解只需要知道“项目运行后页面上的内容来自src/App.vue”这一条就够了。后面写代码时你会逐渐熟悉。3.4 安装依赖并启动项目验证热更新接下来在项目根目录执行npm install npm run dev第一条安装项目依赖好一点的网络环境下一两分钟就能完成。第二条启动开发服务器默认地址是http://localhost:5173终端会直接显示出来用浏览器打开就能看到默认页面。想验证热更新是否正常可以打开src/App.vue随便改一行模板文字保存后浏览器页面应该立即更新不用手动刷新。看到这个效果说明你的 Vue 环境基本没问题了。到这里你已经成功跑起来一个真正的 Vue 3 项目。4. 编辑器、代码规范与调试工具写起来舒服才是硬道理项目能跑只是第一步后面的日常开发体验很大程度上取决于编辑器的配置。这块不做好你会发现自己写代码又慢又容易出错。4.1 VSCode 插件Volar 和 Vue DevTools 一个都不能少VSCode 是目前 Vue 开发的主流选择。安装插件时有一个常见误区很多人还会去装老牌的 Vetur但 Vetur 对 Vue 3 的支持早就跟不上而且会和 Volar 冲突。现在正确做法是只装Vue Language Features (Volar)这一个插件Vue 3 和 Vue 2 都认语法高亮、类型推导、模板补全都靠它。安装后留意一件事如果你之前装过 Vetur建议先在扩展列表里禁用它或卸载掉否则 Volar 会提示“检测到 Vetur可能导致冲突”。另外Volar 现在已经吸收了TypeScript Vue Plugin的功能不需要再单独安装那个插件了。浏览器端还需要装一个 Vue DevTools。在 Chrome 或 Edge 应用商店搜索 “Vue Devtools”认准 Vue.js 官方那几个字。装完之后打开你正在跑的 Vue 项目按 F12应该能看到一个新的 “Vue” 面板。这里能看到组件树、组件 props、Pinia 里的数据、路由状态调试时非常方便。4.2 ESLint 和 Prettier 联动让团队代码风格统一创建项目时如果你勾选了 ESLint 和 Prettier那项目里已经自带了基础配置保存文件时 VSCode 会自动格式化。如果没生效需要在.vscode/settings.json里确认一下配置{ editor.formatOnSave: true, editor.defaultFormatter: esbenp.prettier-vscode, editor.codeActionsOnSave: { source.fixAll.eslint: explicit } }这样设置之后每次保存文件先由 ESLint 修掉代码中的问题再由 Prettier 做格式化。几个常见的 Prettier 规则我一般这样配兄弟们可以参考{ semi: false, singleQuote: true, printWidth: 100 }意思是不加分号、字符串用单引号、单行最多 100 个字符。这组配置是目前 Vue 社区里比较主流的风格。团队协作时这些统一写在项目根目录的.prettierrc文件里谁拉下来代码都一样就不会出现你改我格式化、我改你格式化的尴尬局面。4.3 调试 Vue 项目直接用 Chrome DevTools 就够了开发 Vue 项目时我最常用的调试方式是在浏览器里按 F12切到 “Sources” 面板。因为 Vite 开发模式下的代码是原样的 ES Module没有压缩混淆所以你能在 Sources 里直接搜索到src目录下的.vue文件源码打断点、查看变量值完全没问题。要在 VSCode 里断点调试也可以配置.vscode/launch.json用 Chrome 调试方式启动。但说实话大多数场景下浏览器 DevTools 加 Vue DevTools 的组合已经足够高效了VSCode 的调试配置更多是锦上添花不必强求。5. 新项目最容易翻车的五个坑以及完整的排查路线环境搭建过程中报错是不可避免的。我把我实际遇到过的、问的最多的五个坑完整梳理出来每个都给你一套排查路线。5.1 端口被占用EADDRINUSE 报错怎么办Vite 默认跑在 5173 端口如果你的机器上已经有别的服务占用终端会报EADDRINUSE或Port 5173 is already in use。Vite 的默认策略是遇到占用自动换端口比如跳到 5174所以通常不影响使用。但如果某些场景下你希望固定端口而且端口被占就立刻报错可以在vite.config.js里配置export default defineConfig({ server: { port: 5173, strictPort: true, }, })strictPort: true表示一旦 5173 被占用就不尝试换端口直接报错。这时候你要么关掉占用端口的程序要么改个端口。排查是谁占用的Windows 上执行netstat -ano | findstr 5173能看到进程号之后去任务管理器结束对应进程macOS/Linux 上执行lsof -i :5173。5.2 依赖安装失败node_modules 相关的玄学问题npm install中途失败、报ETARGET、ERESOLVE这类错误是最常见也最烦人的。最常见的几个原因依赖源不稳定、lock 文件与 package.json 不一致、缓存损坏。我的固定排查顺序是先删掉node_modules和package-lock.json然后执行npm cache clean --force再重新npm install。如果还是失败就检查报错信息里有没有具体的依赖包名用npm view 包名看看它是否存在、版本号是否正确。只要不是网络彻底断掉这套流程能解决八成问题。这里要特别提醒报错信息里如果出现了node-sass这个词那就不是上面这些手段能解决的了。node-sass 是出了名地跟 Node 版本强绑定不同 Node 版本要下载不同的二进制文件经常编译失败。新项目直接改用sassDart Sass依赖项里写sass: ^1.69.0即可跟 node-sass 的用法基本一样但安装省心太多了。5.3 两个版本混淆坑import 语句和单文件组件语法网上很多 Vue 2 时代的教程main.js里写的是import Vue from vue这个写法在 Vue 3 里是跑不起来的。Vue 3 的正确入口是import { createApp } from vue import App from ./App.vue createApp(App).mount(#app)如果你照着 Vue 2 的教程配项目终端会报Module not found: Cant resolve vue或者default is not exported from vue。看到这类报错先检查一下是不是把 Vue 2 的代码拿过来了。还有生命周期这一块Vue 2 里写beforeDestroy、destroyedVue 3 里统一改成了beforeUnmount、unmounted。这些差异靠报错看不出来但会直接影响业务逻辑的正确性。新建项目时建议直接看官方文档或找 Vue 3 相关的文章别混着看。5.4 编辑器“满屏红条”Volar 类型检查与 ESLint 联动一个刚创建好的干净项目有时候打开.vue文件会发现满屏红色波浪线但项目本身跑得好好的。这种情况八成是 Volar 和 ESLint 的配合出现了问题。Volar 默认会做模板类型检查而 ESLint 负责代码规范检查两者可能针对同一行给出不同样的标记。排查路线是先看报错提示内容如果是 “Cannot find module” 或类型不存在的错误多半是依赖没装好重新npm install如果是格式类错误按Shift Alt F手动格式化一下就好了。如果红色波浪线实际上不影响编译和运行那就不用太担心强迫症患者可以打开设置搜索vue.server.takeoverMode或者按社区方案调整 Volar 的全局检查开关。5.5 Windows PowerShell 下终端乱码或命令不识别Windows 上有个很隐蔽的坑PowerShell 默认编码是 GBK而 npm 的输出和部分中文报错是 UTF-8导致终端显示乱码。有时候连npm run dev输出的服务地址都是乱码非常影响判断。解决办法是在 PowerShell 里执行chcp 65001切换到 UTF-8 代码页。但我更建议你换成 Windows Terminal 作为默认终端它对 UTF-8 的支持更稳还可以多标签页配合 Git Bash 使用体验很好。如果你在 PowerShell 里执行某些命令提示“禁止运行脚本”那是因为默认执行策略限制可以右键“以管理员身份运行 PowerShell”执行Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser这条命令允许运行本地脚本但不允许运行未签名的远程脚本安全性有保障。6. 顺手配置这几个东西后续开发会快很多环境跑通、项目能跑但这套开发环境还谈不上“一步到位”。下面这几个配置属于“现在花五分钟后面每天省五十分钟”的积累。6.1 路径别名 指向 src 目录日常开发中组件之间互相引用是家常便饭。如果都用相对路径组件层级一深就会出现../../../../components/xxx.vue这种让人头晕的写法。更科学的做法是配置别名让指向src目录。Vite 项目里默认帮你在vite.config.js中预留了这段代码import { fileURLToPath, URL } from node:url export default defineConfig({ resolve: { alias: { : fileURLToPath(new URL(./src, import.meta.url)), }, }, })如果发现你的vite.config.js里没有手动加进去即可。这样你在任何组件里都可以写import MyComponent from /components/MyComponent.vue不用再数着../找层级了。顺便说一句如果你在用 TypeScript还需要在tsconfig.json的compilerOptions.paths里加一行/*: [./src/*]否则编辑器会提示找不到模块。6.2 开发环境的接口代理配置前后端分离开发时Vue 项目跑在 5173 端口后端接口跑在 8080 或别的端口跨域问题立刻就会出现。解决思路不是在后端配 CORS虽然那也是方案而是在 Vite 的 dev server 上配置一个代理把前端请求转发到后端。典型的vite.config.js配置export default defineConfig({ server: { proxy: { /api: { target: http://localhost:8080, changeOrigin: true, rewrite: (path) path.replace(/^\/api/, ), }, }, }, })这样你在前端请求/api/user时实际会被转发到http://localhost:8080/user。前端的请求路径始终以/api开头就不会有跨域问题了。生产部署时同理在 Nginx 里配置反向代理这一块以后可以单独展开聊。6.3 让项目配置随仓库走.npmrc 和 .editorconfig团队协作时最头疼的永远是“我这边跑得好好的你那边就报错”。很多问题的根源在于本地环境不一致。比较实用的一个做法是在项目根目录维护一个.npmrc文件把镜像源、缓存策略这类配置固定下来registryhttps://registry.npmmirror.com这样任何一个人拉取代码后执行npm install用的都是同一条源避免有人用官方源、有人用镜像源造成 lock 文件出现莫名其妙的差异。另外可以加一个.editorconfig文件统一缩进风格和换行符root true [*] charset utf-8 indent_style space indent_size 2 end_of_line lf insert_final_newline true trim_trailing_whitespace true这两个文件加进去之后配合 ESLint、Prettier整个项目从编码风格到依赖源都有一致的规范团队里就不会再有人因为“我这默认 Tab你那默认空格”这种问题浪费时间了。6.4 建立自己的项目模板一次环境搭好最好的沉淀方式就是把它变成你自己的模板。create-vue 支持通过参数直接进入非交互式创建比如npm create vuelatest my-project -- --typescript --router --pinia --eslint --prettier这样一条命令就能生成带 TS、路由、状态管理和代码规范的项目基础结构不需要再手动一顿回车。如果你已经有一个自己觉得顺手的公司内部模板也可以推到 git 仓库里下次直接git clone下来改一下项目名就用效率最高。根据我的个人经验把这套流程在本地完整走三遍把依赖安装、项目启动、编辑器配置、接口代理这些都做顺手你对 Vue 开发环境的理解就不再是“照着点下一步”了。后面无论换新电脑、还是帮同事排查环境问题你都能快速定位不会再因为环境问题浪费半天时间。如果你照着这篇文章走中间还有哪个环节报错大概率是版本号或者系统环境细节上的偏差把完整报错信息贴到社区提问时也记得带上node -v和npm -v的输出别人帮你排查起来会快很多。
Vue 3开发环境搭建全攻略：从Node.js到Vite一步到位
很多刚开始接触 Vue 的朋友甚至一些写了两年 Vue 的开发者都容易在“开发环境搭建”这一步被折腾得够呛。我见过有人照着两三年前的教程装完环境结果项目跑起来全是红色报错也有人装好了 Node结果npm install卡了半小时没反应最后发现是源没配。我自己在几台新电脑上反复搭过 Vue 环境从 Windows 到 macOS 都踩过一轮今天这篇就把这套“最完整、无坑、一步到位”的 Vue 开发环境搭建流程整理出来从选型到落地每一步都告诉你为什么这么做以及踩坑之后怎么救。不管你用的是 Windows、macOS 还是 Linux照着这套流程走基本能一次跑通。1. 动手装 Node.js 之前先把这三个选型问题定下来很多人一上来就打开浏览器搜“Node.js 下载”装完发现版本不对项目又删了重来。其实真正合理的顺序是先把三个选型问题想清楚再动手。1.1 Node.js 版本别追新认准 LTSNode.js 的版本号分两种Current 和 LTS。Current 是当前开发版功能新但稳定性差很多第三方依赖还没跟上LTS 是长期维护版官方会持续打补丁生态兼容性最好。Vue 3 的官方脚手架和 Vite 都要求 Node 18 或更高版本所以 20 LTS 是目前最稳的选择22 LTS 也已经进入了维护期问题也不大。这里有个教训有次我在新笔记本上直接装了当时最新的 Node 23结果跑npm create vuelatest时一切正常但安装某个依赖时开始报ERR_INVALID_ARG_TYPE查了半天是那个依赖用了旧的原生模块跟新版本 V8 引擎不兼容。换成 Node 20 LTS 后一次通过。所以我的建议很明确不要去官网首页点那个大大的“当前版本”下载按钮点下方 LTS 那个按钮。如果你需要同时维护多个项目有些老项目要 Node 16新项目要 Node 20那就需要用版本管理工具。Windows 上推荐nvm-windowsmacOS/Linux 上推荐nvm后面我会专门说怎么配。1.2 包管理器npm 还是 pnpm先别纠结但你得知道差别官方脚手架默认用的是 npm所以新手直接用 npm 完全没问题。但如果你打算长期做 Vue 开发我建议尽早了解 pnpm。区别在哪npm 安装依赖时会把每个包都完整下载到项目的node_modules里10 个项目就有 10 份重复的依赖pnpm 则是把所有包的实体放在磁盘上一个全局的“内容寻址存储”里每个项目通过硬链接引用安装速度快占用的磁盘空间可能只有 npm 的三分之一。实测同一个 Vue 项目npm 安装耗时两分钟左右pnpm 大概二三十秒。不过 pnpm 对某些冷门依赖的兼容性偶尔会出问题如果你不想到处搜“pnpm 安装 xxx 失败”的解决方案那就老老实实用 npm。反正本文将基于 npm 讲解它是最不容易出幺蛾子的选择。1.3 Vue 版本默认 Vue 3但你要能识别老项目现在新建项目直接用 Vue 3。Vue 2 已经停止维护了别再用vue create那个命令去折腾旧脚手架了。这两个脚手架的区别很关键vue-clivue create是 Vue 2 时代基于 Webpack 的产物现在官方推荐用create-vuenpm create vuelatest它基于 Vite启动速度快、配置简洁体验完全不是一个级别。如果你接手的是一个用vue create创建的旧项目也没关系环境基础是一样的还是 Node npm只是构建工具不同。后面如果打算升级那又是一套独立流程今天先不展开。搞清楚这些之后我们正式开始安装。2. Node.js 安装与 npm 国内镜像配置一次装对不返工这一节是整个搭建流程的地基。地基打歪了后面每一步都会歪。我按系统分场景给你拆开讲。2.1 Windows 与 macOS 下的 Node 安装细节Windows 用户去 Node.js 官网下载.msi安装包双击运行一路 Next。但有两个细节需要注意安装路径尽量不要选C:\Program Files\这种带空格的目录后续某些工具解析路径时容易出幺蛾子建议改成D:\Node.js或者C:\nodejs这种短路径安装向导里默认勾选了“Add to PATH”一定要保证它是勾选状态否则装完在终端里敲node -v会提示“不是内部或外部命令”。macOS 用户如果只是简单安装直接下载.pkg包双击安装即可。但更推荐用 Homebrew 装nvm因为.pkg安装的 Node 不带版本切换能力卸载起来也麻烦。用 Homebrew 安装 nvm 的命令是brew install nvm装完后按照终端提示把三行环境变量加到~/.zshrc里重启终端后就能用nvm install 20安装指定版本了。装完记得在终端验证一下node -v npm -v能输出版本号说明基础环境已经通了。如果node -v有输出但npm -v报错多半是 PATH 配置不全检查一下环境变量里有没有 Node 安装目录。2.2 npm 国内镜像配置解决安装慢和超时问题不配镜像的话npm 默认从官方源下载包在国内网络环境下经常出现网络超时、下载到一半断掉的情况体验非常糟糕。最直接的办法是把 registry 指向国内镜像源。npm config set registry https://registry.npmmirror.com npm config get registry第二条命令能帮你确认是否设置成功输出结果应该是https://registry.npmmirror.com/。这个淘宝 npm 镜像源跟官方源同步频率很高日常开发完全够用。如果你用的是 pnpm对应命令是pnpm config set registry https://registry.npmmirror.com。如果你想在某个项目下单独指定源比如公司私有仓库那就不要用上面的全局命令而是在项目根目录建一个.npmrc文件写上registryhttps://registry.npmmirror.com这样只对当前项目生效不污染全局配置。2.3 多版本切换用 nvm 解决“这个项目要 Node 16那个项目要 Node 20”的问题老项目和新项目通常对 Node 版本要求不一样。我见过最典型的情况公司的旧系统是 Vue 2 Webpack 4Node 版本高了构建直接报opensslErrorStack需要 Node 16而新项目用 Vue 3 Vite 5Node 版本低了又跑不起来。这时候没有版本管理工具你就只能频繁卸载重装太浪费时间了。nvm 的常用命令并不多nvm install 16.20.2 nvm install 20.11.0 nvm use 20.11.0 nvm list安装好之后你可以随时切换nvm use对应的版本。需要注意的一点如果你已经装了 Node再装 nvm可能会冲突。建议先把之前装的 Node 卸载干净再装 nvm然后用nvm install重新装需要用的版本。3. create-vue 跑通第一个项目交互式配置逐项拆解环境装好了接下来就是真正创建 Vue 项目。这是搭环境最直观的验证环节也是新手最容易一脸懵的地方。3.1 为什么用 create-vue 而不是 vue createnpm create vuelatest是 Vue 官方当前推荐的创建方式底层是 Vite。Vite 冷启动速度极快开发服务器几乎秒开改代码热更新也很快还直接在脚手架里内置了 TypeScript、Vue Router、Pinia、ESLint 等选项可以选择性地集成。老牌的vue create属于 Vue CLI是一个 Webpack 封装。虽然还能用但对新项目来说Vue 官方在常规更新中已经明确不再推荐使用它创建新项目。别被旧的博客文章带偏新建项目直接认准create-vue。3.2 交互式命令行选项每个都说明白执行下面这条命令npm create vuelatest终端会先让你填项目名如果你已经建好了目录可以直接用.表示当前目录。然后会问你一系列功能选项。我逐个说下含义和我的推荐选项含义推荐TypeScript是否启用 TS 语法新手选 No进阶选 YesJSX是否支持在 Vue 中使用 JSX不常用选 NoVue Router是否安装路由需要多页面就选 YesPinia状态管理库建议 Yes后面基本都会用到Vitest单元测试框架暂时不需要就 NoEnd-to-End Testing端到端测试选 No需要时再补ESLint代码规范检查强烈建议 YesPrettier代码格式化工具配合 ESLint 一起 Yes如果你不确定可以直接全部选 No 先跑通一个最小项目然后再手动加依赖。不要怕选错这些选项都只是往项目里加依赖和配置文件不会对项目造成不可逆的破坏。3.3 生成目录结构认识了再写代码项目创建完结构大概是这样的my-vue-app/ ├── public/ ├── src/ │ ├── assets/ │ ├── components/ │ ├── App.vue │ └── main.js ├── .vscode/ ├── index.html ├── package.json └── vite.config.jssrc/main.js是应用的入口文件它负责创建 Vue 应用实例并挂载到index.html里的某个元素上App.vue是根组件单文件组件SFC包含了模板、脚本和样式三个部分index.html是整个应用的 HTML 入口Vite 会在这里挂载入口脚本。第一次看到这些文件别慌你现在不需要全部理解只需要知道“项目运行后页面上的内容来自src/App.vue”这一条就够了。后面写代码时你会逐渐熟悉。3.4 安装依赖并启动项目验证热更新接下来在项目根目录执行npm install npm run dev第一条安装项目依赖好一点的网络环境下一两分钟就能完成。第二条启动开发服务器默认地址是http://localhost:5173终端会直接显示出来用浏览器打开就能看到默认页面。想验证热更新是否正常可以打开src/App.vue随便改一行模板文字保存后浏览器页面应该立即更新不用手动刷新。看到这个效果说明你的 Vue 环境基本没问题了。到这里你已经成功跑起来一个真正的 Vue 3 项目。4. 编辑器、代码规范与调试工具写起来舒服才是硬道理项目能跑只是第一步后面的日常开发体验很大程度上取决于编辑器的配置。这块不做好你会发现自己写代码又慢又容易出错。4.1 VSCode 插件Volar 和 Vue DevTools 一个都不能少VSCode 是目前 Vue 开发的主流选择。安装插件时有一个常见误区很多人还会去装老牌的 Vetur但 Vetur 对 Vue 3 的支持早就跟不上而且会和 Volar 冲突。现在正确做法是只装Vue Language Features (Volar)这一个插件Vue 3 和 Vue 2 都认语法高亮、类型推导、模板补全都靠它。安装后留意一件事如果你之前装过 Vetur建议先在扩展列表里禁用它或卸载掉否则 Volar 会提示“检测到 Vetur可能导致冲突”。另外Volar 现在已经吸收了TypeScript Vue Plugin的功能不需要再单独安装那个插件了。浏览器端还需要装一个 Vue DevTools。在 Chrome 或 Edge 应用商店搜索 “Vue Devtools”认准 Vue.js 官方那几个字。装完之后打开你正在跑的 Vue 项目按 F12应该能看到一个新的 “Vue” 面板。这里能看到组件树、组件 props、Pinia 里的数据、路由状态调试时非常方便。4.2 ESLint 和 Prettier 联动让团队代码风格统一创建项目时如果你勾选了 ESLint 和 Prettier那项目里已经自带了基础配置保存文件时 VSCode 会自动格式化。如果没生效需要在.vscode/settings.json里确认一下配置{ editor.formatOnSave: true, editor.defaultFormatter: esbenp.prettier-vscode, editor.codeActionsOnSave: { source.fixAll.eslint: explicit } }这样设置之后每次保存文件先由 ESLint 修掉代码中的问题再由 Prettier 做格式化。几个常见的 Prettier 规则我一般这样配兄弟们可以参考{ semi: false, singleQuote: true, printWidth: 100 }意思是不加分号、字符串用单引号、单行最多 100 个字符。这组配置是目前 Vue 社区里比较主流的风格。团队协作时这些统一写在项目根目录的.prettierrc文件里谁拉下来代码都一样就不会出现你改我格式化、我改你格式化的尴尬局面。4.3 调试 Vue 项目直接用 Chrome DevTools 就够了开发 Vue 项目时我最常用的调试方式是在浏览器里按 F12切到 “Sources” 面板。因为 Vite 开发模式下的代码是原样的 ES Module没有压缩混淆所以你能在 Sources 里直接搜索到src目录下的.vue文件源码打断点、查看变量值完全没问题。要在 VSCode 里断点调试也可以配置.vscode/launch.json用 Chrome 调试方式启动。但说实话大多数场景下浏览器 DevTools 加 Vue DevTools 的组合已经足够高效了VSCode 的调试配置更多是锦上添花不必强求。5. 新项目最容易翻车的五个坑以及完整的排查路线环境搭建过程中报错是不可避免的。我把我实际遇到过的、问的最多的五个坑完整梳理出来每个都给你一套排查路线。5.1 端口被占用EADDRINUSE 报错怎么办Vite 默认跑在 5173 端口如果你的机器上已经有别的服务占用终端会报EADDRINUSE或Port 5173 is already in use。Vite 的默认策略是遇到占用自动换端口比如跳到 5174所以通常不影响使用。但如果某些场景下你希望固定端口而且端口被占就立刻报错可以在vite.config.js里配置export default defineConfig({ server: { port: 5173, strictPort: true, }, })strictPort: true表示一旦 5173 被占用就不尝试换端口直接报错。这时候你要么关掉占用端口的程序要么改个端口。排查是谁占用的Windows 上执行netstat -ano | findstr 5173能看到进程号之后去任务管理器结束对应进程macOS/Linux 上执行lsof -i :5173。5.2 依赖安装失败node_modules 相关的玄学问题npm install中途失败、报ETARGET、ERESOLVE这类错误是最常见也最烦人的。最常见的几个原因依赖源不稳定、lock 文件与 package.json 不一致、缓存损坏。我的固定排查顺序是先删掉node_modules和package-lock.json然后执行npm cache clean --force再重新npm install。如果还是失败就检查报错信息里有没有具体的依赖包名用npm view 包名看看它是否存在、版本号是否正确。只要不是网络彻底断掉这套流程能解决八成问题。这里要特别提醒报错信息里如果出现了node-sass这个词那就不是上面这些手段能解决的了。node-sass 是出了名地跟 Node 版本强绑定不同 Node 版本要下载不同的二进制文件经常编译失败。新项目直接改用sassDart Sass依赖项里写sass: ^1.69.0即可跟 node-sass 的用法基本一样但安装省心太多了。5.3 两个版本混淆坑import 语句和单文件组件语法网上很多 Vue 2 时代的教程main.js里写的是import Vue from vue这个写法在 Vue 3 里是跑不起来的。Vue 3 的正确入口是import { createApp } from vue import App from ./App.vue createApp(App).mount(#app)如果你照着 Vue 2 的教程配项目终端会报Module not found: Cant resolve vue或者default is not exported from vue。看到这类报错先检查一下是不是把 Vue 2 的代码拿过来了。还有生命周期这一块Vue 2 里写beforeDestroy、destroyedVue 3 里统一改成了beforeUnmount、unmounted。这些差异靠报错看不出来但会直接影响业务逻辑的正确性。新建项目时建议直接看官方文档或找 Vue 3 相关的文章别混着看。5.4 编辑器“满屏红条”Volar 类型检查与 ESLint 联动一个刚创建好的干净项目有时候打开.vue文件会发现满屏红色波浪线但项目本身跑得好好的。这种情况八成是 Volar 和 ESLint 的配合出现了问题。Volar 默认会做模板类型检查而 ESLint 负责代码规范检查两者可能针对同一行给出不同样的标记。排查路线是先看报错提示内容如果是 “Cannot find module” 或类型不存在的错误多半是依赖没装好重新npm install如果是格式类错误按Shift Alt F手动格式化一下就好了。如果红色波浪线实际上不影响编译和运行那就不用太担心强迫症患者可以打开设置搜索vue.server.takeoverMode或者按社区方案调整 Volar 的全局检查开关。5.5 Windows PowerShell 下终端乱码或命令不识别Windows 上有个很隐蔽的坑PowerShell 默认编码是 GBK而 npm 的输出和部分中文报错是 UTF-8导致终端显示乱码。有时候连npm run dev输出的服务地址都是乱码非常影响判断。解决办法是在 PowerShell 里执行chcp 65001切换到 UTF-8 代码页。但我更建议你换成 Windows Terminal 作为默认终端它对 UTF-8 的支持更稳还可以多标签页配合 Git Bash 使用体验很好。如果你在 PowerShell 里执行某些命令提示“禁止运行脚本”那是因为默认执行策略限制可以右键“以管理员身份运行 PowerShell”执行Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser这条命令允许运行本地脚本但不允许运行未签名的远程脚本安全性有保障。6. 顺手配置这几个东西后续开发会快很多环境跑通、项目能跑但这套开发环境还谈不上“一步到位”。下面这几个配置属于“现在花五分钟后面每天省五十分钟”的积累。6.1 路径别名 指向 src 目录日常开发中组件之间互相引用是家常便饭。如果都用相对路径组件层级一深就会出现../../../../components/xxx.vue这种让人头晕的写法。更科学的做法是配置别名让指向src目录。Vite 项目里默认帮你在vite.config.js中预留了这段代码import { fileURLToPath, URL } from node:url export default defineConfig({ resolve: { alias: { : fileURLToPath(new URL(./src, import.meta.url)), }, }, })如果发现你的vite.config.js里没有手动加进去即可。这样你在任何组件里都可以写import MyComponent from /components/MyComponent.vue不用再数着../找层级了。顺便说一句如果你在用 TypeScript还需要在tsconfig.json的compilerOptions.paths里加一行/*: [./src/*]否则编辑器会提示找不到模块。6.2 开发环境的接口代理配置前后端分离开发时Vue 项目跑在 5173 端口后端接口跑在 8080 或别的端口跨域问题立刻就会出现。解决思路不是在后端配 CORS虽然那也是方案而是在 Vite 的 dev server 上配置一个代理把前端请求转发到后端。典型的vite.config.js配置export default defineConfig({ server: { proxy: { /api: { target: http://localhost:8080, changeOrigin: true, rewrite: (path) path.replace(/^\/api/, ), }, }, }, })这样你在前端请求/api/user时实际会被转发到http://localhost:8080/user。前端的请求路径始终以/api开头就不会有跨域问题了。生产部署时同理在 Nginx 里配置反向代理这一块以后可以单独展开聊。6.3 让项目配置随仓库走.npmrc 和 .editorconfig团队协作时最头疼的永远是“我这边跑得好好的你那边就报错”。很多问题的根源在于本地环境不一致。比较实用的一个做法是在项目根目录维护一个.npmrc文件把镜像源、缓存策略这类配置固定下来registryhttps://registry.npmmirror.com这样任何一个人拉取代码后执行npm install用的都是同一条源避免有人用官方源、有人用镜像源造成 lock 文件出现莫名其妙的差异。另外可以加一个.editorconfig文件统一缩进风格和换行符root true [*] charset utf-8 indent_style space indent_size 2 end_of_line lf insert_final_newline true trim_trailing_whitespace true这两个文件加进去之后配合 ESLint、Prettier整个项目从编码风格到依赖源都有一致的规范团队里就不会再有人因为“我这默认 Tab你那默认空格”这种问题浪费时间了。6.4 建立自己的项目模板一次环境搭好最好的沉淀方式就是把它变成你自己的模板。create-vue 支持通过参数直接进入非交互式创建比如npm create vuelatest my-project -- --typescript --router --pinia --eslint --prettier这样一条命令就能生成带 TS、路由、状态管理和代码规范的项目基础结构不需要再手动一顿回车。如果你已经有一个自己觉得顺手的公司内部模板也可以推到 git 仓库里下次直接git clone下来改一下项目名就用效率最高。根据我的个人经验把这套流程在本地完整走三遍把依赖安装、项目启动、编辑器配置、接口代理这些都做顺手你对 Vue 开发环境的理解就不再是“照着点下一步”了。后面无论换新电脑、还是帮同事排查环境问题你都能快速定位不会再因为环境问题浪费半天时间。如果你照着这篇文章走中间还有哪个环节报错大概率是版本号或者系统环境细节上的偏差把完整报错信息贴到社区提问时也记得带上node -v和npm -v的输出别人帮你排查起来会快很多。
