VS Code中从零创建Vue3项目：环境配置、Vite搭建与避坑指南

最近有朋友问我在VS Code里怎么从零开始创建一个Vue3项目。网上的教程确实不少但很多都默认你已经有一套完整环境或者还在教Vue CLI那一套跟现在Vite的玩法完全对不上。这篇文章我不讲虚的只按我自己实际走过的流程来。从Node环境怎么选版本、VS Code要装哪些插件、怎么用Vite把项目拉起来到项目跑起来后怎么配置路径别名和代码规范最后把最常见的一批报错和坑整理成速查表。文章偏实操适合刚接触Vue3的新手也适合那些希望把开发环境一次配顺的开发者。看完你就能在自己的电脑上搭出一个干净、可扩展的Vue3项目后面想加路由、状态管理或者UI组件库都会顺畅很多。1. 环境准备装对Node、选对包管理器1.1 Node.js版本与Vue3的适配关系在初始化任何Vue3项目之前最容易被忽视的就是环境。很多人直接在官网下载了最新的Node.js结果项目启动报错或者装依赖时各种诡异问题。这里先把环境说清楚。Vue3本身要求Node.js 16.0以上但如果你打算用Vite作为构建工具建议直接上Node 18及以上因为Vite 5版本把基线提到了Node 18Vite 6更是要求Node 18或20。我自己的主力环境是Node 20 LTS用得很稳兼容性也最好。打开终端先检查一下自己的版本node -v npm -v如果版本低于18我建议先别急着卸载旧版本优先考虑用nvm来管理多个Node版本。Windows用户可以用nvm-windowsmacOS和Linux用户直接用官方nvm。安装好之后切换版本命令很简单nvm install 20 nvm use 20为什么要强调版本可以把Node理解为Vite的发动机Node版本太低Vite启动时可能直接给你一个黄色警告甚至有些原生依赖根本装不上。版本太新也不是好事部分UI组件库或旧项目依赖可能还没适配容易踩兼容性坑。所以选双数LTS版本比如20或22是大多数人验证过的最稳方案。1.2 包管理器npm、pnpm还是yarn创建Vue3项目之前还要决定用哪个包管理器。npm是Node自带的零额外安装上手最容易但它安装依赖时会把每个项目都复制一份磁盘占用大安装速度也一般。yarn的缓存机制做得好但经典yarn已经进入了维护期新版yarn berry虽然强大踩坑成本又偏高。所以我个人推荐新项目直接用pnpm。pnpm的优势在于使用硬链接和内容寻址存储同一份依赖无论在多少个项目里出现磁盘上都只保留一份省空间而且安装速度快。它对工程依赖的隔离也更严格不像npm那样容易产生“幽灵依赖”对项目健康度是好事。安装pnpm有两种方式npm install -g pnpm如果你用的是Node 16.13以上版本还可以用内置的corepackcorepack enable corepack prepare pnpmlatest --activate这里有一个经验一旦项目里选定pnpm整个团队最好统一不要混用npm和pnpm。两者的node_modules结构不同混用之后有时候会报一些莫名其妙的模块找不到问题排查起来非常头疼。1.3 VS Code必备插件VS Code本身只是一个编辑器但装对插件之后写Vue3的体验会完全不同。下面这几个插件基本是标配插件名作用备注VolarVue Language FeaturesVue3 SFC语法高亮、模板类型检查、自动补全Vue3官方推荐必装TypeScript Vue PluginVolar解决.vue文件在TS模块解析中的类型提示TS项目建议同时安装ESLint代码规范检查需要配合项目依赖Prettier - Code formatter统一代码风格保存时自动格式化Vue VSCode Snippets快速生成SFC模板代码可选但很方便有一个老坑必须提醒Vetur和Volar不能共存。Vetur是Vue2时代的老插件如果你之前写过Vue2VS Code里可能还留着它那你在打开Vue3项目时容易出现模板高亮错乱、defineProps莫名标红等问题。解决办法很简单在扩展面板搜索Vetur点击禁用然后执行Developer: Reload Window让插件重新加载。这一点处理不好Vue3项目创建后的第一印象就会很糟糕。2. 用Vite快速创建Vue3项目2.1 创建项目的标准命令现在创建Vue3项目官方推荐的方式是用Vite脚手架而不是Vue CLI。在VS Code里打开终端或者直接在系统终端进入你准备放项目的目录然后执行# 使用 npm npm create vitelatest my-vue3-demo -- --template vue # 使用 pnpm pnpm create vite my-vue3-demo --template vue-ts这里的my-vue3-demo是项目名--template参数决定生成JS还是TS版本的项目。vue模板生成的就是最常见的JavaScript版本vue-ts模版则带TypeScript支持。如果你打算做后台管理系统、商城这种需要长期维护的项目我强烈建议直接选vue-ts虽然初期有点门槛但类型系统能帮你挡住很多隐藏bug。如果只是想快速验证一个页面效果选vue模板就够了。执行过程中脚手架可能会问你“是否安装依赖并启动项目”“是否使用rolldown-vite”之类的选项不同版本提示略有差异按默认回车就行。创建完成后目录里会出现一个清爽的项目骨架。2.2 解读Vite生成的项目结构用VS Code打开刚创建的项目很多人第一反应是“怎么文件这么少”确实Vite脚手架只给最精简的结构这是好事避免模板变成全家桶。核心文件如下my-vue3-demo/ ├─ index.html ├─ package.json ├─ vite.config.ts ├─ tsconfig.json ├─ env.d.ts └─ src/ ├─ main.ts ├─ App.vue ├─ components/ │ └─ HelloWorld.vue └─ assets/ └─ vue.svgindex.html是整个应用的HTML入口注意它不在public目录里而是放在根目录这是因为Vite会从index.html解析出需要加载的模块里面的script typemodule src/src/main.ts/script才是启动入口。src/main.ts里调用了createApp(App).mount(#app)这是Vue3应用的起点。vite.config.ts是配置中枢后面配置路径别名、开发代理都靠它。components/HelloWorld.vue是示例组件一般我会直接删掉改成自己的页面。如果你看到的入口是main.js而不是main.ts说明创建时选了vue模板这很正常。Vue3的单文件组件SFC无论TS还是JS写法核心是一样的template负责结构script setup负责逻辑style负责样式三种语言区域融合在一个.vue文件里。2.3 安装依赖并启动开发服务器项目结构看明白之后就要把它跑起来。终端输入cd my-vue3-demo pnpm install pnpm run dev第一次执行pnpm install可能稍微等一会儿看网速和镜像源。启动成功后终端会打印类似信息VITE v5.x.x ready in 400 ms ➜ Local: http://localhost:5173/按住Ctrl点击这个地址浏览器就会打开默认页面。此时修改src/App.vue里的内容页面会热更新不需要手动刷新。如果5173端口被占用了Vite会自动切换到5174终端会重新打印新的地址。如果不想用默认端口也可以在vite.config.ts里通过server.port显式指定。2.4 Vite和Webpack到底怎么选很多刚从Vue2转过来的朋友会问为什么现在新项目都用Vite而不是Webpack我用一个比喻来解释。Webpack启动项目就像中央厨房提前把所有菜全部做好一桌一桌地送一旦项目变大启动时间就成了灾难Vite更像是餐厅按客人的点单现炒哪桌需要哪道菜就上哪道所以冷启动几乎都是秒开。热更新的时候Vite利用ESM的特性只更新变动模块项目规模越大这种优势越明显。Vue CLI底层其实就是Webpack虽然它也能创建Vue3项目但官方已经明确推荐Vite作为新项目脚手架。所以如果你不是要维护老项目就不要再使用Vue CLI创建新工程了直接从Vite开始体验会好很多。当然Webpack在很多历史项目里依然大量存在具备它的知识仍然是加分项只是新项目的选择上Vite已经是更合理的默认项。3. 在VS Code里把开发环境调顺手3.1 工作区设置把规范固化到项目里项目创建好后VS Code默认的代码格式化和缩进可能不够统一。我的做法是在项目根目录创建.vscode/settings.json把这些配置提交到版本库这样团队里的每个人打开项目都是一致的编辑体验{ editor.tabSize: 2, editor.formatOnSave: true, editor.codeActionsOnSave: { source.fixAll.eslint: true }, typescript.tsdk: node_modules/typescript/lib, eslint.validate: [javascript, typescript, vue], [vue]: { editor.defaultFormatter: esbenp.prettier-vscode }, [typescript]: { editor.defaultFormatter: esbenp.prettier-vscode } }这几个配置的含义分别是tabSize统一用2个空格缩进Vue生态普遍是这个规范formatOnSave让保存时自动格式化避免手写格式混乱codeActionsOnSave在保存时自动执行ESLint的--fix一些简单的代码规范问题直接就被修掉了[vue]和[typescript]指定了对应文件的默认格式化器是Prettier这一步很关键因为如果不指定VS Code可能会同时询问你使用Volar还是Prettier来格式化容易造成格式跳来跳去。3.2 配置路径别名当项目页面越来越多组件嵌套层级变深时import HelloWorld from ../../../components/HelloWorld.vue这样的相对路径非常痛苦。配置路径别名之后就可以用/components/HelloWorld.vue来表示从src目录下开始找文件。在vite.config.ts中配置import { defineConfig } from vite import vue from vitejs/plugin-vue import { fileURLToPath, URL } from node:url export default defineConfig({ plugins: [vue()], resolve: { alias: { : fileURLToPath(new URL(./src, import.meta.url)) } } })注意这里使用了node:url需要确保项目能解析到Node相关类型所以要先安装pnpm add -D types/node如果你用TS模板还要同步配置tsconfig.json否则编辑器会提示找不到模块{ compilerOptions: { baseUrl: ., paths: { /*: [src/*] } } }这两个配置必须同时存在一个管Vite构建时的解析一个管TypeScript类型检查。我见过太多人只配了vite.config.ts编辑器里/xxx仍然飘红就是忽略了tsconfig.json。3.3 集成ESLint和PrettierVite脚手架默认不集成ESLint所以代码规范要自己装。这里我给一套比较省心的方案先把基础工具链装上pnpm add -D eslint eslint-plugin-vue vue/eslint-config-typescript typescript-eslint/parser typescript-eslint/eslint-plugin prettier eslint-plugin-prettier vue/eslint-config-prettier然后在项目根目录创建.eslintrc.cjs写一个足够用但不过分严格的配置module.exports { root: true, env: { browser: true, es2022: true, node: true, }, extends: [ plugin:vue/vue3-recommended, eslint:recommended, vue/typescript/recommended, plugin:prettier/recommended, ], parserOptions: { ecmaVersion: latest, }, rules: {}, }这里要劝一句新手不要一上来就把规则全开尤其是vue/multi-word-component-names这类强制组件名多单词的规则在一个刚开始的项目里会让你反复改名非常打击积极性。先用recommended级别的规则跑通等项目稳定后再逐步加严这样体验更平滑。4. 常见问题与排查技巧实录4.1 Vue3项目创建后的高频问题速查表下面这个表格是我在陪别人搭环境时最常遇到的几类问题几乎每个项目都能碰到至少一条现象典型原因快速解决启动提示“vite”不是内部或外部命令依赖没装完整删除node_modules后重新执行installnpm安装时长时间卡住不动默认源访问慢切换npmmirror镜像源.vue文件模板没有语法高亮Vetur和Volar冲突禁用Vetur重载窗口找不到模块/components/xxx.vuetsconfig未配置paths在tsconfig.json中补上baseUrl和paths页面白屏控制台提示找不到/src/main.tsindex.html中script入口路径错误检查入口文件的src路径保存后代码格式乱跳同时存在多个格式化器用[vue]指定Prettier为默认格式化器4.2 安装依赖卡死或失败的处理国内开发者在安装依赖时最常遇到网络问题。如果你执行npm install卡顿很久或者报network相关错误先检查一下当前源npm config get registry如果返回的是https://registry.npmjs.org/可以切换成国内镜像npm config set registry https://registry.npmmirror.com/使用pnpm的话对应命令是pnpm config set registry https://registry.npmmirror.com/换源之后删除原来的node_modules重新安装一次不要直接叠加。有时候还要清一下缓存npm cache clean --force我见过不少人换源后仍然报错最后发现是在同一个项目里混用了npm和pnpm导致依赖树结构错乱。这种问题没有捷径只能统一包管理器后重装。4.3 Volar和Vetur冲突导致的高亮错乱这个问题在Vue3项目里属于“经典中的经典”。表现是代码在逻辑上完全没问题但VS Code里到处都是红色波浪线模板里的变量没有补全甚至script setup标签都不被识别。原因几乎都是因为之前装过Vetur它还在后台接管.vue文件的解析而Vue3的SFC语法已经不是Vetur能正确处理的了。解决办法就是禁用Vetur然后重载窗口。如果你确认项目里没装Vetur但依然有问题那就检查Volar本身是不是旧版本升级到最新版本。这里还有一个很小的细节Volar的“Takeover模式”对于纯Vue项目可以启用能关掉VS Code内置的TS服务降低内存占用但如果你的项目同时也有大量纯.ts文件可以先不折腾保持默认也不会影响正常开发。4.4 TS项目里“找不到模块”和若依Vue3 TS报错Vite的vue-ts模板默认会生成一个env.d.ts文件里面通常有/// reference typesvite/client / declare module *.vue { import type { DefineComponent } from vue const component: DefineComponent{}, {}, any export default component }如果你手动整理项目时把这个文件删了或者覆盖了内容TypeScript就会不认识.vue文件于是到处报“找不到模块”。遇到这类问题第一反应检查这个声明文件在不在。另一个高频坑是路径别名问题你配置了vite.config.ts的别名但忘了同步tsconfig.json导致编辑器里依然找不到/开头的模块。像若依这类较重的后台模板经常因为依赖升级或二次定制时丢配置而报TS错误排查思路基本都是这个顺序先看tsconfig再看env.d.ts最后检查node_modules里对应类型包是否存在。4.5 奇怪的Edge浏览器按钮失效问题你可能在群里见过有人问Vue3项目在Edge浏览器里有时候页面顶部的关闭、最小化按钮没反应甚至整个页面卡死。这种问题第一反应不应该是去查框架代码而是先排除浏览器扩展干扰。尤其开发模式下有些扩展会往页面注入脚本影响事件循环导致类似“按钮失灵”的诡异现象。我遇到过的真实案例最后定位到的是一个录屏插件注入脚本导致的。遇到这种情况先打开浏览器无痕模式跑一下项目如果无痕下正常那就是扩展冲突逐个禁用排查即可。如果无痕下也复现再考虑是不是项目里某些全局事件把页面搞卡了这时候可以用最小化demo逐步定位。总之不要一上来就认定是Vue3框架的问题环境因素往往比代码本身更容易出幺蛾子。5. 从Demo到真实项目给你的项目加上路由和状态管理5.1 安装Vue Router 4项目创建后想继续做后台管理系统或者商城第一个要加的就是路由。Vue3对应的是Vue Router 4版本安装命令pnpm add vue-router4然后在src/router/index.ts里写一个最基础的路由配置import { createRouter, createWebHistory } from vue-router import HomeView from /views/HomeView.vue const router createRouter({ history: createWebHistory(), routes: [ { path: /, name: home, component: HomeView, }, ], }) export default router在src/main.ts里挂载import { createApp } from vue import App from ./App.vue import router from ./router createApp(App).use(router).mount(#app)这样就能通过router-link和router-view实现页面切换了。这里要提一个部署相关的小坑createWebHistory模式在开发环境没有任何问题但部署到Nginx时如果服务器没有配置try_files回退到index.html刷新子路由页面就会404。如果不想在部署时费这个劲可以直接改用createWebHashHistory()虽然URL会带一个#号但胜在省心。5.2 引入Pinia管理状态状态管理方面Vue3社区已经全面转向Pinia它相比Vuex少了mutations的概念API更简洁TypeScript支持也更自然。安装pnpm add pinia在main.ts中注册import { createPinia } from pinia const pinia createPinia() createApp(App).use(pinia).mount(#app)然后就可以在src/store目录下创建自己的store了。对于大多数后台管理系统来说登录状态、用户信息、菜单权限这些全局数据很适合放在Pinia里。不过刚创建项目时我不建议立刻上状态管理等确实有跨组件共享数据的需求时再加入避免过度设计。5.3 按需接入UI组件库如果是做后台管理系统UI组件库基本绕不开。Vue3生态里比较常用的有Element Plus、Ant Design Vue、Naive UI等。以Element Plus为例推荐使用按需自动导入的方式避免全量打包导致体积膨胀。安装相关插件pnpm add element-plus pnpm add -D unplugin-vue-components unplugin-auto-import然后在vite.config.ts里配置import AutoImport from unplugin-auto-import/vite import Components from unplugin-vue-components/vite import { ElementPlusResolver } from unplugin-vue-components/resolvers export default defineConfig({ plugins: [ vue(), AutoImport({ resolvers: [ElementPlusResolver()] }), Components({ resolvers: [ElementPlusResolver()] }), ], })配好之后组件不用手动import模板里直接写el-button就能用。但切记不要再在main.ts里执行app.use(ElementPlus)否则会全量引入组件和按需导入冲突打包体积直接暴增。5.4 我的建议把纯净模板沉淀成自己的基建创建Vue3项目这件事最忌一口气把路由、状态管理、UI库全部塞进初始化阶段。先把基础跑通再按需求逐个添加出了问题也容易定位。我自己的习惯是把一份配好路径别名、ESLint、Prettier、Router、Pinia的vue-ts空项目推到一个独立的Git仓库命名为vue3-template每次开新项目直接复制或克隆过去从零开始配环境的时间几乎可以压缩到几分钟。最后再分享一个小技巧。在VS Code里创建Vue3项目时调试好环境后第一时间把.vscode、.eslintrc.cjs、tsconfig.json这些配置一起提交到版本库。团队里新人进来clone完就能直接开发不用再折腾一整天。我自己就是靠这个习惯让不少同事少走了弯路。希望这篇文章能帮你在Vue3项目创建这条路上少踩几个坑项目能顺利跑起来后面的开发才谈得上效率。