Vue 2 项目 Webpack 升级到 Vite 构建工具

将 Vue 2 + Webpack 项目升级到 Vite 构建工具。当用户需要将 Vue 2 项目从 Webpack 迁移到 Vite、优化构建速度、解决 Webpack 配置问题，或处理 Vue CLI/Webpack 与 Vite 环境变量兼容时使用此技能。触发场景包括：(1) 用户提到"升级到 Vite"、"迁移到 Vite"、"Webpack 转 Vite"；(2) 用户抱怨 Webpack 构建慢、热更新慢；(3) 用户想要现代化 Vue 2 项目的构建工具；(4) 用户遇到 Webpack 配置复杂难以维护的问题；(5) 用户询问如何提升 Vue 2 项目的开发体验；(6) 用户提到 process.env、VUE_APP_*、import.meta.env、VITE_* 等环境变量兼容。

Vue 2 项目升级到 Vite 构建工具

重要提示

⚠️ 在开始之前，必须确认用户已经备份了代码或使用了 Git 版本控制！

前置安全检查

阶段 2 包含删除操作（rm -rf / git rm），执行前必须确认：

1. 当前在项目根目录（ls package.json 存在）
2. Git 状态干净或业务代码已提交/stash（git status）
3. 用户已明确确认可以执行删除
4. 删除操作优先使用 git rm（可通过 git restore 恢复），非 Git 项目才使用 rm

执行原则

1. 使用 TodoWrite 工具：创建完整的任务列表，实时更新进度
2. 分阶段执行：按照阶段顺序执行，每个阶段完成后标记为完成
3. 遇到问题及时沟通：使用 AskUserQuestion 询问用户
4. 保留业务依赖：只删除 Webpack/Babel 相关依赖

执行流程概览

阶段	内容
阶段 1	项目分析 - 分析现有项目结构、依赖和配置
阶段 2	文件清理与配置 - 删除 Webpack 配置，创建 Vite 配置
阶段 3	代码迁移 - 修改代码以适配 Vite
阶段 4	测试与验证 - 安装依赖并测试运行
阶段 5	部署配置（可选）- 配置自动化部署脚本

参考文档

• Vite 配置模板：见 references/vite-config.md
• 常见问题处理：见 references/common-issues.md
• 部署配置：见 references/deploy-config.md

---

阶段 1：项目分析

使用 TodoWrite 创建任务列表，然后依次执行：

1. 分析 package.json（识别业务依赖、Webpack 依赖、需升级依赖）
2. 提取环境变量（从 config/.env.js 转换为 .env. 格式）
3. 检查代理配置（记录 proxyTable）
4. 检查特殊功能（SVG Sprite、JSX、动态路由）
5. 单独审计 axios：核对官方 release/security 公告，避免继续保留已披露漏洞版本；同时排查上传、导出、401/403 拦截和裸 axios 调用

详细步骤见 references/migration-steps.md

---

阶段 2：文件清理与配置

1. 删除 Webpack 相关文件（build/、config/、.babelrc 等）
2. 更新 package.json（添加 type: module，替换 scripts，更新依赖）
3. 创建 vite.config.js（使用 references/vite-config.md 模板）
4. 创建环境变量文件（.env.development、.env.staging、.env.production）

详细步骤见 references/migration-steps.md

---

阶段 3：代码迁移

1. 修改 index.html（移动到根目录，添加 <script type="module">）
2. 修改 main.js（使用 render 函数，导入加 .vue 扩展名）
3. 迁移环境变量：优先使用 import.meta.env；如项目存在并行上线或老分支合并，需要保留 process.env.VUE_APP_* 静态写法兼容层
4. 处理静态资源（static → public，~@ → @，global → window）
5. 修改组件导入（所有 .vue 导入加扩展名）
6. 修复样式（/deep/ 和 >>> → ::v-deep）

详细步骤见 references/migration-steps.md

---

环境变量兼容约定

迁移期如果可能有 Webpack/Vue CLI 写法的需求先合入生产，不要只做 process.env -> import.meta.env 的单向替换。

1. .env.* 中新增变量优先使用 VITE_ 前缀。
2. Vite 代码推荐使用 import.meta.env.VITE_*。
3. Webpack/Vue CLI 历史代码允许继续使用 process.env.VUE_APP_*。
4. 在 vite.config.js 中用 loadEnv(mode, process.cwd(), '') 读取变量，并自动把 VITE_XXX 映射为 process.env.VUE_APP_XXX。
5. 如果 .env.* 已存在 VUE_APP_XXX，也要原样注入为 process.env.VUE_APP_XXX。
6. define 使用精确 key，不整体替换 process.env，减少对第三方库和动态访问的影响。
7. 兼容层只保证静态写法，如 process.env.VUE_APP_BASE_API；不承诺兼容 process.env[key]。

具体配置示例见 references/vite-config.md。

---

阶段 4：测试与验证

1. 安装依赖：先执行 pnpm install；如遇 peer dependency 冲突，优先手动排查并解决版本冲突，确认无法解决后再使用 pnpm install --force（--force 会忽略 lockfile，需检查 pnpm-lock.yaml 变更）
2. 启动开发服务器：pnpm run dev
3. 验证功能：页面显示、样式、图标、路由、API 请求
4. 构建测试：pnpm run build:stage && pnpm run preview

遇到问题查看 references/common-issues.md

---

阶段 5：部署配置（可选）

如需自动化部署，参考 references/deploy-config.md：

1. 创建压缩脚本（export-zip.cjs）
2. 创建 FTP 部署脚本（ftp-deploy.js）—— 部署凭证通过环境变量传入，禁止硬编码
3. 添加部署 NPM 脚本
4. 安装依赖：pnpm add -D archiver ftp-deploy rimraf
5. 执行生产部署前需显式确认

---

升级要点速查

类别	修改内容
依赖管理	保留业务依赖，删除 Webpack/Babel，升级 Vue 到 2.7.x；axios 使用当前 1.x 安全补丁版本，不保留已披露漏洞版本
配置文件	创建 vite.config.js 和 .env.* 文件
代码修改	.vue 导入加扩展名，环境变量优先迁移到 import.meta.env，必要时兼容 process.env.VUE_APP_*
语法替换	require → import，global → window，~@ → @
axios 改造	排查 CancelToken、headers.post['Content-Type']、裸 axios 调用、上传下载与登录态拦截