企业官网建设流程全解析

我们直接进入正题：用 VS Code 运行 Vue 项目。这篇文章就是写给那些刚接触 Vue 或者被“环境配置”劝退的人，我把从零到跑起来的完整路径、中间会踩的坑、以及跑起来之后怎么调、怎么查，全部拆开讲。先说明一点，这不需要你有多深的计算机功底，但你要有耐心，因为前端环境这东西，80% 的问题都出在版本和依赖上。

1. 环境准备：把地基打牢再动手

很多人拿到 Vue 项目第一步就是npm install，结果装到一半报错、装完了启动报错、启动成功了几分钟后又各种警告，其实绝大多数问题都能在环境这一步提前避免。环境和工具链的高版本不一定是最稳定的，适合项目、适合团队、适合你操作系统版本的才是最好的。

1.1 Node.js 版本怎么选

Vue 项目跑起来离不开 Node.js，它不仅是包管理器 npm 的运行基础，也是 Vite、Webpack 这些构建工具的宿主环境。你可以把 Node.js 理解成 Vue 项目的“运行时”，版本不对，后面全白搭。

之前实际测试过，Vue 3 + Vite 5 的项目，Node 18.18 及以上跑得很顺；Vue 2 + Webpack 的老项目，Node 14 到 16 是舒适区，强行用 Node 20 去跑老项目，经常出现OpenSSLError这种加密库兼容性问题，很多人卡在这一步其实不是代码问题，是 Node 版本的问题。

推荐方案：直接用nvm（Node Version Manager）管理多个 Node 版本，随时切换。Windows 用户去装 nvm-windows，macOS 用户用 nvm 命令即可。安装完执行：

nvm install 18.18.0 nvm use 18.18.0 node -v

看到v18.18.0就说明切过来了。如果你懒得装 nvm，那就确保你本机的 Node 版本不低于 16，且尽可能用 LTS（长期支持版）。说句实在话，Node 版本的选择没有统一答案，但 LTS 版本永远是最稳妥的起点。

1.2 包管理器用哪个：npm、yarn 还是 pnpm

很多新手会纠结这个问题，我直接说结论：如果项目里有pnpm-lock.yaml优先用 pnpm，有yarn.lock用 yarn，只有package-lock.json就用 npm。别混用，混用 lock 文件会造成依赖版本漂移，项目在你电脑上能跑，在同事电脑上跑不起来，或者今天跑起来明天跑不起来，都是这种问题。

npm 是 Node.js 自带的，不用额外安装。pnpm 的优势是省磁盘空间、安装速度快，而且对 monorepo 的支持很好。如果你没有历史包袱，建议直接上 pnpm：

npm install -g pnpm pnpm install

注意一点：执行安装命令之前，确认自己是否开了全局代理之类的东西。国内开发者如果下载依赖太慢或者一直失败，可以把 npm 镜像切到淘宝源：

npm config set registry https://registry.npmmirror.com pnpm config set registry https://registry.npmmirror.com

实测下来，镜像切换之后安装速度能有显著提升，尤其是node-sass、electron这类带二进制文件的依赖。但切了镜像之后如果还失败，那大概率是别的问题，后面会专门讲。

2. VS Code 安装与插件配置

环境层搞定后，轮到编辑器环节。VS Code 本身只是一个编辑器，装上合适的插件和配置之后，才会变成真正顺手的 Vue 开发 IDE。

2.1 VS Code 下载安装要注意什么

VS Code 下载直接去官网就行，认准code.visualstudio.com，其他渠道下载的安装包来历不明，不推荐。安装的时候有一点要特别留意：Windows 用户建议勾选“Add to PATH”和“Register as default editor”这两个选项，这样之后在命令行里执行code .就能直接用 VS Code 打开当前目录，配合终端操作效率翻倍。

安装完后打开 VS Code，左侧栏是功能图标区，Ctrl+Shift+X打开扩展面板，这里是整个编辑器生态的核心入口。所有插件都是从这安装的。

2.2 必装插件清单

下面这几款插件是运行 Vue 项目时我实测下来真正有用的，不是广告，是我自己日常开发离不开的：

Volar 这地方多说一句，Vue 3 项目千万不要再装 Vetur，两个插件同时开启会冲突，导致提示错乱，这是新手很容易踩的坑。无论是从 Vue 2 迁移还是新开 Vue 3 项目，统一用 Volar 就够了。

2.3 编辑器基础配置

插件装好之后，打开设置Ctrl+,，把下面这几项加上，基本就处于舒服状态了：

{ "editor.formatOnSave": true, "editor.defaultFormatter": "esbenp.prettier-vscode", "editor.tabSize": 2, "files.eol": "\n", "emmet.includeLanguages": { "vue-html": "html", "vue": "html" } }

files.eol设为\n是为了避免 Windows 环境下的 CRLF 和 Linux 下的 LF 混用，这能防止团队协作时出现“明明没改过这行代码，git diff 却显示整行被改动”的尴尬情况。这个细节我真建议每个人都配置上，能省去很莫名其妙的沟通成本。

3. 创建并运行 Vue 项目的完整流程

环境装好了，插件配好了，现在开始真正“跑起来”。这里我分三条路径来说：从零创建项目、从 Git 拉取已有项目、以及启动之后的内部逻辑。

3.1 用 Vite 创建 Vue 3 项目

Vue 官方现在推荐的构建工具是 Vite，启动速度快、热更新快，体感上比老一代的 Webpack 舒服太多。在终端执行：

npm create vue@latest

执行之后会问你项目名字、是否使用 TypeScript、是否包含路由（Vue Router）、是否安装 Pinia（状态管理）、是否需要 ESLint 和 Prettier 等等。新手建议先都选“No”，等跑通整个流程后再逐步加种类插件，这样排查问题的时候范围会更小。

或者更直接一点，用 Vite 官方模板：

npm create vite@latest my-vue-app -- --template vue cd my-vue-app npm install npm run dev

注意这里my-vue-app就是你的项目目录名，可以随意替换。看到终端输出Local: http://localhost:5173/的时候，项目就已经起来了，浏览器打开这个地址即可看到默认页面。

3.2 用 VS Code 打开项目并启动

创建好的项目，在当前目录执行：

code .

VS Code 就会打开整个项目目录。左侧文件树里能看到src、public、package.json、vite.config.js这些文件和目录，这就是一个 Vue 项目的基本骨架。

在 VS Code 里按Ctrl+``（反引号）调出内置终端，运行：

npm run dev

启动命令运行后，Vite 会占住终端进程，这个终端窗口不要关，一旦关闭项目就停了。Vite 的热更新（HMR）默认开启，你改任何.vue文件的代码，浏览器页面会在几百毫秒内自动同步刷新，不需要手动刷新浏览器。

这里要提醒一句：如果终端报了vite: not recognized之类的错误，说明 npm scripts 没跑起来，大概率是依赖没装好，重新执行一次npm install再看结果。依赖装好后，在package.json的scripts字段里，dev就是开发模式启动脚本，build是打包生产版本，preview是本地预览打包结果。

3.3 npm run dev 之后发生了什么

这段内容适合那些不满足于“能跑就行”的人。npm run dev等于执行了node_modules/.bin/vite，Vite 启动了一个本地开发服务器，它做的事情包括：

• 读取index.html作为入口
• 通过 ES Module 的方式解析src/main.js里 import 的各种模块
• 把.vue单文件组件编译成浏览器能识别的 JS 对象
• 启动 WebSocket 服务，用于热更新推送

vite.config.js里的server.port字段可以修改端口号，默认 5173。如果端口被占用，Vite 会自动加一，控制台会提示最终使用的端口，不用太紧张。

4. 调试与接口联调

项目跑起来了，只是第一步，真正开发过程中的痛点更多集中在“页面出来了但数据没出来”这类问题上。这就要说到调试和接口联调。

4.1 配置断点调试（launch.json）

很多新手只在代码里写console.log来排查问题，如果是简单逻辑还好，但遇到复杂数据流时效率极低。VS Code 自带调试面板，配置一次之后，可以直接在编辑器里打断点、单步执行、查看变量值。

点击左侧的“运行和调试”图标，创建一个launch.json，对于 Vite 项目，配置如下：

{ "version": "0.2.0", "configurations": [ { "type": "chrome", "request": "launch", "name": "Debug in Chrome", "url": "http://localhost:5173", "webRoot": "${workspaceFolder}/src" } ] }

先启动npm run dev，然后按F5，VS Code 会自动打开一个新的 Chrome 窗口并进入调试模式。在.vue文件的script代码行号左边点一下设置断点，再在页面上触发对应的交互，代码执行到断点时就会暂停，你可以悬停查看变量值，也可以按F10单步跳过、F11进入函数内部，比console.log排查问题效率高出不少。

4.2 跨域问题怎么处理

开发中几乎一定会遇到接口跨域。前端跑在localhost:5173，后端跑在localhost:8080，浏览器出于同源策略，默认会拦截两者之间的请求。处理方式很多，开发环境下最简单暴力的就是配置 Vite 代理。

在vite.config.js里加一段：

import { defineConfig } from 'vite' import vue from '@vitejs/plugin-vue' export default defineConfig({ plugins: [vue()], server: { proxy: { '/api': { target: 'http://localhost:8080', changeOrigin: true, rewrite: (path) => path.replace(/^\/api/, '') } } } })

配置完成后，前端代码里请求/api/login，Vite 会把请求转发到http://localhost:8080/login，同时浏览器看到的还是同源请求，跨域问题直接消失。changeOrigin: true的意思是让后端收到请求时认为请求来自localhost:8080本身，避免部分后端框架的防盗链机制误判。

这个配置也是前后端分离项目联调的基础，后面只要看到“Access-Control-Allow-Origin”之类的报错，第一反应就是代理没配好或者后端没开 CORS。

4.3 状态管理选 Pinia 还是 Vuex

热词里有“pinia vs vuex”，这里顺带讲一下。Vuex 是 Vue 2 时代的官方状态管理库，Vuex 4 虽然也支持 Vue 3，但写法上还是略显繁琐。Pinia 是 Vue 3 时代的官方推荐，去掉了mutations的概念，直接改 state，API 更加简洁，而且天然支持 Composition API 和 TypeScript。

如果你是全新项目，直接用 Pinia 就好。创建 store：

// stores/counter.js import { defineStore } from 'pinia' export const useCounterStore = defineStore('counter', { state: () => ({ count: 0 }), actions: { increment() { this.count++ } } })

组件里使用：

<script setup> import { useCounterStore } from '@/stores/counter' const counter = useCounterStore() </script> <template> <button @click="counter.increment">{{ counter.count }}</button> </template>

如果是从老项目迁移过来的，Vuex 也不是不能用，但新项目没必要再绕远路。小项目甚至不需要状态管理，用ref配合provide/inject就足够了，别过度设计。

5. 常见问题排查实录

这一节是所有你可能会遇到的、有代表性的坑，基本都是我用 VS Code 跑 Vue 项目时踩过或者帮别人解决过的真实问题。我之前差不多把这些整理成一份速查表，特别适合遇到错误时对照着看。

5.1 端口占用

启动的时候提示Port 5173 is already in use，页面死活打不开。解决方式有两种：一是关掉占用端口的进程，二是改端口。

快速查找占用端口的进程：

# Windows netstat -ano | findstr :5173 taskkill /PID 12345 /F # macOS / Linux lsof -i :5173 kill -9 12345

懒人方案是直接在vite.config.js里设置server.port和strictPort: false，这样端口被占用时 Vite 会自动往上找可用端口，不会中断启动。但我自己还是习惯先找出是谁占了端口，有时候占端口的可能是另一个跑着的开发服务，误杀了也不太好。

5.2 依赖安装失败

npm install中途报错，常见的原因有这么几类：

第一类是网络问题，解决方案前面提过，换淘宝镜像。

第二类是权限问题，报EACCES错误，基本上是因为全局安装时没有权限，macOS/Linux 下用sudo或者先修复 npm 的全局目录权限，Windows 下用管理员身份的 PowerShell 执行。

第三类也是最阴间的：某些二进制依赖（node-sass、sharp等）下载预编译二进制文件失败，报错信息里往往出现ERR! node-pre-gyp或者python相关字样。这类问题没有一劳永逸的解法，通常是先删掉node_modules和 lock 文件重新装一遍，或者去搜对应包的中文 mirror 配置。

第四类是 Node 版本过高导致原生模块编译失败。这时候降 Node 版本（用 nvm）到项目要求的范围内，再重新 install，多半可以解决。

5.3 打包后布局异常

热词里有一条“vue 打包后布局异常”，这个现象非常典型：开发模式一切正常，npm run build之后部署上线，发现样式错乱了。原因九成出在静态资源路径和路由模式上。

Vite 打包后默认资源路径是绝对路径/assets/xxx，如果你的项目部署在服务器的子目录下（比如https://example.com/my-app/），就会找不到资源导致页面白屏或样式失效。对应的处理方式是在vite.config.js里配置base: './'，让资源以相对路径引用：

export default defineConfig({ base: './' })

另外，Vue Router 如果用了createWebHistory模式，打包后手动刷新子路由页面会 404，这是纯前端路由在静态服务器上的经典问题，解决办法要么改用createWebHashHistory，要么在后端配置路径重写，把未知路由都指向index.html。

5.4 其他高频问题速查表

除了这些，还有一类定位问题的方法值得分享：遇到任何报错，先看浏览器开发者工具（F12）的 Console 面板，再看到 Network 面板，判断是前端代码问题、资源加载问题还是接口请求问题。大多数前端运行报错都能通过这两步精准定位，不需要一上来就在搜索引擎里复制整段报错。

6. 一些进阶提升建议

到这里，用 VS Code 跑 Vue 项目已经基本跑顺了。如果你还愿意继续深入，下面这些方向大概率是你的下一步需求，也是论坛上大家问得比较多的话题。

6.1 路由传参和页面跳转

Vue Router 是 Vue 项目的核心依赖之一，热词里也有“vue路由”和“vue路由参数”。最常见的用法是：

// 跳转并携带参数 router.push({ path: '/detail', query: { id: 1 } }) router.push({ name: 'detail', params: { id: 1 } }) // 接收参数 const route = useRoute() console.log(route.query.id) console.log(route.params.id)

注意query用在path跳转，params必须配合name跳转，否则参数会丢失。这个坑新手经常踩，我也是反复吃亏之后才勉强形成了条件反射。

6.2 前后端分离项目联调

热词里“springboot vue前后端分离”“fastapi vue前后端分离”都指向同一件事：后端一个服务，前端一个服务，两边独立开发，通过接口通信。这种模式下，Vite 代理配置是连接两端的桥梁，把/api开头的请求转发到后端地址，前端开发时不需要关心后端跑在哪台机器，只留意代理配置正确即可。

另外，联调时建议前后端约定好统一的接口返回结构，比如：

{ "code": 0, "message": "success", "data": {} }

前端就能用统一的 axios 拦截器处理错误和加载状态，减少重复代码。这类约定看起来平常，但在真实项目里能让沟通成本大幅下降。

6.3 视频播放（m3u8）等场景

热词里出现“vue播放m3u8”，这属于 Vue 项目里的实际业务需求。m3u8 是 HLS 视频流协议的索引文件格式，前端播放通常用hls.js库：

npm install hls.js

在 Vue 组件里用：

<script setup> import Hls from 'hls.js' import { ref, onMounted } from 'vue' const videoRef = ref(null) onMounted(() => { const video = videoRef.value if (Hls.isSupported()) { const hls = new Hls() hls.loadSource('https://example.com/video/stream.m3u8') hls.attachMedia(video) } }) </script> <template> <video ref="videoRef" controls></video> </template>

这类业务功能与 VS Code 本身关系不大，但它提醒我们一件事：Vue 项目跑起来只是起点，后面真正考验人的是具体业务场景的集成能力。

写到这里，我觉得最重要的一个建议是：不要害怕尝试。项目跑不起来是常态，跑起来是幸事，每解决一个报错，你对这套工具链的理解就会深一层。VS Code 和 Vue 的组合之所以流行，正是因为配置门槛已经被降得很低了，剩下的只是你对命令、文件和错误信息的熟悉程度。常备一个能随时搜索的浏览器标签页，比背多少命令都实用。等到哪天你闭着眼就能完成从安装到启动的整条流程，你会觉得这一切都没什么难度——这本身就是进步的过程。