传统前端到现代框架迁移

---

name: legacy-to-modern-migration

description: 指导将 JS + jQuery + HTML 传统前端项目迁移至 React + TypeScript 或 Vue 3 + TypeScript 的迁移策略、概念映射、分阶段步骤和检查清单。含图片、样式、功能等价等重构实施要求。当用户提到技术栈升级、jQuery 迁移、MPA 转 SPA、项目重构、遗留项目迁移为 React/Vue 时自动激活。

version: 1.0.0

---

# 传统前端到现代框架迁移

适用于将 JavaScript + jQuery + HTML/CSS 多页面应用（MPA）或服务端模板渲染项目，迁移至 React + TypeScript 或 Vue 3 + TypeScript 单页面应用（SPA）的场景。

适用场景

迁移策略选择

| 策略 | 适用情况 | 优点 | 风险 |

|------|----------|------|------|

| **渐进式（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 && <Component />}` |

| 手动 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 | 单文件组件 `<template>` + props |

| 多页面 + 服务端路由 | Vue Router 客户端路由 |

通用映射

| 遗留概念 | 现代对应 |

|----------|----------|

| 页面级 JS 入口（每页一个 script） | 路由 + 懒加载页面组件 |

| 公共 JS 模块（utils、ajax 封装） | `services/`、`utils/`、类型化 API 层 |

| 内联样式 / 页面级 CSS | CSS Modules / Tailwind / styled-components |

| 服务端模板变量 | 通过 API 获取 + 前端状态管理 |

| 表单提交 + 整页刷新 | 表单库 + 客户端校验 + API 调用 |

迁移前分析

在动手迁移前，必须完成以下分析并输出**迁移分析报告**：

1. **存量盘点**

- 页面数量、功能模块数量

- 依赖的 jQuery 插件及替代方案（如 DataTables → TanStack Table）

- 现有 API 调用方式、是否有统一封装

- 是否有服务端模板（JSP/Thymeleaf/EJS 等）需改为纯前端渲染

2. **依赖关系**

- 页面间共享的 JS/CSS 模块

- 跨页面复用的业务逻辑

- 与后端的接口契约（是否需调整）

3. **迁移优先级**

- 按业务价值、复杂度、耦合度排序

- 优先迁移独立模块、低耦合页面

- 识别可复用的工具函数、常量、类型定义

分阶段迁移流程

阶段 0：准备

阶段 1：基础层

阶段 2：按模块/页面迁移

阶段 3：收尾

重构实施要求

迁移时需遵循以下实施约束，确保视觉与交互一致、代码更简洁易维护。

图片与图标

样式

目标

迁移检查清单

每个迁移单元完成后，确认：

强约束

输出格式

迁移分析或迁移计划完成后，将报告保存为 Markdown 文件：

相关技能