Skill: yyyyzj/vue2-vite-upgrade (version 1.0.1)

--- name: vue2-vite-upgrade description: 将 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/vite-config.md) - **常见问题处理**：见 [references/common-issues.md](references/common-issues.md) - **部署配置**：见 [references/deploy-config.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](references/migration-steps.md) --- ## 阶段 2：文件清理与配置 1. 删除 Webpack 相关文件（build/、config/、.babelrc 等） 2. 更新 package.json（添加 type: module，替换 scripts，更新依赖） 3. 创建 vite.config.js（使用 [references/vite-config.md](references/vite-config.md) 模板） 4. 创建环境变量文件（.env.development、.env.staging、.env.production） 详细步骤见 [references/migration-steps.md](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](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](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](references/common-issues.md)** --- ## 阶段 5：部署配置（可选） 如需自动化部署，参考 [references/deploy-config.md](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` 调用、上传下载与登录态拦截 |


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (HIGH)