1. 先把话说清楚Vite 建 Vue3 项目到底解决了什么问题每次在群里看到有人问 vue3安装及环境配置怎么弄我基本都会回一句先别装一堆全局脚手架直接用 Vite 的官方模板起步。原因很简单Vue3 时代的官方推荐脚手架已经换成了 create-vue底层构建工具就是 Vite而不是过去的 webpack。你要做的只是敲一行命令剩下的路由、状态管理、TypeScript、ESLint 这些按需勾选就行。这件事看着门槛很低但真正把它落到一个能长期维护、能上生产、团队几个人并行开发不打架的工程里中间要做的判断其实不少。我写这篇东西的出发点是过去两年里陆陆续续带了几个 vue3后台管理系统 项目从零搭过也接手过别人搭的踩的坑五花八门。有的是 Node 版本不对导致依赖装不上有的是 vite build --mode test 打出来的包把测试环境接口带到了线上还有的是 pxtorem 配置了半天发现对 echarts 一点用没有。这些问题单独看都不大但凑在一起就足够让一个新人卡一整天。所以下面我按为什么这么选 → 环境怎么铺 → 项目怎么建 → 配置怎么写 → 工程化怎么补 → 出问题怎么查的顺序把整个流程摊开讲一遍。适合谁看如果你刚学 Vue3准备跟着 vue3官网 的文档走一遍但不确定工程该怎么搭这篇能当操作手册如果你是从 Vue2 转过来手里还留着 webpack 时代的配置习惯这篇能帮你把思路换过来如果你在做 vue3 可视化大屏 或者 uniapp vue2转vue3 这类改造前面几节的构建配置部分也能直接抄。我不打算写成 API 手册那种东西官网更全我更想讲的是当时为什么这么决定以及这么决定之后会有什么后果。先给一个整体判断Vite 的核心价值不在打包更快这四个字上而在于它把开发态和构建态彻底拆成了两套逻辑。开发态靠浏览器原生 ESM 加 esbuild 预构建启动时几乎不打包整个应用构建态才交给 Rollup 做完整的产物优化。理解这个前提后面很多配置项为什么长这样就有答案了。2. 环境准备Node 版本、包管理器与 Windows 上那些莫名其妙的报错2.1 Node 版本是第一道门槛别在这省事先说最容易翻车的地方。Vite 对 Node 版本是有硬性要求的而且这个大版本迭代得挺快。大致上 Vite 5 需要 Node 18 以上Vite 6 依旧要求 Node 18但到了 Vite 7 就要求 Node 20.19 或者 22.12。你在网上看到的教程时间不一样里面写的版本要求可能就对不上所以最靠谱的做法是去 Vite 官方文档看当前版本的 engines 字段而不是照抄某篇两年前的博客。具体怎么装我不建议直接去官网下 msi 装到系统里因为一个团队里往往同时维护着几个老项目需要不同 Node 版本。用 nvm-windows 或者 fnm 这类版本管理工具把 18、20、22 都装上切项目的时候nvm use 20一下就行。Linux 和 macOS 上 nvm 或者 fnm 更简单一条命令的事。注意切换 Node 版本之后务必把node_modules删掉重装。因为依赖预构建的缓存和原生模块比如 esbuild 的二进制是绑架构和版本编译的混着用会出现一些很难查的诡异错误。顺手把 npm 的镜像源配好这个不用多说。我一般还会在项目根目录放一个.npmrc把engine-stricttrue打开这样 Node 版本不对的时候安装阶段就直接报错比跑到一半崩掉好排查得多。2.2 包管理器怎么选npm、pnpm、yarn 的取舍create-vue 默认给你的是 npm 命令但实际项目里我基本都用 pnpm。原因有两个一是磁盘占用和安装速度pnpm 用硬链接共享依赖多个项目之间的重复依赖不会各存一份二是它的依赖结构更严格不会像 npm 那样把没声明的幽灵依赖提升到顶层这在团队协作里能提前暴露我用了没装的包这类问题。不过 pnpm 也有代价。有些老库对 node_modules 的目录结构有假设遇到的时候要么加.npmrc里的shamefully-hoisttrue要么直接换回 npm。所以我的建议是新项目用 pnpm接手的老项目、或者要跟 CI 环境保持一致的项目follow 现有约定别为了个人偏好把整个工程的锁文件换掉。这里有个细节pnpm 的锁文件是pnpm-lock.yamlnpm 是package-lock.jsonyarn 是yarn.lock。三者不要同时存在否则不同同事跑出来结果不一样这类问题排查起来特别费劲。团队里统一一个在 README 里写清楚。2.3 Windows 开发环境的几个经典坑windows vue3开发环境 相关的报错里出现频率最高的就是环境变量语法问题。比如你想给构建加内存照着网上 Linux 的写法敲了NODE_OPTIONS--max-old-space-size4096 vite结果 Windows 的 cmd 直接告诉你这个命令不认识。原因是 cmd 的变量赋值语法是set NODE_OPTIONSxxxPowerShell 又是$env:NODE_OPTIONSxxx各不相同。解决办法有三条路按推荐顺序排装cross-env在package.json的 scripts 里写成cross-env NODE_OPTIONS--max-old-space-size4096 vite跨平台通用这是最省心的在 Windows 的系统属性 → 环境变量里加一条用户变量一次配置永久生效但会影响机器上所有项目用.env文件配合dotenv或者 Vite 自己的 env 机制不过NODE_OPTIONS这类 Node 进程参数不适合走.env还是前两种更合适。还有一个 vscode vite 组合下的细节VS Code 的集成终端默认可能是 PowerShell而外面教程大多是 bash 语法。建议在设置里把默认终端改成 Git Bash 或者 WSL脚本类命令能少踩一半的坑。另外 VS Code 装 Volar现在叫 Vue - Official扩展把旧的 Vetur 卸掉两者的模板语法提示会打架。3. 从零创建项目create-vue 的交互式选项逐个拆3.1 一条命令背后的选择逻辑现在官方推荐的方式是npm create vuelatest跟着交互提示走。它会依次问你项目名、是否用 TypeScript、是否加 JSX 支持、要不要 Vue Router、要不要 Pinia、要不要 Vitest 单元测试、要不要端到端测试方案、要不要 ESLint、要不要 Prettier。这些选项不是随便勾的每一条都会往工程里塞一批文件和依赖事后想删比事前想清楚麻烦。我的一般组合是这样TypeScript 开JSX 看情况做通用组件库或者要写渲染函数的时候开纯业务项目可以不开Router 和 Pinia 开ESLint 和 Prettier 开测试先不开——等业务定型了再补不然早期接口天天变测试写了一堆天天改性价比很低。关于 vue3使用jsx 这件事单独说一句。Vue3 的模板能力已经很强了绝大多数业务页面用模板更直观出了问题堆栈也更好读。JSX 的优势在于写高阶组件、动态渲染、以及要把 h 函数写得比较复杂的时候可读性会好很多。我的用法是两者混着模板为主遇到需要高度抽象的表格列渲染之类的场景再用 JSX不做非此即彼的选择。创建完之后进目录npm install。装依赖这一步如果卡住八成是网络问题或者 registry 配置问题先确认源再确认代理设置公司内网环境经常有这个问题最后才怀疑依赖本身。3.2 目录结构看一眼就知道怎么长生成出来的骨架大致长这样my-vue-app/ ├── public/ # 原样拷贝的静态资源不参与构建处理 ├── src/ │ ├── assets/ # 参与构建的资源会被哈希改名 │ ├── components/ # 通用组件 │ ├── router/ # 路由配置 │ ├── stores/ # Pinia 状态 │ ├── views/ # 页面级组件 │ ├── App.vue │ └── main.ts ├── index.html # 真正的入口 HTML ├── vite.config.ts ├── tsconfig.json ├── tsconfig.app.json ├── tsconfig.node.json ├── env.d.ts └── package.json这里有个和 webpack 时代很不一样的点index.html在项目根目录而且它是构建的真正入口。Vite 会解析这个 HTML找到里面script typemodule src/src/main.ts这样的标签然后从那里开始构建。webpack 时代的public/index.html只是模板两种思路差别挺大。理解这一点之后你就能明白为什么改base的时候有人会去动 HTML 里的路径其实大部分时候不需要。public和src/assets的区别值得单独强调public里的文件会被原封不动复制到产物根目录不哈希、不压缩、不做任何处理所以适合放 favicon、robots.txt、以及那些必须在运行时按固定路径访问的文件src/assets里的文件会被构建管道处理小图会被内联成 base64大文件会带哈希后缀输出适合业务里引用的图片。放错位置最常见的后果就是——本地跑得好好的打包之后图片 404。3.3 TS 的配置文件为什么被拆成三个create-vue 生成的是三份 tsconfig根目录那份基本只做引用tsconfig.app.json管 src 下的业务代码tsconfig.node.json管vite.config.ts这类跑在 Node 环境里的文件。拆开的原因是这两类代码的运行时环境完全不同一个是浏览器一个是 Node类型库也不一样。混在一起写你会在vite.config.ts里莫名其妙拿到 DOM 的类型提示或者在业务代码里能用上process而实际上跑起来会报错。顺带提一个 vue3面试题 里经常出现的点env.d.ts里那句/// reference typesvite/client /是干什么的它把 Vite 提供的客户端类型比如import.meta.env的声明、静态资源导入的类型注入到 TS 环境里没有它你在 TS 里 import 一个.vue文件就会报找不到模块。4. 配置文件精讲vite.config.ts 里每一项为什么要这么写4.1 别名 alias不只是少写几个点路径别名几乎是每个项目的标配。写起来是这样import { 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)) } } })用fileURLToPath(new URL(...))而不是path.resolve(__dirname, ./src)是因为后者在 ESM 环境下__dirname根本不存在。create-vue 生成的就是这种写法直接抄过来最稳。但光配 Vite 还不够TypeScript 需要单独知道这个别名的映射关系否则编辑器里 import 会标红。要在tsconfig.app.json的compilerOptions里加{ compilerOptions: { baseUrl: ., paths: { /*: [./src/*] } } }这里踩过的坑是改完 tsconfig 有时候编辑器不生效需要重启 TS 服务VS Code 里是命令面板执行TypeScript: Restart TS Server。很多人以为是配置写错了其实只是缓存。4.2 server 配置本地开发和跨域代理开发服务器的配置看着简单但每一项都有实际用途export default defineConfig({ server: { host: 0.0.0.0, port: 5173, open: true, proxy: { /api: { target: http://192.168.1.100:8080, changeOrigin: true, rewrite: path path.replace(/^\/api/, ) } } } })host: 0.0.0.0是为了让局域网内其他设备手机、平板能访问你的开发服务做移动端适配或者 vue3 可视化大屏 投屏调试的时候必备。默认只监听 localhost手机连不上很多人第一反应是防火墙问题其实是这里没开。changeOrigin: true的作用是修改请求头里的 Host 字段让它和目标服务器的域名一致。不加这个某些后端尤其是上了 Nginx 或者网关的会因为 Host 不匹配直接返回 403 或者空响应现象是接口一直转圈或者 404特别迷惑。rewrite是否需要取决于后端接口本身带不带/api前缀。如果后端本身就是/api/user/list那就不需要 rewrite如果后端是/user/list而你前端想统一加个/api前缀方便走网关那就需要 rewrite 去掉。这个搞反了就会出现本地代理配了但接口还是 404。还有一点代理只在开发服务器生效。打包出来的静态文件是浏览器直连后端地址的所以生产环境的跨域要靠后端配置或者 Nginx 反向代理解决不能指望 Vite 的 proxy。4.3 构建配置base、分包和产物检查构建这块我实际项目里改动最多的是三处。第一处是base。如果你的应用部署在子路径下比如https://example.com/admin/必须把 base 设成/admin/否则打包出来的 JS、CSS 引用路径会从根目录开始找直接白屏。这个问题的表现是控制台报一堆 404然后冒出一个Uncaught SyntaxError: Invalid or unexpected token或者说模块加载失败。很多人看到这个报错第一反应是代码有语法错误其实压根不是是资源根本没加载到。第二处是分包。默认情况下 Vite 会把所有 node_modules 里的东西打成一个 vendor 包业务越大这个包越肥首屏加载很吃亏。我的做法是按需手动切build: { chunkSizeWarningLimit: 1500, rollupOptions: { output: { manualChunks: { vue-vendor: [vue, vue-router, pinia], ui-vendor: [element-plus], chart-vendor: [echarts] } } } }把 Vue 全家桶、UI 库、图表库各自拆开的好处是它们更新频率完全不同。业务代码天天改Vue 版本几个月才动一次拆开之后用户浏览器能长期缓存前者只需要重新下载业务包。对于 vue3后台管理系统 这类需要长期迭代的项目这个优化收益很直接。第三处是build.target。默认值已经比较激进了如果你的用户群里还有老版本浏览器需要手动降级。不过大多数面向内部的管理系统直接用默认值就行为了一小撮旧设备牺牲现代语法优化不划算。4.4 环境变量.env 体系与 --mode test 的正确玩法环境变量这块是出错重灾区我把规则说细一点。Vite 只暴露以VITE_开头的变量给客户端代码其他的即使写在.env里也不会被import.meta.env读到。这个设计是防止你无意中把数据库密码这种服务端配置打进前端产物里。文件加载优先级从高到低是.env.[mode].local→.env.[mode]→.env.local→.env。mode 由启动命令决定vite默认是 developmentvite build默认是 productionvite build --mode test就是加载.env.test。一个典型的.env.test长这样VITE_APP_TITLE后台管理系统测试环境 VITE_API_BASE_URLhttps://test-api.example.com VITE_ENABLE_MOCKtrue然后package.json里加一条{ scripts: { dev: vite, build: vue-tsc --noEmit vite build, build:test: vue-tsc --noEmit vite build --mode test, preview: vite preview } }我踩过的最典型的一个坑.env.test写了build:test也跑了但打出来的包连的还是线上接口。查了半天发现是请求封装那里写死了 baseURL根本没读import.meta.env.VITE_API_BASE_URL。所以环境变量配完一定要在代码里实际用上并且每次加新变量都在.env、.env.development、.env.test、.env.production四个文件里同步声明缺一个就会出现某个环境取到 undefined然后请求发到undefined/api/user这种地址。另外提醒一句import.meta.env是在构建时被静态替换的不是运行时读取。所以不能写import.meta.env[VITE_ name]这种动态拼接构建时替换不了会变成 undefined。5. 工程化补强路由、状态、请求和 UI 库怎么接进来5.1 Router 与 Pinia 的接入姿势create-vue 勾选了 Router 和 Pinia 之后骨架里已经有基础配置了。Router 用的是createWebHistory也就是 HTML5 History 模式URL 干净但需要服务端配置 fallback——所有找不到的路径都返回 index.html否则用户刷新页面会 404。这个不是前端能解决的部署的时候要跟运维说清楚。关于 vue3 路由跳转后组件内容不渲染 这个高频问题八成是两种情况之一一是router-view放在了错误的位置比如放在了transition外面同时又嵌套了v-if二是动态添加路由之后忘了调用router.replace或者跳转时机早于路由注册完成。我的经验是把动态路由的注册放在路由守卫里登录后拿到权限菜单再addRoute注册完立刻next({ ...to, replace: true })重新触发一次导航这样就不会出现地址变了但页面还是旧的。Pinia 这边我建议按业务域拆 store而不是搞一个大而全的全局 store。另外setup写法的 store 比options写法在类型推导上更顺尤其配合 TypeScript 的时候。一个常见误区是把接口请求写在 store 里——不是不行但会让 store 变得很重我一般只在 store 里管状态和少量同步逻辑异步请求放在单独的 api 层store 提供 action 去调用。5.2 请求层封装统一错误处理和取消重复请求axios 封装我见过太多版本了这里只说我认为必要的三件事。第一件是统一响应拦截。后端返回的格式通常是{ code, data, message }在拦截器里判断 code非成功状态统一弹提示并 reject业务代码就不用每个请求都写一遍判断。第二件是取消重复请求。用户手快连点两次提交按钮就会发两个一样的请求。实现方式是用AbortController或者 axios 的CancelToken新版本推荐前者在请求拦截器里按方法 URL 参数生成 key存在 Map 里重复的直接取消。第三件是 loading 的粒度控制。全局 loading 用起来爽但两个请求并发的时候先返回的那个会把 loading 关掉视觉上会闪。我一般给请求配置加一个silent标记需要安静的请求不触发全局 loading。顺带说个数据流上的老问题vue3 props 赋值给 data 这件事在组合式 API 里其实是不推荐的。props 是响应式的只读引用直接const local props.value会丢掉响应性。想要基于 props 派生本地状态正确做法是用computed做只读派生或者用watch监听 props 变化同步到本地 ref。如果是想把 props 当初始值、之后独立变化那要明确知道这是一次性拷贝后续 props 变了本地不会跟着变这个语义要跟调用方约定清楚。5.3 UI 库按需引入与移动端适配的坑后台项目我最常用的是 Element Plus可视化大屏会用 ECharts 加一些自定义组件。按需引入现在基本靠unplugin-vue-components和unplugin-auto-import这两个插件自动做不用手动 import 组件和样式。配置写在vite.config.ts的 plugins 里就行注意生成的两个 d.ts 文件components.d.ts、auto-imports.d.ts要提交到仓库不然同事拉下来编辑器会一片红。现在说一个很多人都会遇到的坑pxtorem 对 echarts 没起到效果。原因是 postcss-pxtorem 处理的是 CSS 里的 px 值而 ECharts 的图表是在 canvas 里绘制的它读取的是你用 JS 传进去的数字这些数字根本不经过 PostCSS 管道。所以你在 CSS 里写font-size: 14px会被转成 rem但textStyle: { fontSize: 14 }就纹丝不动。解决办法是在 JS 里手动做转换写一个工具函数按当前根字号把设计稿 px 换算成实际需要的值或者干脆用 ECharts 自己的适配思路——监听容器尺寸变化用chart.resize()重绘。对于 vue3 可视化大屏 场景我其实更推荐整体用transform: scale()做等比缩放比 rem 方案心智负担小也不用担心 canvas 里的 px 不转换。两种方案各有取舍scale 方案在超宽屏上会有黑边rem 方案则要处理字体最小值的限制。5.4 一些容易被忽略的样式和交互细节vue3修改 tabs 标签页样式 这种需求通常是因为用了组件库的 Tabs 但设计稿对不上。方法是加一个自定义 class然后用:deep()穿透style scoped .custom-tabs :deep(.el-tabs__item) { height: 40px; line-height: 40px; font-size: 14px; } .custom-tabs :deep(.el-tabs__active-bar) { height: 3px; border-radius: 2px; } /style不加:deep()而直接写选择器是无效的因为 scoped 会给每个选择器加上 data 属性而组件库内部元素的 data 属性和你的组件不是同一个。这个坑几乎所有刚上手 Vue3 的人都踩过。还有 vue3 shouhide 动画这类需求推荐用内置的Transition组件配合 CSS 类名别自己用 JS 去改display因为display: none不参与过渡会直接跳变。如果要处理高度不确定的折叠展开Transition配合max-height或者用 JS 钩子函数读取scrollHeight动态设置高度后者更精确但要处理内容变化的情况。6. 常见问题与排查技巧实录6.1 启动和构建阶段的报错速查下面这张表是我这两年记下来的高频问题和定位思路基本覆盖了日常能碰到的八成情况。现象大概率原因排查动作启动时提示 Node 版本不符Node 低于当前 Vite 要求node -v确认切到 20.19 或 22.12依赖装完后启动报找不到某个包幽灵依赖或锁文件混用删 node_modules 和锁文件重装统一包管理器打包产物部署后白屏控制台一堆 404base 没配或者配错检查base检查 index.html 里的资源引用Uncaught SyntaxError: Invalid or unexpected token资源路径错误加载到了 HTML 内容或字符编码问题打开 Network 看这个 JS 的实际响应体是不是 HTML构建到一半 Node 堆内存溢出项目太大或者依赖循环提高 max-old-space-size同时查循环依赖修改代码后页面不热更新HMR 断开或文件被忽略重启 dev server检查是否在项目根目录外类型提示正常但构建报 TS 错误vue-tsc 和编辑器用了不同的 tsconfig检查tsconfig.app.json的 include 范围重点说第二条。幽灵依赖这个事情用 npm 的时候很难发现因为你 import 了一个没在 dependencies 里声明的包只要它是别的包的间接依赖被提升到顶层了本地跑起来照样正常。但换到 pnpm 或者换了依赖树之后就炸了。判断方法很简单把 node_modules 删掉用 pnpm 重装一遍立刻就会暴露出来。6.2 内存溢出怎么处理才对前端项目跑到 OOM一般是几个原因叠加依赖太多导致依赖预构建阶段吃掉大量内存、业务代码里存在循环引用、或者 sourcemap 生成时占用过高。处理顺序我建议这样先在脚本里加cross-env NODE_OPTIONS--max-old-space-size4096把上限拉到 4G这是最快见效的。如果拉完还是不行说明不是内存上限的问题而是真的有东西在无限增长。这时候去查循环依赖用madge这类工具扫一下或者把build.sourcemap临时关掉看是否还崩。另外optimizeDeps.include手动把大依赖比如 echarts、mapbox-gl声明进去能减少预构建阶段的反复扫描。vue3 mapboxgl 这类地图库体积特别大还经常带 worker 文件构建时分包和 worker 的处理要单独配。我的做法是把地图库整体拆成一个独立 chunk用动态 import 延迟加载首屏基本感受不到它的存在。6.3 浏览器差异和一些玄学问题有些问题确实不是代码的锅。比如 vue3项目在 Edge 浏览器里有时候无法关闭右上角的最小化按钮——这个东西是浏览器自身的窗口 UI网页层根本控制不了遇到这种反馈我会先确认对方是不是把浏览器窗口的按钮和页面内的自定义按钮搞混了。类似地某些快捷键比如 CtrlW在浏览器里被保留前端也拦不住。还有一类是 uniapp vue2转vue3 过程中特有的Vue2 的选项式 API 里this.$refs、this.$nextTick用得很顺手转到组合式 API 之后这些都没了需要换成ref和nextTick显式导入。这个迁移不是简单改语法是要把依赖 this 上下文的思维换成显式依赖的思维。刚开始别扭用久了会发现类型推导和逻辑复用的体验好很多。diff 算法层面 Vue3 也做了重写编译期会标记动态节点运行时只对比变化的部分长列表渲染的优化比 Vue2 明显但这属于框架内部的收益业务代码不需要为此做额外工作。最后提一个部署上很容易忽略的点vite preview只是本地预览构建产物用的简易静态服务不能拿来当生产服务器。它没有缓存策略、没有 gzip、没有并发优化用它跑生产会被人投诉。正经做法是把dist目录交给 Nginx 或者 CDN配置好缓存头和 history fallback才算完整交付。我个人在实际操作中的体会是Vite 把搭建 Vue3 项目的门槛降得很低但它把复杂度转移到了配置理解上——默认配置能跑通一个 demo但要跑好一个真实项目你得知道base、proxy、manualChunks、env这几项分别在什么情况下要动。我习惯的做法是每接一个新项目先花半小时把vite.config.ts从头读一遍把它当成一份项目说明书比看任何 README 都快。
Vite 创建 Vue3 项目：环境配置、工程化与避坑指南
1. 先把话说清楚Vite 建 Vue3 项目到底解决了什么问题每次在群里看到有人问 vue3安装及环境配置怎么弄我基本都会回一句先别装一堆全局脚手架直接用 Vite 的官方模板起步。原因很简单Vue3 时代的官方推荐脚手架已经换成了 create-vue底层构建工具就是 Vite而不是过去的 webpack。你要做的只是敲一行命令剩下的路由、状态管理、TypeScript、ESLint 这些按需勾选就行。这件事看着门槛很低但真正把它落到一个能长期维护、能上生产、团队几个人并行开发不打架的工程里中间要做的判断其实不少。我写这篇东西的出发点是过去两年里陆陆续续带了几个 vue3后台管理系统 项目从零搭过也接手过别人搭的踩的坑五花八门。有的是 Node 版本不对导致依赖装不上有的是 vite build --mode test 打出来的包把测试环境接口带到了线上还有的是 pxtorem 配置了半天发现对 echarts 一点用没有。这些问题单独看都不大但凑在一起就足够让一个新人卡一整天。所以下面我按为什么这么选 → 环境怎么铺 → 项目怎么建 → 配置怎么写 → 工程化怎么补 → 出问题怎么查的顺序把整个流程摊开讲一遍。适合谁看如果你刚学 Vue3准备跟着 vue3官网 的文档走一遍但不确定工程该怎么搭这篇能当操作手册如果你是从 Vue2 转过来手里还留着 webpack 时代的配置习惯这篇能帮你把思路换过来如果你在做 vue3 可视化大屏 或者 uniapp vue2转vue3 这类改造前面几节的构建配置部分也能直接抄。我不打算写成 API 手册那种东西官网更全我更想讲的是当时为什么这么决定以及这么决定之后会有什么后果。先给一个整体判断Vite 的核心价值不在打包更快这四个字上而在于它把开发态和构建态彻底拆成了两套逻辑。开发态靠浏览器原生 ESM 加 esbuild 预构建启动时几乎不打包整个应用构建态才交给 Rollup 做完整的产物优化。理解这个前提后面很多配置项为什么长这样就有答案了。2. 环境准备Node 版本、包管理器与 Windows 上那些莫名其妙的报错2.1 Node 版本是第一道门槛别在这省事先说最容易翻车的地方。Vite 对 Node 版本是有硬性要求的而且这个大版本迭代得挺快。大致上 Vite 5 需要 Node 18 以上Vite 6 依旧要求 Node 18但到了 Vite 7 就要求 Node 20.19 或者 22.12。你在网上看到的教程时间不一样里面写的版本要求可能就对不上所以最靠谱的做法是去 Vite 官方文档看当前版本的 engines 字段而不是照抄某篇两年前的博客。具体怎么装我不建议直接去官网下 msi 装到系统里因为一个团队里往往同时维护着几个老项目需要不同 Node 版本。用 nvm-windows 或者 fnm 这类版本管理工具把 18、20、22 都装上切项目的时候nvm use 20一下就行。Linux 和 macOS 上 nvm 或者 fnm 更简单一条命令的事。注意切换 Node 版本之后务必把node_modules删掉重装。因为依赖预构建的缓存和原生模块比如 esbuild 的二进制是绑架构和版本编译的混着用会出现一些很难查的诡异错误。顺手把 npm 的镜像源配好这个不用多说。我一般还会在项目根目录放一个.npmrc把engine-stricttrue打开这样 Node 版本不对的时候安装阶段就直接报错比跑到一半崩掉好排查得多。2.2 包管理器怎么选npm、pnpm、yarn 的取舍create-vue 默认给你的是 npm 命令但实际项目里我基本都用 pnpm。原因有两个一是磁盘占用和安装速度pnpm 用硬链接共享依赖多个项目之间的重复依赖不会各存一份二是它的依赖结构更严格不会像 npm 那样把没声明的幽灵依赖提升到顶层这在团队协作里能提前暴露我用了没装的包这类问题。不过 pnpm 也有代价。有些老库对 node_modules 的目录结构有假设遇到的时候要么加.npmrc里的shamefully-hoisttrue要么直接换回 npm。所以我的建议是新项目用 pnpm接手的老项目、或者要跟 CI 环境保持一致的项目follow 现有约定别为了个人偏好把整个工程的锁文件换掉。这里有个细节pnpm 的锁文件是pnpm-lock.yamlnpm 是package-lock.jsonyarn 是yarn.lock。三者不要同时存在否则不同同事跑出来结果不一样这类问题排查起来特别费劲。团队里统一一个在 README 里写清楚。2.3 Windows 开发环境的几个经典坑windows vue3开发环境 相关的报错里出现频率最高的就是环境变量语法问题。比如你想给构建加内存照着网上 Linux 的写法敲了NODE_OPTIONS--max-old-space-size4096 vite结果 Windows 的 cmd 直接告诉你这个命令不认识。原因是 cmd 的变量赋值语法是set NODE_OPTIONSxxxPowerShell 又是$env:NODE_OPTIONSxxx各不相同。解决办法有三条路按推荐顺序排装cross-env在package.json的 scripts 里写成cross-env NODE_OPTIONS--max-old-space-size4096 vite跨平台通用这是最省心的在 Windows 的系统属性 → 环境变量里加一条用户变量一次配置永久生效但会影响机器上所有项目用.env文件配合dotenv或者 Vite 自己的 env 机制不过NODE_OPTIONS这类 Node 进程参数不适合走.env还是前两种更合适。还有一个 vscode vite 组合下的细节VS Code 的集成终端默认可能是 PowerShell而外面教程大多是 bash 语法。建议在设置里把默认终端改成 Git Bash 或者 WSL脚本类命令能少踩一半的坑。另外 VS Code 装 Volar现在叫 Vue - Official扩展把旧的 Vetur 卸掉两者的模板语法提示会打架。3. 从零创建项目create-vue 的交互式选项逐个拆3.1 一条命令背后的选择逻辑现在官方推荐的方式是npm create vuelatest跟着交互提示走。它会依次问你项目名、是否用 TypeScript、是否加 JSX 支持、要不要 Vue Router、要不要 Pinia、要不要 Vitest 单元测试、要不要端到端测试方案、要不要 ESLint、要不要 Prettier。这些选项不是随便勾的每一条都会往工程里塞一批文件和依赖事后想删比事前想清楚麻烦。我的一般组合是这样TypeScript 开JSX 看情况做通用组件库或者要写渲染函数的时候开纯业务项目可以不开Router 和 Pinia 开ESLint 和 Prettier 开测试先不开——等业务定型了再补不然早期接口天天变测试写了一堆天天改性价比很低。关于 vue3使用jsx 这件事单独说一句。Vue3 的模板能力已经很强了绝大多数业务页面用模板更直观出了问题堆栈也更好读。JSX 的优势在于写高阶组件、动态渲染、以及要把 h 函数写得比较复杂的时候可读性会好很多。我的用法是两者混着模板为主遇到需要高度抽象的表格列渲染之类的场景再用 JSX不做非此即彼的选择。创建完之后进目录npm install。装依赖这一步如果卡住八成是网络问题或者 registry 配置问题先确认源再确认代理设置公司内网环境经常有这个问题最后才怀疑依赖本身。3.2 目录结构看一眼就知道怎么长生成出来的骨架大致长这样my-vue-app/ ├── public/ # 原样拷贝的静态资源不参与构建处理 ├── src/ │ ├── assets/ # 参与构建的资源会被哈希改名 │ ├── components/ # 通用组件 │ ├── router/ # 路由配置 │ ├── stores/ # Pinia 状态 │ ├── views/ # 页面级组件 │ ├── App.vue │ └── main.ts ├── index.html # 真正的入口 HTML ├── vite.config.ts ├── tsconfig.json ├── tsconfig.app.json ├── tsconfig.node.json ├── env.d.ts └── package.json这里有个和 webpack 时代很不一样的点index.html在项目根目录而且它是构建的真正入口。Vite 会解析这个 HTML找到里面script typemodule src/src/main.ts这样的标签然后从那里开始构建。webpack 时代的public/index.html只是模板两种思路差别挺大。理解这一点之后你就能明白为什么改base的时候有人会去动 HTML 里的路径其实大部分时候不需要。public和src/assets的区别值得单独强调public里的文件会被原封不动复制到产物根目录不哈希、不压缩、不做任何处理所以适合放 favicon、robots.txt、以及那些必须在运行时按固定路径访问的文件src/assets里的文件会被构建管道处理小图会被内联成 base64大文件会带哈希后缀输出适合业务里引用的图片。放错位置最常见的后果就是——本地跑得好好的打包之后图片 404。3.3 TS 的配置文件为什么被拆成三个create-vue 生成的是三份 tsconfig根目录那份基本只做引用tsconfig.app.json管 src 下的业务代码tsconfig.node.json管vite.config.ts这类跑在 Node 环境里的文件。拆开的原因是这两类代码的运行时环境完全不同一个是浏览器一个是 Node类型库也不一样。混在一起写你会在vite.config.ts里莫名其妙拿到 DOM 的类型提示或者在业务代码里能用上process而实际上跑起来会报错。顺带提一个 vue3面试题 里经常出现的点env.d.ts里那句/// reference typesvite/client /是干什么的它把 Vite 提供的客户端类型比如import.meta.env的声明、静态资源导入的类型注入到 TS 环境里没有它你在 TS 里 import 一个.vue文件就会报找不到模块。4. 配置文件精讲vite.config.ts 里每一项为什么要这么写4.1 别名 alias不只是少写几个点路径别名几乎是每个项目的标配。写起来是这样import { 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)) } } })用fileURLToPath(new URL(...))而不是path.resolve(__dirname, ./src)是因为后者在 ESM 环境下__dirname根本不存在。create-vue 生成的就是这种写法直接抄过来最稳。但光配 Vite 还不够TypeScript 需要单独知道这个别名的映射关系否则编辑器里 import 会标红。要在tsconfig.app.json的compilerOptions里加{ compilerOptions: { baseUrl: ., paths: { /*: [./src/*] } } }这里踩过的坑是改完 tsconfig 有时候编辑器不生效需要重启 TS 服务VS Code 里是命令面板执行TypeScript: Restart TS Server。很多人以为是配置写错了其实只是缓存。4.2 server 配置本地开发和跨域代理开发服务器的配置看着简单但每一项都有实际用途export default defineConfig({ server: { host: 0.0.0.0, port: 5173, open: true, proxy: { /api: { target: http://192.168.1.100:8080, changeOrigin: true, rewrite: path path.replace(/^\/api/, ) } } } })host: 0.0.0.0是为了让局域网内其他设备手机、平板能访问你的开发服务做移动端适配或者 vue3 可视化大屏 投屏调试的时候必备。默认只监听 localhost手机连不上很多人第一反应是防火墙问题其实是这里没开。changeOrigin: true的作用是修改请求头里的 Host 字段让它和目标服务器的域名一致。不加这个某些后端尤其是上了 Nginx 或者网关的会因为 Host 不匹配直接返回 403 或者空响应现象是接口一直转圈或者 404特别迷惑。rewrite是否需要取决于后端接口本身带不带/api前缀。如果后端本身就是/api/user/list那就不需要 rewrite如果后端是/user/list而你前端想统一加个/api前缀方便走网关那就需要 rewrite 去掉。这个搞反了就会出现本地代理配了但接口还是 404。还有一点代理只在开发服务器生效。打包出来的静态文件是浏览器直连后端地址的所以生产环境的跨域要靠后端配置或者 Nginx 反向代理解决不能指望 Vite 的 proxy。4.3 构建配置base、分包和产物检查构建这块我实际项目里改动最多的是三处。第一处是base。如果你的应用部署在子路径下比如https://example.com/admin/必须把 base 设成/admin/否则打包出来的 JS、CSS 引用路径会从根目录开始找直接白屏。这个问题的表现是控制台报一堆 404然后冒出一个Uncaught SyntaxError: Invalid or unexpected token或者说模块加载失败。很多人看到这个报错第一反应是代码有语法错误其实压根不是是资源根本没加载到。第二处是分包。默认情况下 Vite 会把所有 node_modules 里的东西打成一个 vendor 包业务越大这个包越肥首屏加载很吃亏。我的做法是按需手动切build: { chunkSizeWarningLimit: 1500, rollupOptions: { output: { manualChunks: { vue-vendor: [vue, vue-router, pinia], ui-vendor: [element-plus], chart-vendor: [echarts] } } } }把 Vue 全家桶、UI 库、图表库各自拆开的好处是它们更新频率完全不同。业务代码天天改Vue 版本几个月才动一次拆开之后用户浏览器能长期缓存前者只需要重新下载业务包。对于 vue3后台管理系统 这类需要长期迭代的项目这个优化收益很直接。第三处是build.target。默认值已经比较激进了如果你的用户群里还有老版本浏览器需要手动降级。不过大多数面向内部的管理系统直接用默认值就行为了一小撮旧设备牺牲现代语法优化不划算。4.4 环境变量.env 体系与 --mode test 的正确玩法环境变量这块是出错重灾区我把规则说细一点。Vite 只暴露以VITE_开头的变量给客户端代码其他的即使写在.env里也不会被import.meta.env读到。这个设计是防止你无意中把数据库密码这种服务端配置打进前端产物里。文件加载优先级从高到低是.env.[mode].local→.env.[mode]→.env.local→.env。mode 由启动命令决定vite默认是 developmentvite build默认是 productionvite build --mode test就是加载.env.test。一个典型的.env.test长这样VITE_APP_TITLE后台管理系统测试环境 VITE_API_BASE_URLhttps://test-api.example.com VITE_ENABLE_MOCKtrue然后package.json里加一条{ scripts: { dev: vite, build: vue-tsc --noEmit vite build, build:test: vue-tsc --noEmit vite build --mode test, preview: vite preview } }我踩过的最典型的一个坑.env.test写了build:test也跑了但打出来的包连的还是线上接口。查了半天发现是请求封装那里写死了 baseURL根本没读import.meta.env.VITE_API_BASE_URL。所以环境变量配完一定要在代码里实际用上并且每次加新变量都在.env、.env.development、.env.test、.env.production四个文件里同步声明缺一个就会出现某个环境取到 undefined然后请求发到undefined/api/user这种地址。另外提醒一句import.meta.env是在构建时被静态替换的不是运行时读取。所以不能写import.meta.env[VITE_ name]这种动态拼接构建时替换不了会变成 undefined。5. 工程化补强路由、状态、请求和 UI 库怎么接进来5.1 Router 与 Pinia 的接入姿势create-vue 勾选了 Router 和 Pinia 之后骨架里已经有基础配置了。Router 用的是createWebHistory也就是 HTML5 History 模式URL 干净但需要服务端配置 fallback——所有找不到的路径都返回 index.html否则用户刷新页面会 404。这个不是前端能解决的部署的时候要跟运维说清楚。关于 vue3 路由跳转后组件内容不渲染 这个高频问题八成是两种情况之一一是router-view放在了错误的位置比如放在了transition外面同时又嵌套了v-if二是动态添加路由之后忘了调用router.replace或者跳转时机早于路由注册完成。我的经验是把动态路由的注册放在路由守卫里登录后拿到权限菜单再addRoute注册完立刻next({ ...to, replace: true })重新触发一次导航这样就不会出现地址变了但页面还是旧的。Pinia 这边我建议按业务域拆 store而不是搞一个大而全的全局 store。另外setup写法的 store 比options写法在类型推导上更顺尤其配合 TypeScript 的时候。一个常见误区是把接口请求写在 store 里——不是不行但会让 store 变得很重我一般只在 store 里管状态和少量同步逻辑异步请求放在单独的 api 层store 提供 action 去调用。5.2 请求层封装统一错误处理和取消重复请求axios 封装我见过太多版本了这里只说我认为必要的三件事。第一件是统一响应拦截。后端返回的格式通常是{ code, data, message }在拦截器里判断 code非成功状态统一弹提示并 reject业务代码就不用每个请求都写一遍判断。第二件是取消重复请求。用户手快连点两次提交按钮就会发两个一样的请求。实现方式是用AbortController或者 axios 的CancelToken新版本推荐前者在请求拦截器里按方法 URL 参数生成 key存在 Map 里重复的直接取消。第三件是 loading 的粒度控制。全局 loading 用起来爽但两个请求并发的时候先返回的那个会把 loading 关掉视觉上会闪。我一般给请求配置加一个silent标记需要安静的请求不触发全局 loading。顺带说个数据流上的老问题vue3 props 赋值给 data 这件事在组合式 API 里其实是不推荐的。props 是响应式的只读引用直接const local props.value会丢掉响应性。想要基于 props 派生本地状态正确做法是用computed做只读派生或者用watch监听 props 变化同步到本地 ref。如果是想把 props 当初始值、之后独立变化那要明确知道这是一次性拷贝后续 props 变了本地不会跟着变这个语义要跟调用方约定清楚。5.3 UI 库按需引入与移动端适配的坑后台项目我最常用的是 Element Plus可视化大屏会用 ECharts 加一些自定义组件。按需引入现在基本靠unplugin-vue-components和unplugin-auto-import这两个插件自动做不用手动 import 组件和样式。配置写在vite.config.ts的 plugins 里就行注意生成的两个 d.ts 文件components.d.ts、auto-imports.d.ts要提交到仓库不然同事拉下来编辑器会一片红。现在说一个很多人都会遇到的坑pxtorem 对 echarts 没起到效果。原因是 postcss-pxtorem 处理的是 CSS 里的 px 值而 ECharts 的图表是在 canvas 里绘制的它读取的是你用 JS 传进去的数字这些数字根本不经过 PostCSS 管道。所以你在 CSS 里写font-size: 14px会被转成 rem但textStyle: { fontSize: 14 }就纹丝不动。解决办法是在 JS 里手动做转换写一个工具函数按当前根字号把设计稿 px 换算成实际需要的值或者干脆用 ECharts 自己的适配思路——监听容器尺寸变化用chart.resize()重绘。对于 vue3 可视化大屏 场景我其实更推荐整体用transform: scale()做等比缩放比 rem 方案心智负担小也不用担心 canvas 里的 px 不转换。两种方案各有取舍scale 方案在超宽屏上会有黑边rem 方案则要处理字体最小值的限制。5.4 一些容易被忽略的样式和交互细节vue3修改 tabs 标签页样式 这种需求通常是因为用了组件库的 Tabs 但设计稿对不上。方法是加一个自定义 class然后用:deep()穿透style scoped .custom-tabs :deep(.el-tabs__item) { height: 40px; line-height: 40px; font-size: 14px; } .custom-tabs :deep(.el-tabs__active-bar) { height: 3px; border-radius: 2px; } /style不加:deep()而直接写选择器是无效的因为 scoped 会给每个选择器加上 data 属性而组件库内部元素的 data 属性和你的组件不是同一个。这个坑几乎所有刚上手 Vue3 的人都踩过。还有 vue3 shouhide 动画这类需求推荐用内置的Transition组件配合 CSS 类名别自己用 JS 去改display因为display: none不参与过渡会直接跳变。如果要处理高度不确定的折叠展开Transition配合max-height或者用 JS 钩子函数读取scrollHeight动态设置高度后者更精确但要处理内容变化的情况。6. 常见问题与排查技巧实录6.1 启动和构建阶段的报错速查下面这张表是我这两年记下来的高频问题和定位思路基本覆盖了日常能碰到的八成情况。现象大概率原因排查动作启动时提示 Node 版本不符Node 低于当前 Vite 要求node -v确认切到 20.19 或 22.12依赖装完后启动报找不到某个包幽灵依赖或锁文件混用删 node_modules 和锁文件重装统一包管理器打包产物部署后白屏控制台一堆 404base 没配或者配错检查base检查 index.html 里的资源引用Uncaught SyntaxError: Invalid or unexpected token资源路径错误加载到了 HTML 内容或字符编码问题打开 Network 看这个 JS 的实际响应体是不是 HTML构建到一半 Node 堆内存溢出项目太大或者依赖循环提高 max-old-space-size同时查循环依赖修改代码后页面不热更新HMR 断开或文件被忽略重启 dev server检查是否在项目根目录外类型提示正常但构建报 TS 错误vue-tsc 和编辑器用了不同的 tsconfig检查tsconfig.app.json的 include 范围重点说第二条。幽灵依赖这个事情用 npm 的时候很难发现因为你 import 了一个没在 dependencies 里声明的包只要它是别的包的间接依赖被提升到顶层了本地跑起来照样正常。但换到 pnpm 或者换了依赖树之后就炸了。判断方法很简单把 node_modules 删掉用 pnpm 重装一遍立刻就会暴露出来。6.2 内存溢出怎么处理才对前端项目跑到 OOM一般是几个原因叠加依赖太多导致依赖预构建阶段吃掉大量内存、业务代码里存在循环引用、或者 sourcemap 生成时占用过高。处理顺序我建议这样先在脚本里加cross-env NODE_OPTIONS--max-old-space-size4096把上限拉到 4G这是最快见效的。如果拉完还是不行说明不是内存上限的问题而是真的有东西在无限增长。这时候去查循环依赖用madge这类工具扫一下或者把build.sourcemap临时关掉看是否还崩。另外optimizeDeps.include手动把大依赖比如 echarts、mapbox-gl声明进去能减少预构建阶段的反复扫描。vue3 mapboxgl 这类地图库体积特别大还经常带 worker 文件构建时分包和 worker 的处理要单独配。我的做法是把地图库整体拆成一个独立 chunk用动态 import 延迟加载首屏基本感受不到它的存在。6.3 浏览器差异和一些玄学问题有些问题确实不是代码的锅。比如 vue3项目在 Edge 浏览器里有时候无法关闭右上角的最小化按钮——这个东西是浏览器自身的窗口 UI网页层根本控制不了遇到这种反馈我会先确认对方是不是把浏览器窗口的按钮和页面内的自定义按钮搞混了。类似地某些快捷键比如 CtrlW在浏览器里被保留前端也拦不住。还有一类是 uniapp vue2转vue3 过程中特有的Vue2 的选项式 API 里this.$refs、this.$nextTick用得很顺手转到组合式 API 之后这些都没了需要换成ref和nextTick显式导入。这个迁移不是简单改语法是要把依赖 this 上下文的思维换成显式依赖的思维。刚开始别扭用久了会发现类型推导和逻辑复用的体验好很多。diff 算法层面 Vue3 也做了重写编译期会标记动态节点运行时只对比变化的部分长列表渲染的优化比 Vue2 明显但这属于框架内部的收益业务代码不需要为此做额外工作。最后提一个部署上很容易忽略的点vite preview只是本地预览构建产物用的简易静态服务不能拿来当生产服务器。它没有缓存策略、没有 gzip、没有并发优化用它跑生产会被人投诉。正经做法是把dist目录交给 Nginx 或者 CDN配置好缓存头和 history fallback才算完整交付。我个人在实际操作中的体会是Vite 把搭建 Vue3 项目的门槛降得很低但它把复杂度转移到了配置理解上——默认配置能跑通一个 demo但要跑好一个真实项目你得知道base、proxy、manualChunks、env这几项分别在什么情况下要动。我习惯的做法是每接一个新项目先花半小时把vite.config.ts从头读一遍把它当成一份项目说明书比看任何 README 都快。
