接手一个 Vue 2 Webpack 4 的老项目最折磨人的不是需求而是按下保存要等 40 秒冷启动、热更新卡在 3-5 秒改一行样式浏览器得来回切三次才刷新同事问个页面逻辑我得先等项目起来才敢点开。想迁 Vite 的念头拖了大半年卡点在于——照着官方迁移文档一条条翻译配置太慢社区零散帖又常常对不上自己项目的插件组合改到一半反而更不敢动。本文分享一套用 AI 陪跑的迁移打法先锁定框架版本与插件选型 用结构化完整报错喂给 Cursor 迁完让 AI 反向扫描遗漏写法可直接落地。一、迁移前先把等待成本算清楚动手之前先把等待成本量化才好判断这次迁移值不值启动成本冷启动 40 秒按完保存起身倒水坐下时编译条才跑完一半。热更成本HMR 稳定在 3-5 秒微调一行样式要在浏览器和编辑器之间反复横跳。协作成本同事来问问题我得先等项目起来才敢打开对应页面截图给他。迁移成本预估两天且必须挑需求空档期做迁完要能一键回滚。核心结论一天里被编译切碎的专注时间远比投入两天做迁移昂贵。二、选型Vue 2 该配哪套 Vite 插件配置之前先做选型插件必须和框架大版本严格对齐继续 Vue 2用社区维护中的vite-plugin-vue2业务组件几乎零改动。顺手升 Vue 3迁移成本直接翻倍这次明确不选。先告诉 AI 版本Cursor 第一版给的是 Vue 3 写法我补了一句「项目是 Vue 2.7 Webpack 4」它才换成 Vue 2 插件方案。方案对应插件业务改动量主要风险继续 Vue 2vite-plugin-vue2近乎为零社区维护需锁定版本升级 Vue 3vitejs/plugin-vue组件与 API 需重写周期翻倍回归面大两套混用无成熟方案—产物行为不可控最小可跑的配置骨架如下适配 Node 18 与 Vue 2.7 项目// vite.config.jsimport{defineConfig}fromviteimport{createVuePlugin}fromvite-plugin-vue2exportdefaultdefineConfig({plugins:[createVuePlugin()],server:{port:5173,open:true}})核心结论版本和大版本框架不先交代清楚AI 后面所有配置翻译都会跑偏。三、入口改造从 html-webpack-plugin 到根目录 index.html入口是最容易被忽略的一处Webpack 的 HTML 生成逻辑要整体换位生成改手写html-webpack-plugin的模板逻辑废弃直接在项目根目录放一份index.html。脚本挂主文件用script typemodule src/src/main.js挂入口Vite 才能接管依赖预构建。命令同步替换package.json里的serve/build换成vite/vite buildCI 脚本一起改。!-- index.html放在项目根目录而非 public/ --!DOCTYPEhtmlhtmllangzh-CNheadmetacharsetUTF-8/title老项目迁 Vite/title/headbodydividapp/divscripttypemodulesrc/src/main.js/script/body/htmlhtml-webpack-plugin→ 根目录index.html→/src/main.js模块脚本 →package.json命令替换核心结论入口没换位后面所有配置怎么调都起不来。四、提问模板让 AI 从完整堆栈里定位报错贴得越完整AI 定位越准这是整场迁移里最关键的习惯完整堆栈贴全部报错 出错文件路径 出错片段不要只贴一行xxx is not defined。交代上下文框架版本、迁移阶段、相关依赖版本一并给出AI 才能从上下文推断根因。限定问法直接问「在 Vite 里通常是什么原因、怎么改」避免它反过来劝你重写项目。这段是我复用最多的提问模板直接粘进 Cursor Chat 即可项目Vue 2.7 从 Webpack 4 迁到 Vitevite-plugin-vue2 阶段已完成入口替换业务代码尚未改造 报错如下 [粘贴完整报错与堆栈] 相关代码 [出错文件片段 文件路径] 依赖版本 [package.json 中相关包与版本] 问这个报错在 Vite 里通常是什么原因请给出最小改动方案不要引入新依赖。核心结论报错只贴一行AI 只能猜贴全上下文它才能给出能直接改的方案。五、坑一require 报错的 ESM 改写第一个拦路的是require is not defined根因是构建底座换了模块规范规范差异Vite 走原生 ESM浏览器端业务代码不认 CommonJS 的require。静态导入图片、样式等静态资源直接改成import交给 Vite 处理哈希与打包。动态路径运行时拼接的路径改用new URL(./x.png, import.meta.url)保住静态分析能力。// ❌ Webpack 时代constimgrequire(./assets/logo.png)// ✅ Vite静态资源importimgfrom./assets/logo.png// ✅ Vite动态路径constnamebannerconsturlnewURL(./assets/${name}.png,import.meta.url).hrefrequire静态化 →import承接资源 →import.meta.url兜住动态路径核心结论改的不是一行语法而是把「运行时加载」翻译成「构建期可分析」。六、坑二别名与全局变量翻译成 resolve.alias第二类坑藏在隐式约定里Webpack 配的别名和注入到了 Vite 全部失效别名显式化resolve.alias里把、components逐条重写路径用path.resolve保证绝对。全局变量ProvidePlugin注入的$、Vue改为define或在入口显式import不再隐式注入。逐条核对把老的webpack.config.js整段贴给 AI问「Vite 里对应怎么写」再人工确认。问题解析不到、$ is not defined、Vue is not defined三类报错同时冒出来。治理别名进resolve.alias全局注入改成define或入口显式导入。核心结论隐式约定一旦显式化剩下的报错才真正指向业务代码。七、坑三环境变量与代理的语义差异配置翻译最容易出错的是环境变量两套体系的前缀和暴露规则不同前缀改写process.env.VUE_APP_*要换成import.meta.env.VITE_*老变量名必须重命名。暴露限制只有VITE_开头的变量才会进入客户端服务端密钥别顺手塞进去。代理等价devServer.proxy的pathRewrite换成 Viteserver.proxy的rewrite。// vite.config.js 中的环境变量与代理片段import{defineConfig}fromviteexportdefaultdefineConfig({define:{__BUILD_TIME__:JSON.stringify(Date.now())},server:{proxy:{/api:{target:http://localhost:8080,changeOrigin:true,rewrite:pp.replace(/^\/api/,)}}}})VUE_APP_*→VITE_*→define注入常量 →server.proxy.rewrite接管转发核心结论环境变量翻译漏一个前缀线上就会静默读到undefined。八、反向扫描让 AI 找出遗漏写法迁完不要急着提测让 AI 做一次反向扫描最省事给扫描清单让它按「Webpack 特有写法」清单逐项 grep输出文件路径与改法。人工复核AI 命中的项逐条看它偶尔会把正确写法误报成问题。保留证据扫描结果贴进 PR 描述评审时省掉来回解释。排查项典型写法Vite 下的处理动态requirerequire( 变量 )import()或new URLWebpack 专有全局__webpack_public_path__删除改用base配置加载器语法!!raw-loader!./x换成?raw查询后缀分包魔法注释webpackChunkName改用manualChunks核心结论人工肉眼扫容易漏AI 按清单扫一遍遗漏率明显更低。九、实测迁移前后的四项硬指标迁移完先量数据再下结论四项指标都要留痕指标Webpack 4Vite变化冷启动约 40 秒约 1.2 秒提速约 33 倍热更新3-5 秒80-200 毫秒一个数量级生产构建约 96 秒约 24 秒缩短约 4 倍产物体积1.86 MB1.79 MB基本持平这条命令用来跑生产构建并抓出耗时与产物大小适配 macOS / Linux 终端timenpx vite build21|tail-8du-hdist/assets/*.js|sort-h|tail-5强约束改动 → 分支灰度 → 数据达标再合并主干核心结论数字摆上桌迁移价值才不需要靠嘴说服别人。十、上线前的兜底清单与回滚预案最后一道防线是可回滚出问题时能五分钟退回原样双轨并行迁移在独立分支进行Webpack 主干保持可用CI 两条流水线都跑。回归重点登录态、上传下载、图表异步加载、懒路由这四类最依赖构建行为。回滚开关发布平台保留旧构建产物一键切换npm run build失败不阻断旧版本。版本锁定vite与插件写死小版本避免上游发版再次打破构建。核心结论没有回滚方案的迁移本质上是在赌运气。结语回头看这次迁移真正的杠杆不在工具本身而在提问的方式版本先交代清楚AI 的配置翻译才不会跑偏报错贴全堆栈加代码片段定位才会一次命中迁完再让它按清单反向扫描遗漏的 Webpack 特有写法才浮出水面。两天时间里AI 大约替我消化了六成的机械劳动剩下四成——尤其是环境变量前缀和懒加载行为——仍然要靠人来验证和拍板。这套打法的价值可以复用到任何一次构建工具迁移先把痛点量化成可对比的指标再把上下文完整交给 AI最后用数据和回滚预案兜底。工具会换代方法论不会。AI 负责把报错翻译成改动人负责把改动翻译成可上线的判断。