Legacy To Modern Migration — 技能工具
v1.0.0指导将 JS + jQuery + HTML 传统前端项目迁移至 React + TypeScript 或 Vue 3 + TypeScript 的迁移策略、概念映射、分阶段步骤和检查清单。含图片、样式、功能等价等重构实施要求。当用户提到技术栈升级、jQuery 迁移、MPA 转 SPA、项目重构、遗留项目迁移为...
详细分析 ▾
运行时依赖
版本
Initial release: Migration strategies and checklists for upgrading legacy JS + jQuery + HTML projects to React + TypeScript or Vue 3 + TypeScript. - Provides phased migration steps, concept mapping tables, and detailed analysis workflow. - Details implementation requirements for images, icons, and styles to ensure functional and visual equivalence. - Includes migration checklists to guarantee code quality and feature completeness. - Enforces constraints: no inline SVG, use original icon/resources, no copying legacy CSS, and phased rollout preferred. - Specifies report output format and integration points with related front-end standards/skills.
安装命令 点击复制
技能文档
适用于将 JavaScript + jQuery + HTML/CSS 多页面应用(MPA)或服务端模板渲染项目,迁移至 React + TypeScript 或 Vue 3 + TypeScript 单页面应用(SPA)的场景。
适用场景
- 用户明确要求将 jQuery/MPA 项目重构为 React 或 Vue
- 讨论技术栈升级、遗留系统现代化
- 规划或执行从传统前端到 React/Vue 的迁移任务
迁移策略选择
| 策略 | 适用情况 | 优点 | 风险 |
|---|---|---|---|
| 渐进式(Strangler Fig) | 大型项目、需持续交付、团队熟悉度不足 | 风险可控、可分批上线、可回滚 | 新旧并存期长、需维护两套代码 |
| 一次性重写 | 中小型项目、业务稳定、有充足时间窗口 | 目标架构清晰、无历史包袱 | 周期长、上线压力大、回滚困难 |
概念映射
jQuery → React
| 遗留模式 | React 对应 |
|---|---|
$(selector).html(content) | 声明式 JSX + state 驱动渲染 |
$(document).on('click', '.btn', handler) | onClick + 事件委托由 React 处理 |
$.ajax() / $.get() | fetch / axios + React Query 或 SWR |
| 全局变量 / 命名空间存储状态 | useState / useContext / Zustand |
$(el).show() / $(el).hide() | 条件渲染 {visible && |
手动 DOM 操作 append / remove | 数据驱动,通过 setState 触发重渲染 |
| 模板字符串拼接 HTML | JSX 组件 + props |
| 多页面 + 服务端路由 | React Router 客户端路由 |
jQuery → Vue 3
| 遗留模式 | Vue 3 对应 |
|---|---|
$(selector).html(content) | 模板 + ref / reactive 驱动渲染 |
$(document).on('click', '.btn', handler) | @click + 事件修饰符 |
$.ajax() / $.get() | fetch / axios + VueUse useFetch 或 Vue Query |
| 全局变量 / 命名空间存储状态 | ref / reactive / Pinia |
$(el).show() / $(el).hide() | v-show / v-if |
| 手动 DOM 操作 | 数据驱动,通过响应式更新视图 |
| 模板字符串拼接 HTML | 单文件组件 + props |
| 多页面 + 服务端路由 | Vue Router 客户端路由 |
通用映射
| 遗留概念 | 现代对应 |
|---|---|
| 页面级 JS 入口(每页一个 script) | 路由 + 懒加载页面组件 |
| 公共 JS 模块(utils、ajax 封装) | services/、utils/、类型化 API 层 |
| 内联样式 / 页面级 CSS | CSS Modules / Tailwind / styled-components |
| 服务端模板变量 | 通过 API 获取 + 前端状态管理 |
| 表单提交 + 整页刷新 | 表单库 + 客户端校验 + API 调用 |
迁移前分析
在动手迁移前,必须完成以下分析并输出迁移分析报告:
- 存量盘点
- 依赖关系
- 迁移优先级
分阶段迁移流程
阶段 0:准备
- 搭建新项目脚手架(Vite + React/Vue + TypeScript)
- 配置 ESLint、Prettier、测试框架
- 建立
services/request.ts统一请求层,与现有 API 兼容 - 将遗留项目中的
utils、constants逐步迁移并补充类型
阶段 1:基础层
- 迁移并类型化 API 调用(
$.ajax→axios/fetch) - 迁移工具函数(日期、格式化、校验等)
- 迁移常量、枚举、类型定义
- 建立路由骨架,占位未迁移页面(重定向或 iframe 嵌入旧页面)
阶段 2:按模块/页面迁移
- 每次迁移一个完整功能或页面
- 从简单到复杂:静态页 → 列表页 → 表单页 → 复杂交互页
- 迁移时提取可复用组件,遵循
react-project-standard或vue3-project-standard的目录结构 - 每完成一个模块,补充单元测试和 E2E 关键路径
阶段 3:收尾
- 移除旧代码入口,全面切换至 SPA
- 配置 404、错误边界、全局错误处理
- 性能优化(懒加载、代码分割、缓存策略)
- 文档更新、部署流程调整
重构实施要求
迁移时需遵循以下实施约束,确保视觉与交互一致、代码更简洁易维护。
图片与图标
- 直接使用原项目的图片资源路径,不重新托管或替换
- 可使用 SVG 图片(
或 CSSbackground-image),禁止使用内联 SVG(直接写在组件中) - 若原项目使用了 iconfont 或 IcoMoon 图标,重构时继续使用,保持图标体系一致;不替换为其他图标方案(如独立 SVG、其他图标库)
- 图标优先使用原项目已有的图标文件(iconfont / IcoMoon / 已有 SVG),必要时可引入 SVG 文件作为独立资源
样式
- 布局样式对齐原项目视觉效果,但只参考原项目效果,不照搬其 CSS
- 优先使用 flex 弹性布局,避免
float、复杂position、冗余嵌套 - 避免不合理写法:如
!important滥用、过深选择器、重复定义 - 组件中禁止使用内联样式(
style={{ ... }}/style="..."),样式统一放在 CSS Modules、Tailwind 类或样式文件中,便于维护
目标
- 视觉和交互:与原项目一致,用户无感知差异
- 代码质量:更简洁、易维护,符合目标框架规范
- 业务功能:与原项目保持一致,不得缺失功能;迁移前后行为等价
迁移检查清单
每个迁移单元完成后,确认:
- [ ] 业务逻辑与旧实现一致,无功能遗漏,功能完整等价
- [ ] 类型定义完整,无
any滥用 - [ ] API 调用使用统一 request 层,错误处理完整
- [ ] 表单校验、loading、空状态、错误状态已实现
- [ ] 可访问性:表单有 label、交互可键盘操作
- [ ] 无 XSS 风险(用户输入已转义或使用安全 API)
- [ ] 关键路径有测试覆盖
- [ ] 符合目标框架的项目规范(参考
react-project-standard/vue3-project-standard) - [ ] 图片使用原项目资源,无内联 SVG;若原项目用 iconfont/IcoMoon 则继续使用
- [ ] 样式参考原项目效果但不照搬 CSS,优先 flex 布局,无内联样式
- [ ] 视觉与交互与原项目一致,代码更简洁易维护
强约束
- 迁移前必须先输出迁移分析报告,明确策略、优先级和风险
- 不要在一次迁移中同时改架构、改 UI、改接口
- 优先保证功能等价,再考虑优化和现代化
- 迁移过程中保持旧系统可运行,避免大爆炸式上线
- 遇到 jQuery 插件无现成替代时,可暂时用 iframe 或微前端方式嵌入,待后续替换
- 图片与图标:使用原项目图片资源,可用 SVG 文件,禁止内联 SVG;若原项目用 iconfont/IcoMoon 则继续使用
- 样式:参考原项目效果不照搬 CSS,优先 flex 布局,组件禁止内联样式
- 目标:视觉与交互一致、代码更简洁易维护,业务功能不得缺失
输出格式
迁移分析或迁移计划完成后,将报告保存为 Markdown 文件:
- 目录:项目根目录下的
reports/(如不存在则创建) - 文件名:
migration-plan-YYYY-MM-DD-HHmmss.md(使用当前时间戳) - 报告应包含:策略选择、存量盘点、依赖关系、迁移优先级、分阶段步骤、风险与回滚方案
相关技能
legacy-web-standard— 理解源项目(jQuery、MPA)的代码模式react-project-standard— 迁移至 React 时的目标结构规范vue3-project-standard— 迁移至 Vue 3 时的目标结构规范frontend-architect— 大型迁移的架构设计与风险评估
免费技能或插件可能存在安全风险,如需更匹配、更安全的方案,建议联系付费定制