Vue 2 项目升级到 Vite 构建工具
重要提示
⚠️ 在开始之前，必须确认用户已经备份了代码或使用了 Git 版本控制！
前置安全检查
阶段 2 涉及移除 Webpack 旧配置，执行前必须确认：
- 当前在项目根目录（
ls package.json存在） - Git 状态干净或业务代码已提交/stash（
git status） - 用户已明确确认可以移除旧配置
- 在 Git 项目中优先使用可恢复的版本控制方式移除文件；非 Git 项目需先确认备份
执行原则
- 使用 TodoWrite 工具：创建完整的任务列表，实时更新进度
- 分阶段执行：按照阶段顺序执行，每个阶段完成后标记为完成
- 遇到问题及时沟通：使用 AskUserQuestion 询问用户
- 保留业务依赖：只删除 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 创建任务列表，然后依次执行：
- 分析 package.json（识别业务依赖、Webpack 依赖、需升级依赖）
- 提取环境变量（从 config/.env.js 转换为 .env. 格式）
- 检查代理配置（记录 proxyTable）
- 检查特殊功能（SVG Sprite、JSX、动态路由）
- 单独审计
axios：核对官方 release/security 公告，避免继续保留已披露漏洞版本；同时排查上传、导出、401/403 拦截和裸axios调用
详细步骤见 references/migration-steps.md
阶段 2：文件清理与配置
- 删除 Webpack 相关文件（build/、config/、.babelrc 等）
- 更新 package.json（添加 type: module，替换 scripts，更新依赖）
- 创建 vite.config.js（使用 references/vite-config.md 模板）
- 创建环境变量文件（.env.development、.env.staging、.env.production）
详细步骤见 references/migration-steps.md
阶段 3：代码迁移
- 修改 index.html（移动到根目录，添加
<script type="module">） - 修改 main.js（使用 render 函数，导入加 .vue 扩展名）
- 迁移环境变量：优先使用 import.meta.env；如项目存在并行上线或老分支合并，需要保留 process.env.VUE_APP_* 静态写法兼容层
- 处理静态资源（static → public，~@ → @，global → window）
- 修改组件导入（所有 .vue 导入加扩展名）
- 修复样式（/deep/ 和 >>> → ::v-deep）
详细步骤见 references/migration-steps.md
环境变量兼容约定
迁移期如果可能有 Webpack/Vue CLI 写法的需求先合入生产，不要只做 process.env -> import.meta.env 的单向替换。
.env.*中新增变量优先使用VITE_前缀。- Vite 代码推荐使用
import.meta.env.VITE_*。 - Webpack/Vue CLI 历史代码允许继续使用
process.env.VUE_APP_*。 - 在
vite.config.js中用loadEnv(mode, process.cwd(), '')读取变量，并自动把VITE_XXX映射为process.env.VUE_APP_XXX。 - 如果
.env.*已存在VUE_APP_XXX，也要原样注入为process.env.VUE_APP_XXX。 define使用精确 key，不整体替换process.env，减少对第三方库和动态访问的影响。- 兼容层只保证静态写法，如
process.env.VUE_APP_BASE_API；不承诺兼容process.env[key]。
具体配置示例见 references/vite-config.md。
阶段 4：测试与验证
- 安装依赖：先执行
pnpm install；如遇 peer dependency 冲突，优先手动排查并解决版本冲突，确认无法解决后再使用pnpm install --force（--force会忽略 lockfile，需检查pnpm-lock.yaml变更） - 启动开发服务器：
pnpm run dev - 验证功能：页面显示、样式、图标、路由、API 请求
- 构建测试：
pnpm run build:stage && pnpm run preview
遇到问题查看 references/common-issues.md
阶段 5：部署配置（可选）
如需自动化部署，参考 references/deploy-config.md：
- 创建压缩脚本（export-zip.cjs）
- 创建 FTP 部署脚本（ftp-deploy.js）—— 部署凭证通过环境变量传入，禁止硬编码
- 添加部署 NPM 脚本
- 安装依赖：
pnpm add -D archiver ftp-deploy rimraf - 执行生产部署前需显式确认
升级要点速查
| 类别 | 修改内容 |
|---|---|
| 依赖管理 | 保留业务依赖，删除 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 调用、上传下载与登录态拦截 |
