先说结论：用 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 项目能够跑起来，本质上依靠的是 npm（Node Package Manager）去下载和管理各种依赖包，然后用 Node.js 去执行构建和开发服务器的启动脚本。VS Code 在里面的角色更接近一个"编辑器 + 终端"，它负责让你舒服地写代码，但不负责真正运行代码。

所以在你打开 VS Code 之前，第一件事是确认 Node.js 装好了没有。打开命令行（Windows 下是 CMD 或 PowerShell，macOS/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 开发变舒服的是插件生态。我每次配置新环境，下面这几个插件是必装的：

这里有一个非常关键、也是新手最容易踩的坑：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 vue@latest

这个命令会进入交互式配置界面，问你项目名称、是否使用 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:5173，Vue 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 下载二进制文件，网络不稳定就会失败。现在的新项目基本都改用 sass（dart-sass）了，安装时不会编译原生模块，稳定性好很多。如果你的项目还在用 node-sass，建议把package.json里的依赖改成"sass"，然后删掉node_modules重新安装。

第二个是 Node.js 版本不匹配导致安装失败。报错信息里通常会有一堆gyp ERR!或node-gyp字样。这种情况最直接的解决办法不是硬修，而是切换 Node.js 版本。建议手动安装 nvm（Node Version Manager）来管理多个 Node 版本，在项目目录下切换合适的版本重试。

npm install反复失败时，还有一个大招：删掉node_modules目录和package-lock.json文件，再重新执行npm install。如果项目里还残留了不完整的依赖，这样清理一次往往能解决。

4.3 请求接口跨域与本地代理配置

Vue 项目开发阶段最常遇到的一个问题就是前端请求后端接口报 CORS 或者跨域。因为前端开发服务器跑在 5173，后端接口跑在 8080 或者其他端口，浏览器会拦截跨域请求。

解决办法不是在浏览器装插件，而是在 Vite 里配置代理。在vite.config.js的server配置里加上proxy：

server: { 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播放m3u8""vue视频m3u8"，这里我专门展开讲一下。m3u8 是一种视频流媒体播放列表格式，它本身不是视频文件，而是一个指向多个视频分片文件的索引列表，播放器会根据列表顺序逐个拉取并播放这些分片。这种格式在直播、点播场景里非常常见，比如在线课程、监控画面播放都用它。

在 Vue 项目里播放 m3u8 视频，最简单的方式是使用 hls.js 这个库。安装命令：

npm install hls.js

在组件中这样使用：

<template> <video id="video" 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里设置base：

export 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 方式是在地址栏里以?key=value形式传参，刷新页面后参数还在，因为它在 URL 里。使用方式：

// 跳转时传参 router.push({ path: '/detail', query: { id: 123 } }) // 接收参数 const route = useRoute() console.log(route.query.id) // 123

params 方式是在路由路径中定义动态段，比如/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.js：

import { 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这些命令写清楚，下次换电脑换环境，或者同事接手项目，照着一跑就能起来。这个习惯帮我省了太多事。