有不少刚接触 Vue3 的朋友问我为什么我在 VS Code 里点了半天也没找到“新建 Vue 项目”的按钮这个问题背后其实藏着一个很常见的误区——VS Code 只是个编辑器它本身并不负责“创建项目”真正干活的是你装在电脑里的 Node.js 工具链。这篇文章就带你走一遍完整的 VS Code 环境下的 Vue3 项目创建流程从环境准备、脚手架选型、目录解读到路由、状态管理、接口请求层的一次性落地最后还会聊聊我在实际创建和运行项目时踩过的几个坑。无论你是刚入门的新手还是习惯了 Vue2 想切换到 Vue3 的老手这篇都值得收藏。1. 动手前先搞清楚VS Code 在 Vue3 项目里担任什么角色1.1 VS Code 是编辑器创建项目靠的是工具链先把底层逻辑捋清楚。VS Code 的本质是一个文本编辑器它强大在插件生态和调试体验上但“创建项目”这件事它只能通过两种方式完成一是在集成的终端里执行命令行工具二是通过插件调用命令行工具。换句话说所有创建 Vue3 项目的操作最终都会落到一条命令上比如npm create vuelatest或者pnpm create vite。理解了这一点你就会明白为什么很多人会卡在“找不到按钮”上。VS Code 里没有像 JetBrains 系 IDE 那样直观的 New Project 向导这是它轻量化的代价。但换个角度想命令行方式反而更透明你清楚地知道项目是怎么被生成出来的遇到问题也能顺着命令的逻辑去排查。所以与其花时间找插件去模拟 IDE 的创建向导不如直接把命令行用熟这才是长期收益最高的方式。1.2 环境准备Node.js 版本怎么选包管理器怎么挑创建 Vue3 项目之前第一个要确认的是 Node.js 版本。Vite 5 要求 Node.js 18 或 20Vite 6 更是把要求提到了 Node.js 18.17.0 以上如果版本太低脚手架会直接报错让你升级 Node。我在不同电脑上试过多种组合最省心的方案是安装 Node.js 20 LTS 版本因为这个版本既满足了 Vite 的最新要求也兼容 Vue2 时期遗留下来的一些旧项目。包管理器方面现在主流是 npm、pnpm、yarn 三选一我个人强烈推荐 pnpm。原因有三点安装速度明显更快因为它通过硬链接和全局内容寻址存储来复用依赖同一个包不会在每台机器上重复下载磁盘占用更小多个项目共享同一个依赖存储对依赖的版本管理更严格能避免很多“我本机能跑提交到别人机器上就报错”的灵异问题。如果你之前一直用 npm也不影响下面的命令我会把 pnpm 和 npm 两种写法都列出来方便你对照操作。1.3 必装插件清单Volar 上场Vetur 退位VS Code 里开发 Vue3 项目插件装对了能事半功倍。第一件要记住的事如果你以前装过 Vetur请立刻禁用它或卸载它。Vetur 是 Vue2 时代的官方插件它不认 Vue3 的script setup语法会导致满屏红色波浪线和错误提示体验极差。Vue3 时代的标准插件是 Volar也就是现在官方推荐的Vue Language Features (Volar)插件包。建议把下面这几个插件一次装齐插件名用途是否必需Vue Language Features (Volar)Vue 单文件组件语法高亮、智能提示、类型检查必装TypeScript Vue Plugin配合 Volar 提供 TS 类型支持强烈建议ESLint代码规范检查提前暴露低级错误建议Prettier - Code formatter统一代码风格保存时自动格式化建议Path Intellisense文件路径自动补全可选但体验提升明显装完插件后在 VS Code 设置里搜vetur确认它是禁用状态然后搜volar确认已启用。这一步做完你在写.vue文件时才能真正感受到 Vue3 的智能提示有多好用——组件内defineProps、ref、computed这些 API 都会有联动提示错误也会出现在“问题”面板里而不是等浏览器报错。2. 创建动作落地用 Vite 脚手架生成你的第一个 Vue3 项目2.1 为什么选 Vite 而不是 Vue CLI这里我需要说一个可能会得罪老用户的观点如果你还在计划用 Vue CLI 创建新项目我建议你慎重。Vue CLI 的维护状态已经进入维护模式官方推荐的新项目脚手架就是 Vite。更重要的是Vite 的开发服务器基于浏览器原生 ES Module冷启动速度是秒开级别热更新也是毫秒级反馈而 Vue CLI 底层的 Webpack 在大型项目上启动动辄就是十几秒甚至几分钟。我用一个真实数据来说明差距一个中等规模的 Vue3 项目同样的机器Vite 启动 dev server 大概 300-500msWebpack 需要 10-20 秒修改一个组件文件后Vite 热更新几乎瞬间完成Webpack 平均要 1-3 秒。对于高频迭代的前端开发来说这个差异直接决定了你的工作流是否顺畅。Vue CLI 当然还有它的价值尤其是旧项目的维护场景。但如果你现在是空着手要创建新项目直接选 Vite别犹豫。2.2 执行创建命令pnpm create vite 全流程实录打开 VS Code按Ctrl ~调出集成终端先确认 Node 和包管理器版本node -v npm -v # 如果安装了 pnpm pnpm -v确认版本没问题后执行创建命令# 使用 pnpm pnpm create vite my-vue3-app --template vue # 使用 npm npm create vitelatest my-vue3-app -- --template vue如果你想要 TypeScript 版本命令改成pnpm create vite my-vue3-app-ts --template vue-ts这里解释一下--template vue的含义它告诉脚手架直接用 Vue 单文件组件模板生成项目跳过交互式选择界面。如果你不指定 template脚手架会进入交互模式让你选择框架和语言变体比如 Vue 还是 React、是否启用 TypeScript、是否启用 JSX。我建议直接用命令参数指定简单直接也方便写进文档复现。以我的经验第一次跑这个命令最容易遇到的坑是pnpm create vite会先下载 create-vite 这个工具在国内网络环境下可能比较慢。如果遇到卡住的情况优先检查你的 npm registry 是否切换到了国内镜像源后面第五节我会详细讲这个问题。2.3 命令跑完后的第一步安装依赖并启动项目创建成功后按提示依次执行cd my-vue3-app pnpm install pnpm devpnpm install会按照 package.json 里的依赖清单把所有包安装到 node_modules。安装完成后pnpm dev会启动 Vite 开发服务器默认端口是 5173终端会输出Local: http://localhost:5173/这样一行信息。在 VS Code 里按住Ctrl点击这个地址浏览器就会打开你的 Vue3 项目首页。看到 “Vite Vue” 的默认欢迎页面恭喜你第一个 Vue3 项目就创建成功了。如果这时候终端报错比如端口被占用或 Node 版本不兼容先别慌第六节我会专门梳理这些高频问题。3. 模板项目到手后先读懂这堆文件再动手3.1 index.html、src/main.js、App.vue 三者之间的关系Vite 脚手架生成的项目结构和 Vue2 时代有明显的不同。你会发现根目录下有一个index.html文件而且它不在 public 文件夹里而是直接放在项目根目录这在 Webpack 时代是不可想象的。Vite 的核心逻辑是把index.html当作入口文件它通过script typemodule src/src/main.js这样的方式加载你的源代码。打开index.html你会看到类似这样的结构!DOCTYPE html html langen head meta charsetUTF-8 link relicon typeimage/svgxml href/vite.svg meta nameviewport contentwidthdevice-width, initial-scale1.0 titleVite Vue/title /head body div idapp/div script typemodule src/src/main.js/script /body /html理解这个结构的重点在于div idapp/div是 Vue 实例挂载的容器main.js会通过createApp(App).mount(#app)把根组件渲染到这个容器里。所以整个页面加载链是index.html→main.js→App.vue→ 子组件。这个关系搞清楚了你就知道改页面标题要去 index.html 里改而不是去某个 .vue 文件里找 title。3.2 main.js 和 Vue2 入口的差异createApp 取代 new VueVue3 的入口文件相比 Vue2 有一处核心变化。Vue2 时代我们是这样写的import Vue from vue import App from ./App.vue new Vue({ render: h h(App) }).$mount(#app)Vue3 则是这样import { createApp } from vue import App from ./App.vue createApp(App).mount(#app)看起来只是 API 名字变了但它背后表达的是“应用实例”和“组件实例”的解耦。Vue2 里new Vue()创建的就是整个应用的根实例所有全局配置都挂在这个实例上Vue3 里createApp()返回的是一个 application 对象你可以在挂载前通过app.use()注册插件、通过app.component()注册全局组件甚至可以创建多个应用实例并行运行。一个常见的迁移坑是Vue2 里用Vue.use(ElementUI)、Vue.prototype.$http axios的这些写法在 Vue3 里全部变了。全局 API 被移到了app实例上原型链挂载也改成了app.config.globalProperties。如果你是从 Vue2 迁过来的老项目入口文件这里是第一处需要动刀的地方。3.3 src 目录里每个文件夹是干什么的默认模板的 src 目录很简洁通常包含这些文件和文件夹src ├── assets # 静态资源比如项目用到的 logo 图片 ├── components # 可复用组件 ├── App.vue # 根组件 ├── main.js # 入口文件 └── style.css # 全局样式components文件夹放的是通用组件比如按钮、表格、弹窗这个约定和 Vue2 一样。assets文件夹在 Vite 里的行为比较特殊它里面的资源会被构建工具处理比如小于 4KB 的图片会被转成 base64 内联而不是像 public 文件夹里的资源那样原样拷贝。如果你分不清该把静态资源放 assets 还是 public记住一个原则需要被构建工具处理的比如在组件里 import 引用的放 assets不需要处理的比如 favicon、第三方静态文件放 public。Vite 模板默认没有创建 router、store、views、api 这些目录需要你根据自己的项目需要去新建。下一节我会演示如何从零把这些目录搭起来把默认模板改造成一个真正能用的业务骨架。4. 把欢迎页改成业务骨架路由、状态管理、请求层一次配齐4.1 安装 Vue Router 4 并配置第一个路由页面Vue3 项目里路由选择很明确——Vue Router 4。安装命令pnpm add vue-router4装完后在 src 下新建两个文件夹views放页面组件router放路由配置。先创建一个简单的页面组件src/views/HomeView.vuescript setup const message 首页 /script template div classhome h1{{ message }}/h1 p如果看到这个页面说明 Vue Router 已经成功跑起来了。/p /div /template style scoped .home { text-align: center; padding: 40px; } /style然后在src/router/index.js里配置路由import { createRouter, createWebHistory } from vue-router import HomeView from ../views/HomeView.vue const router createRouter({ history: createWebHistory(import.meta.env.BASE_URL), routes: [ { path: /, name: home, component: HomeView } ] }) export default router这里有个值得注意的细节history我们选择了createWebHistory这意味着 URL 是干净的/、/about这种形式不带#。这是 Vue3 官方推荐的默认模式但它要求生产环境下的服务器必须把所有请求都指向 index.html否则刷新二级路由页面会 404。如果你没有配置服务器的条件可以考虑退回createWebHashHistoryURL 会变成/#/about但省去了服务器配置的麻烦。最后一步在main.js里用app.use(router)注册路由并在App.vue里加router-viewscript setup import { RouterView } from vue-router /script template RouterView / /template现在执行pnpm dev浏览器打开 http://localhost:5173/ 应该能看到刚写的首页内容了。这就是一个最简路由系统从零到可用的完整链路。4.2 状态管理选择Pinia 取代 VuexVue3 的官方状态管理库是 Pinia现在已经进入核心库的推荐列表Vuex 4 虽然可用但已经不再是官方推荐。Pinia 的设计更贴合 Composition API去掉了 Vuex 里繁琐的 mutations、modules 嵌套命名空间直接用defineStore定义 store用起来像调用普通函数一样自然。安装 Piniapnpm add pinia创建一个 store 文件src/stores/counter.jsimport { defineStore } from pinia import { ref, computed } from vue export const useCounterStore defineStore(counter, () { // state const count ref(0) // getters const doubleCount computed(() count.value * 2) // actions function increment() { count.value } return { count, doubleCount, increment } })这种写法叫作 setup store它的优势是直接用 Vue3 的 ref 和 computed 来定义状态具备天然的响应式和 Composition API 的复用逻辑。如果你的项目还停留在 Options API 的写法习惯Pinia 也支持类似 data、getters、actions 那样的配置式写法两种风格可以混搭。在组件里使用 storescript setup import { useCounterStore } from ../stores/counter const store useCounterStore() /script template div p计数: {{ store.count }}/p button clickstore.increment1/button /div /templatePinia 的使用体验最直观的感受是“不需要再写 commit 和 dispatch”了store 方法直接调用数据响应式自动跟踪。你会发现它更像是一个带状态的组合式函数而不是一个需要遵循各种规则的管理器。4.3 封装请求层axios 实例化与 Vite 跨域代理几乎每个项目都需要发接口请求推荐你直接装 axios 并做一层简单的封装pnpm add axios新建src/api/request.jsimport axios from axios const request axios.create({ baseURL: /api, timeout: 10000 }) // 请求拦截器 request.interceptors.request.use( config { const token localStorage.getItem(token) if (token) { config.headers.Authorization Bearer ${token} } return config }, error Promise.reject(error) ) // 响应拦截器 request.interceptors.response.use( response { const res response.data if (res.code ! 0) { alert(res.message || 请求出错) return Promise.reject(new Error(res.message || Error)) } return res }, error Promise.reject(error) ) export default request这里的核心配置是baseURL: /api。为什么不用完整的后端地址因为在开发环境下浏览器会拦截跨域请求你在 axios 里写了http://localhost:8080请求发出去会被 CORS 拦截。正确做法是在 Vite 配置里设置代理让/api开头的请求转发到真实的后端服务器。修改根目录vite.config.jsimport { fileURLToPath, URL } from node:url import { defineConfig } from vite import vue from vitejs/plugin-vue export default defineConfig({ plugins: [vue()], resolve: { alias: { : fileURLToPath(new URL(./src, import.meta.url)) } }, server: { proxy: { /api: { target: http://localhost:8080, // 后端真实地址 changeOrigin: true, rewrite: path path.replace(/^\/api/, ) } } } })这里同时配置了别名指向 src 目录。从这之后你在任何组件里都可以用import request from /api/request来引用封装好的请求实例路径不再需要写一长串相对定位符不用再担心../../../../这种地狱级相对路径的歧义问题了。4.4 ESLint 和 Prettier代码规范从创建项目第一天就接好Vite 默认模板其实已经集成了 ESLint 配置但在文件保存自动格式化上还需要补充一下。ESLint 负责检查代码质量和规范Prettier 负责格式化风格两者需要配合使用。我建议在package.json里添加 lint 脚本{ scripts: { dev: vite, build: vite build, preview: vite preview, lint: eslint . --ext .vue,.js,.ts --fix } }然后在 VS Code 设置里开启保存自动修复这样每次按下Ctrl S文件就会自动格式化并修复基本的 lint 错误。我见过很多半路接入规范的项目几十个文件全部爆红改起来痛不欲生。从项目创建第一天就接好格式化是最省成本的决策。5. 点击运行之后热更新原理、调试配置与建档常见问题5.1 Vite 热更新为什么这么快以及“改了不生效”的排查Vite 能在几百毫秒内响应代码修改是因为它的热更新机制和 Webpack 不同。Webpack 的热更新是全量构建后用 websocket 推送更新Vite 则是通过原生 ES Module 按需加载某个文件修改了浏览器只需要重新请求那个模块其他模块完全不动。这个差异在大项目中尤其明显Vite 几乎能做到“改一行秒刷”。但有两种情况会让 Vite 的热更新失效需要特别注意修改vite.config.js本身这个文件的变化需要重启 dev server 才生效因为它是构建工具的配置不属于模块依赖图修改了组件内部引用的非组件文件比如直接 import 一个 .json 或 .txt偶尔遇到缓存这时手动刷新一下浏览器即可。如果你改了页面内容浏览器没反应先看看终端有没有报错信息如果没有报错再确认修改的是否是.vue文件而且这个文件确实被路由或父组件引用了。大多数时候按一下浏览器刷新就能解决。5.2 在 VS Code 里配置 Vue3 断点调试VS Code 的调试功能在 Vue3 项目里同样好用你可以在源码里打断点在编辑器里看到变量的实时值。这个配置方式比较简单在vite.config.js里开启 sourcemapexport default defineConfig({ plugins: [vue()], build: { sourcemap: true } })然后按F5如果是第一次运行VS Code 会提示你选择调试环境选 Chrome。它会自动生成launch.json你只需要把 URL 改成你的开发地址{ version: 0.2.0, configurations: [ { type: chrome, request: launch, name: Vue3 Debug, url: http://localhost:5173, webRoot: ${workspaceFolder}/src } ] }之后按F5就会自动启动浏览器并连接调试器。在组件里的console.log之外你可以直接在代码行号处点红色圆点打断点程序执行到那里会自动停住鼠标悬停就能看变量值。相比满屏打 log 再删除的方式这种方式的效率高很多。5.3 高频报错实录轻松识别并解决它们从创建到运行的路径上有几个报错几乎每个人都会遇一次。第一个是运行pnpm dev时的版本报错Error: Vite requires Node.js version 18.17.0这个最直接就是 Node 版本太低去 Node 官网下载 LTS 版本重装即可。注意装完后在命令行里确认node -v的输出已经更新如果还是旧版本可能需要重启终端。第二个常见报错是Uncaught SyntaxError: Invalid or unexpected token这个报错出现在浏览器控制台时大多不是代码语法问题而是编码问题。文件里混入了全角符号、不可见字符或 BOM 头尤其是在 Windows 下用记事本编辑过文件后容易出现。排查方法用 VS Code 打开对应的 .js 文件右下角确认文件编码是 UTF-8用“命令面板”执行“Change File Encoding → Reopen with Encoding → UTF-8”转换一下同时检查代码里的引号、括号是否有全角字符。另一个可能是你引入了某个第三方库它输出的 ES Module 格式和你的构建配置不兼容这时检查 import 路径是否精确到了文件级别。第三个高频问题是启动后浏览器页面白屏、控制台报 503 或 WebSocket 无法连接。这多半是 dev server 所在端口的问题比如 5173 被占用Vite 会自动换 5174但 VS Code 调试器地址没更新。解决方法是启动时看终端输出的实际端口或者手动指定固定端口pnpm dev --port 5173 --strictPort--strictPort的意思是端口被占用就直接报错而不是默认换端口这样你反而更容易发现问题。5.4 想用 JSX 或 uniapp/electron 扩展创建期就该知道的支持边界Vite 的--template vue生成的是标准 SFC 模式也就是.vue单文件组件写法。如果你打算在项目里用 JSX 写组件需要先装插件pnpm add vitejs/plugin-vue-jsx然后在vite.config.js里注册这个插件之后你就可以在.jsx/.tsx文件里使用 Vue3 的 JSX 语法了。同样地如果你未来要把 Vue3 项目改造为 uniapp 应用或者 Electron 桌面端Vite 在这些场景下都有对应的脚手架模板整体结构和你现在创建的项目是相通的。提前理解这些边界等你真正遇到这类需求时就不会觉得是推翻重来而是顺手加一层配置而已。6. 创建阶段的高频坑从版本冲突到依赖安装失败的完整排查链路6.1 Node.js 版本与 Vite 的适配关系详解创建项目时第一个高频坑是 Node 版本和 Vite 大版本不兼容。比如你执行pnpm create vite时它会默认拉取最新版 create-vite这个工具通常要求非常新的 Node 环境。如果你机器上装的是 Node 16 或更早版本创建命令本身就可能报错错误信息通常长这样package.json: Only files and directories are supported或者You are using Node 16.0.0 but this version of create-vite requires Node ^18.0.0 || 20.0.0遇到这种问题我的处理流程是这样先执行node -v确认当前版本如果版本过低去 nodejs.org 下载 LTS 版本直接覆盖安装安装完成后重新打开终端执行node -v确认版本号变化重新执行创建命令。这里要特别注意Windows 用户在安装新版 Node 后旧版本信息有时还会残留在环境变量 PATH 里。如果你执行node -v显示的还是旧版本可以在命令行执行where node查看 Node 可执行文件的实际路径把旧路径从系统 PATH 中删掉即可。6.2 pnpm install 卡住或失败登记源的问题与解决方法如果你在公司网络或国内网络环境下安装依赖pnpm install卡在Downloading或者报ETIMEDOUT大概率是源的问题。这时需要把包管理器的 registry 切换为国内镜像源比如淘宝镜像或者你所在公司内部的私有源如果有的话。切换 npm 源npm config set registry https://registry.npmmirror.com切换 pnpm 源pnpm config set registry https://registry.npmmirror.com切换完成后建议同时清一下 pnpm 的缓存和代理配置如果有的话pnpm store prune然后重新执行pnpm install。绝大多数情况下换源之后依赖安装就能顺利用完。这里提一句如果你在全局配置过任何代理相关的环境变量恰好又是走不了的节点一定要清理掉否则换源也没用。pnpm config get proxy和pnpm config get https-proxy可以用来检查现有代理配置有输出就清除pnpm config delete proxy pnpm config delete https-proxy排查完这些再用pnpm install重新装一次基本不会再有网络层面的问题。6.3 一个容易被忽视的细节为什么项目在 Edge 浏览器里偶尔卡顿或按钮失灵有些用户反馈 Vue3 项目在 Edge 浏览器里会出现奇怪现象比如“有时无法关闭浏览器右上角的最小化按钮”。听到这类描述第一时间要分清楚问题发生在哪一层是应用层面的组件渲染异常还是浏览器本身的异常行为。我的经验是90% 的情况和 Vue3 项目本身无关而是开发时过多使用了弹出层、遮罩层或全屏组件某个组件的 z-index 或事件冒泡处理影响了浏览器原生交互区域的点击。排查这类问题有一个固定思路无痕模式打开同一个页面禁用全部浏览器扩展如果正常了说明是扩展脚本注入导致的冲突如果依然异常就逐步注释掉项目里涉及全局事件监听的代码特别是mousedown、click捕获阶段处理的逻辑。在项目中找全局的addEventListener看有没有在 document 或 window 上注册事件而不做阻止。这通常就是问题的元凶。6.4 创建后的项目结构升级从 Hello World 到后台管理系统的雏形说到热搜词里的“vue3 后台管理系统”不少人就是奔着这个目标来的。一个标准后台管理系统的前端结构通常在创建后的项目基础上需要增加这些模块src ├── api # 接口请求定义 ├── assets # 静态资源 ├── components # 通用组件 ├── layout # 后台布局框架侧边栏、顶栏、主内容区 ├── router # 路由配置通常包含动态路由 ├── stores # Pinia 状态管理 ├── styles # 全局样式 ├── utils # 工具函数 ├── views # 页面组件 ├── App.vue └── main.js有了别名、路由、Pinia、axios 请求封装你就有了搭后台管理系统的基础。接下来按业务需要填充 layout 里的侧边栏菜单、顶部导航、views 下的具体页面再配上动态路由和权限控制整个管理端就能跑起来了。从热词里也能看到“若依 vue3 ts 报错”这类问题常被搜索说明很多人在这个阶段会碰到 vue3 和 ts 配置磨合的坑。我的建议是如果你是为了快速完成业务可以先以 JS 为主把基础跑通不要在类型系统的细节上空耗太久。前端框架的学习路线永远是“跑通流程”优先于“精雕细节”。最后再分享一个我自己的习惯这几年我用 VS Code 创建 Vue3 项目的次数很多了逐渐固定下来一套自己的流程先检查 Node 版本再切换到 npmmirror 源用pnpm create vite创建项目进入项目后第一件事就是配路由、Pinia、axios 和别名把这些基础设施打通后我才开始写业务。周围的朋友经常问我要项目模板其实模板的底层就是这篇文章的这几步操作。写代码这件事最重要的不是记住每个配置项而是搞懂配置之间的依赖关系——Node 提供运行环境Vite 负责构建和热更新Vue Router 管理页面流转Pinia 管理共享状态axios 连接后端。如果你想少走弯路创建项目的第一天就把这五件事理清楚之后所有的业务开发都会顺畅很多。另外一个小技巧每次新建项目时把pnpm create vite系列命令和配置代码整理成一个 note放在自己的代码片段库里。这样下次新建时连查文档的时间都省了。