先说结论用 VS Code 跑 Vue 项目卡住你的往往不是 VS Code 本身而是 Node.js 环境、依赖安装和启动命令这条链路没理清楚。这篇我按自己从零到一跑通 Vue 项目的完整过程来写从环境准备、VS Code 插件配置到常见报错排查最后顺带把路由传参、m3u8 视频播放、前后端联调、打包前配置这些高频需求一起整理出来。无论你是刚接触 Vue 的新手还是被某个报错卡住的老同学都可以直接照着操作。写这篇的起因是有个朋友跟我说他用 VS Code 打开项目后一片乱码保存文件也不生效折腾半天才发现连 Node.js 都没装。这种情况我见得太多了很多朋友以为运行 Vue 项目就是把代码放到编辑器里然后点运行按钮实际上前端项目和 C、Java 这类项目的运行逻辑完全不同。Vue 项目本质上是 Node.js 生态下的工程化项目VS Code 只是你写代码的工具真正让项目跑起来的是 Node.js 环境里安装的依赖和执行的 npm 脚本。所以整篇文章的核心链路就是准备好 Node.js在 VS Code 里装对插件然后执行 npm install 和 npm run dev。1. 环境准备Node.js 版本选择与依赖安装1.1 为什么说 Node.js 才是运行 Vue 项目的地基Vue 项目能够跑起来本质上依靠的是 npmNode Package Manager去下载和管理各种依赖包然后用 Node.js 去执行构建和开发服务器的启动脚本。VS Code 在里面的角色更接近一个编辑器 终端它负责让你舒服地写代码但不负责真正运行代码。所以在你打开 VS Code 之前第一件事是确认 Node.js 装好了没有。打开命令行Windows 下是 CMD 或 PowerShellmacOS/Linux 下是终端输入node -v npm -v能正常输出版本号就说明 Node.js 环境没问题。如果提示找不到命令那就需要先去 Node.js 官网下载安装包。这里有一个非常关键的版本选择问题不要看到最新版就无脑装建议选择官网标注为 LTS长期维护版的版本。因为 Vue 项目的依赖包对 Node 版本是有要求的。Vue 3 Vite 的项目通常要求 Node.js 18 以上而 Vue 2 Vue CLI 的老项目在 Node 18/20 上反而可能出问题。我自己踩过一次坑就是拿 Node 20 去跑一个基于 node-sass 的老项目编译直接报错最后降到 Node 16 才顺利跑通。所以装 Node.js 之前先确认你的项目是什么技术栈实在分不清就装 LTS 版本兼容性最好。1.2 npm 镜像源与依赖安装Node.js 装好之后还有一个让新手抓狂的环节npm install 装依赖的时候速度慢得让人怀疑人生甚至直接卡住不动。这是因为默认的 npm 源在国外国内网络访问不稳定是常有的事。解决办法很简单把 npm 源切换成国内镜像。我这里常用的命令是npm config set registry https://registry.npmmirror.com设置之后可以用npm config get registry检查一下是否切换成功。这个镜像源是阿里的 npm 镜像更新频率很高实测下来跑常规依赖完全没问题。切换之后再执行npm install速度会明显快很多。另外再提一个细节装依赖的时候经常有人直接关掉终端或者看到进度条停在某一项就不耐烦。其实 npm install 在解析依赖树的时候会有短暂卡顿尤其是项目依赖特别多的时候这是正常的。建议第一次安装依赖时保持耐心如果需要更快的安装速度可以考虑使用 pnpm 替代 npm但如果你刚开始接触项目先老老实实用 npm减少变量。2. VS Code 侧配置插件、编码与工作区设置2.1 必备插件清单与 Vetur/Volar 冲突问题VS Code 本身是一个编辑器外壳真正让 Vue 开发变舒服的是插件生态。我每次配置新环境下面这几个插件是必装的插件名称用途Vue - Official原名 VolarVue 3 项目必备提供 .vue 单文件组件高亮、语法提示、类型检查VeturVue 2 老项目的高亮与格式化工具ESLint代码规范检查有错误会直接显示在编辑器里Prettier - Code formatter统一代码风格保存时自动格式化Auto Rename Tag改标签时自动同步修改闭合标签提高效率Path Intellisense自动补全文件路径写 import 时非常方便这里有一个非常关键、也是新手最容易踩的坑Vetur 和 Volar 不要同时启用。如果你的项目是 Vue 2就启用 Vetur 禁用 Volar如果是 Vue 3就启用 Volar 禁用 Vetur。两个插件同时开会在 .vue 文件里出现语法提示打架的情况甚至可能让 VS Code 直接卡顿。有时候插件装完并没有立刻生效特别是第一次装 Volar 的时候VS Code 会弹窗提示需要重新加载窗口。这时候不要忽略它点一下Reload让插件真正加载起来。2.2 中文乱码与文件编码设置热搜词里有vue乱码这个关键词我估计很多人遇到过。打开项目后中文显示成乱码最常见的原因就是文件编码不对。VS Code 默认使用 UTF-8 打开文件而有些文件是 GBK 编码保存的特别是从别人那里拷过来的项目或者老旧项目。处理方式打开文件后看 VS Code 右下角的编码提示比如显示UTF-8点它然后选择通过编码重新打开再选择GBK或者GB2312中文就能正常显示了。如果你希望以后保存文件都用同一种编码可以在底部编码按钮里选择通过编码保存避免后续改动造成乱码。如果你要修改整个项目的规则可以在项目根目录建一个.vscode/settings.json文件加入{ files.encoding: utf8, files.autoGuessEncoding: true }这样每次打开文件时 VS Code 会自动猜测编码中文乱码问题会少很多。这里多说一句团队协作时尽量统一 UTF-8这是行业标准避免 GBK/UTF-8 来回转换造成的乱码噩梦。2.3 老系统兼容性提醒看热搜词里有vs code win7这个我得专门说一下。VS Code 从 1.70 版本开始就不再支持 Windows 7/8 系统了如果你还在旧系统上安装最新版 VS Code 会直接提示无法安装或无法运行。这种情况有两个选择一是去官网下载 VS Code 1.69 及之前的版本二是建议升级操作系统。考虑到现在的 Vue 工程化工具链越来越新旧版 VS Code 老系统跑新项目会遇到很多兼容性问题真的不建议在这条路上花太多时间。3. 实操从创建项目到启动成功的完整流程3.1 创建 Vue 项目的两种方式对比运行 Vue 项目的第一步是你好歹得有一个项目。常规做法有两种用 Vite 官方脚手架创建或者用 Vue CLI 创建。Vite 是 Vue 官方现在主推的构建工具创建命令是npm create vuelatest这个命令会进入交互式配置界面问你项目名称、是否使用 TypeScript、是否引入路由Vue Router、是否引入状态管理Pinia等。如果你只是想快速跑起来看效果除了项目名之外推荐先全部选 No等基础跑通后再逐步添加。Vue CLI 是老一代的创建方式命令是npm install -g vue/cli vue create hello-vue它同样有交互式配置默认走的是基于 webpack 的构建体系。对于新手我更推荐直接用 Vite 方式创建因为 Vite 的启动速度非常快项目结构也更轻量清晰。Vue CLI 更适合维护那种历史遗留的 Vue 2 老项目现在的官方新增项目都建议走 Vite。3.2 安装依赖与启动命令创建好项目之后进入项目目录这一步非常关键——必须先安装依赖然后再启动。顺序错了启动会直接报vite 不是内部或外部命令。cd 你的项目目录 npm install npm run dev执行npm run dev之后终端会输出一个本地访问地址。Vite 默认是http://localhost:5173Vue CLI 默认是http://localhost:8080。把地址复制到浏览器打开看到 Vue 的欢迎页面就说明项目已经跑起来了。这里补充一下为什么 Vite 用的是 5173 而不是 8080。8080 这类端口经常被其他程序占用Vite 有意换成了相对冷门的端口来减少冲突。不过如果你 5173 也用不了Vite 会自动往上升级端口号比如 5174、5175终端里会显示最终可用的地址直接复制访问即可。3.3 项目目录结构和 package.json 脚本解读项目跑起来之后你需要大概知道代码放在哪里。Vite 创建的 Vue 3 项目最关键的是src目录里面main.js是入口文件App.vue是根组件components目录放子组件router目录放路由配置。你平时写页面主要就是在src/views或src/components下新建 .vue 文件。package.json文件里的scripts字段定义了项目支持的命令常见的有{ scripts: { dev: vite, build: vite build, preview: vite preview } }npm run dev启动开发服务器npm run build将项目打包成静态文件npm run preview在本地预览打包后的产物。很多新手不知道该用哪个命令记住一个原则开发阶段用 dev上线交付用 build验证打包结果用 preview。Vite 启动后的热更新是默认开启的。你修改 .vue 文件保存后浏览器页面会自动刷新不需要手动重启服务。如果改代码后页面没有自动更新可能是 HMR 失效这个问题我在下一章会专门讲。4. 运行中的常见报错与排查实录4.1 端口占用提示 port is already in use这个报错是最常见的。终端里出现类似这样的信息Port 5173 is already in use解决思路分两步。第一找到占用端口的进程并结束它第二实在找不到占用源就直接改项目端口在vite.config.js里设置import { defineConfig } from vite import vue from vitejs/plugin-vue export default defineConfig({ plugins: [vue()], server: { port: 3000, host: 0.0.0.0 } })如果你只想临时跑一下找到占用端口的进程把它结束掉更快。Windows 下用netstat -ano | findstr 5173查到进程 ID然后任务管理器结束对应进程macOS/Linux 下用lsof -i:5173查看然后kill即可。这里有个小技巧host: 0.0.0.0可以让局域网内其他设备通过你的 IP 访问这个项目方便测试。但要注意开放到局域网意味着同一网络的人都能访问你的开发服务器调试完记得改回来。4.2 依赖安装失败的典型场景与处理思路npm install报错的原因五花八门我遇到的典型场景有两个。第一个是 node-sass 安装失败。这类问题的根源是 node-sass 需要从 GitHub 下载二进制文件网络不稳定就会失败。现在的新项目基本都改用 sassdart-sass了安装时不会编译原生模块稳定性好很多。如果你的项目还在用 node-sass建议把package.json里的依赖改成sass然后删掉node_modules重新安装。第二个是 Node.js 版本不匹配导致安装失败。报错信息里通常会有一堆gyp ERR!或node-gyp字样。这种情况最直接的解决办法不是硬修而是切换 Node.js 版本。建议手动安装 nvmNode Version Manager来管理多个 Node 版本在项目目录下切换合适的版本重试。npm install反复失败时还有一个大招删掉node_modules目录和package-lock.json文件再重新执行npm install。如果项目里还残留了不完整的依赖这样清理一次往往能解决。4.3 请求接口跨域与本地代理配置Vue 项目开发阶段最常遇到的一个问题就是前端请求后端接口报 CORS 或者跨域。因为前端开发服务器跑在 5173后端接口跑在 8080 或者其他端口浏览器会拦截跨域请求。解决办法不是在浏览器装插件而是在 Vite 里配置代理。在vite.config.js的server配置里加上proxyserver: { proxy: { /api: { target: http://localhost:8080, changeOrigin: true, rewrite: (path) path.replace(/^\/api/, ) } } }意思是当前端向/api开头的地址发起请求时Vite 会自动把它转发到http://localhost:8080这个后端服务。这样你在前端代码里请求/api/user/list实际访问的就是http://localhost:8080/user/list。配置完成后需要重启 dev 服务才会生效。这个小细节经常有人漏掉改了配置不重启然后一直怀疑配置写错了。4.4 m3u8 视频播放与在 Vue 项目里的集成方式热搜词里反复出现vue播放m3u8vue视频m3u8这里我专门展开讲一下。m3u8 是一种视频流媒体播放列表格式它本身不是视频文件而是一个指向多个视频分片文件的索引列表播放器会根据列表顺序逐个拉取并播放这些分片。这种格式在直播、点播场景里非常常见比如在线课程、监控画面播放都用它。在 Vue 项目里播放 m3u8 视频最简单的方式是使用 hls.js 这个库。安装命令npm install hls.js在组件中这样使用template video idvideo controls autoplay muted/video /template script setup import Hls from hls.js import { onMounted } from vue onMounted(() { const video document.getElementById(video) const videoUrl https://example.com/stream.m3u8 if (Hls.isSupported()) { const hls new Hls() hls.loadSource(videoUrl) hls.attachMedia(video) } else if (video.canPlayType(application/vnd.apple.mpegurl)) { // 针对 Safari 浏览器的原生 HLS 支持 video.src videoUrl } }) /script需要注意如果播放源地址不合法、跨域或者已经失效视频是拉不到分片数据的播放器会一直转圈或黑屏。遇到这种情况先确认播放地址本身是否能正常访问比如用浏览器直接打开 .m3u8 链接看返回内容再去排查前端代码。另外一个小提醒网页里播放自动播放策略很严格带声音的视频大概率不能自动播放。上面示例里我加了muted属性这是为了绕过浏览器的自动播放限制如果你需要声音还是让用户手动点击播放比较靠谱。4.5 打包后布局异常与路由 404 问题热搜词里有vue 打包后 布局异常这个属于开发正常、上线翻车的经典案例。开发时页面显示完全正常执行npm run build后放到服务器上发现页面样式错乱、图片丢失点击路由还是 404。先说布局异常根本原因是打包后的静态资源路径不对。默认的base配置是/这会把资源路径写成绝对路径比如/assets/index.js。如果项目被部署在子目录比如https://example.com/myapp/绝对路径的/assets会访问到域名根目录自然就找不到了。解决方法是在vite.config.js里设置baseexport default defineConfig({ base: ./ })base: ./表示使用相对路径打包后的资源引用会变成./assets/index.js这样部署在任意子目录下都能找到。再看路由 404这是因为 Vue Router 默认使用 HTML5 History 模式这种模式在浏览器地址栏里看起来是标准路径但服务器必须把所有路径都重定向到index.html否则你直接访问子路径时服务器找不到对应文件就 404 了。如果你没有服务器配置权限最简单的方案是把路由模式改成 Hash 模式import { createRouter, createWebHashHistory } from vue-router const router createRouter({ history: createWebHashHistory(), routes: [ // 路由配置 ] })Hash 模式下地址会带#虽然看起来不如 History 模式美观但部署时省心很多不需要额外配置服务器。4.6 热更新失效与 .vue 文件不生效的排查思路热更新失效也是开发过程中很容易遇到的一个问题。现象是代码改了好几处浏览器页面纹丝不动。排查思路按顺序来第一确认项目是在本地开发服务器下打开的而不是直接双击了index.html。第二确认 VS Code 的终端里没有报错如果有红色错误信息HMR 会进入降级模式等错误修好才会恢复。第三把node_modules里的.vite缓存目录删掉再重新启动有时候缓存文件损坏会导致热更新失灵。有一个隐藏问题值得单独说在某些老版本 Vite Vue 的组合下如果你在一个循环渲染的页面里直接修改模板结构偶尔会出现页面不刷新的情况但控制台没有报错。这时候最简单的办法是保存文件后在浏览器里手动刷新一下试试如果刷新就能看到说明构建本身没问题只是 HMR 对特定改动的处理还不够智能。5. 项目运行起来之后路由、状态管理与前后端联调5.1 路由参数传参与页面标题动态更新项目能正常启动后你接下来要处理的无非就是页面跳转和参数传递。Vue Router 传参有两种常用方式query 方式和 params 方式很多人搞混。query 方式是在地址栏里以?keyvalue形式传参刷新页面后参数还在因为它在 URL 里。使用方式// 跳转时传参 router.push({ path: /detail, query: { id: 123 } }) // 接收参数 const route useRoute() console.log(route.query.id) // 123params 方式是在路由路径中定义动态段比如/detail/:id跳转时用params传参。但要注意用 params 传参时必须通过路由的名字或路径字符串跳转直接写router-link to/detail是拿不到动态参数的。params 方式的参数值也会出现在 URL 路径里刷新后不会丢。关于动态修改页面标题这算是新手的进阶需求。可以在全局路由守卫里处理router.afterEach((to) { document.title to.meta.title ? ${to.meta.title} - 我的Vue应用 : 我的Vue应用 })配置路由时给每个路由加meta.title字段比如{ path: /home, component: Home, meta: { title: 首页 } }这样每次切换路由浏览器标签页标题就会跟着变非常实用。5.2 Pinia 与 Vuex 的选择状态管理该用哪个项目中多个组件要共享数据比如用户登录状态、购物车数据就需要状态管理。Vue 官方推荐的是 Pinia因为它在 Vue 3 下类型提示更好、API 更简洁、体积也更小。Vuex 是老的方案维护大型老项目时可能会遇到但新项目我建议直接用 Pinia。安装 Pinia 后在main.js里注册import { createApp } from vue import { createPinia } from pinia import App from ./App.vue const app createApp(App) const pinia createPinia() app.use(pinia) app.mount(#app)然后再建一个 store 文件比如src/stores/user.jsimport { defineStore } from pinia export const useUserStore defineStore(user, { state: () ({ name: , token: }), actions: { setToken(token) { this.token token } } })组件里使用时import { useUserStore } from /stores/user const userStore useUserStore() userStore.setToken(abc123)这套流程跑通了组件之间的数据共享问题就算解决了。至于 Pinia 和 Vuex 的深度对比比如 mutation、getter 的差异建议你先把基础跑通后再回头看官方文档否则容易一头雾水。5.3 前后端分离联调Spring Boot / FastAPI 与 WebSocket 场景很多项目都是前后端分离开发前端跑在 5173后端跑在 8080可能是 Spring Boot、FastAPI 或者其他。联调时除了前面说的代理跨域还有几个实操细节。第一请求接口的baseURL建议配置在环境变量文件里.env.development和.env.production别写死在代码里。开发环境用/api走代理生产环境替换成真实接口域名这属于前端工程的规范写法。第二如果你需要对接 WebSocket 接口比如做聊天、在线通知、大屏实时数据Vue 项目里原生支持也很简单const ws new WebSocket(ws://localhost:8080/ws) ws.onopen () { console.log(连接建立) ws.send(JSON.stringify({ type: ping })) } ws.onmessage (event) { const data JSON.parse(event.data) console.log(收到消息:, data) } ws.onclose () { console.log(连接关闭) }这里我踩过的坑是WebSocket 地址里不要带http要用ws://或wss://而且如果前端部署在 HTTPS 环境下WebSocket 也必须用wss://否则会被浏览器拦截。另一个坑是网络切换或者服务端重启会导致 WebSocket 断开你需要监听onclose事件做自动重连不然用户会莫名其妙断线。第三和 FastAPI 或 Spring Boot 联调时如果后端没配 CORS 但你一定要在浏览器里直接请求跨域接口有个兜底方案是临时用 Vite 代理绕过跨域限制但这是开发环境的操作不能带到生产环境。生产环境要么前端和后端同源部署要么后端正确配置跨域白名单两者都可以但必须有且仅有一个生效。5.4 用 VS Code AI 插件提升开发效率最近热搜里很多人在问 VS Code 接入 AI 插件的事比如 Codex、Kimi、DeepSeek 这些。这类工具的用法都一样在 VS Code 插件市场里搜索对应插件名称安装然后在插件设置里配置 API 密钥最后通过侧边栏会话框体验问答、代码生成、代码解释等功能。使用这类插件时我要提醒一句不要盲信生成的代码特别是涉及依赖安装、网络请求、数据处理的代码一定要理解后再放进项目里。我见过有人让 AI 生成了一段fetch请求的代码结果没处理错误状态线上出问题排查半天。AI 是提高效率的助手不是替你思考的工具。6. 最后的实操心得折腾这么多年 Vue 项目我最深的体会是运行 Vue 项目这件事真正的技术含量不在 VS Code 操作上而在对 Node.js 生态和构建工具链的理解上。环境不对花再多时间在编辑器设置上也是白搭环境对了开发流程自然流畅。给看到这里的朋友几个实在的建议。第一项目跑不起来的排查顺序永远是Node 版本是不是匹配、依赖是否完整安装、端口是否被占用、配置改动后是否重启按照这个顺序逐个排查绝大多数问题都能定位。第二遇到报错先冷静读终端里的错误信息英文不好没关系报错的前几行通常就告诉你是哪一步出了问题别急着全网搜。第三node_modules不是你改坏了依赖经常大胆删除重装很多时候杀敌一千总比卡住不跑强。最后再分享一个小技巧建议每个项目都在根目录写好README.md把npm install、npm run dev、npm run build这些命令写清楚下次换电脑换环境或者同事接手项目照着一跑就能起来。这个习惯帮我省了太多事。