指导将 JS + jQuery + HTML 传统前端项目迁移至 React + TypeScript 或 Vue 3 + TypeScript 的迁移策略、概念映射、分阶段步骤和检查清单。含图片、样式、功能等价等重构实施要求。当用户提到技术栈升级、jQuery 迁移、MPA 转 SPA、项目重构、遗留项目迁移为 React/Vue 时自动激活。
适用于将 JavaScript + jQuery + HTML/CSS 多页面应用（MPA）或服务端模板渲染项目，迁移至 React + TypeScript 或 Vue 3 + TypeScript 单页面应用（SPA）的场景。
| 策略 | 适用情况 | 优点 | 风险 |
|---|---|---|---|
| 渐进式（Strangler Fig） | 大型项目、需持续交付、团队熟悉度不足 | 风险可控、可分批上线、可回滚 | 新旧并存期长、需维护两套代码 |
| 一次性重写 | 中小型项目、业务稳定、有充足时间窗口 | 目标架构清晰、无历史包袱 | 周期长、上线压力大、回滚困难 |
推荐：优先考虑渐进式，除非项目规模小且业务简单。
| 遗留模式 | 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 客户端路由 |
| 遗留模式 | 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 调用 |
在动手迁移前，必须完成以下分析并输出迁移分析报告：
存量盘点
依赖关系
迁移优先级
services/request.ts 统一请求层，与现有 API 兼容utils、constants 逐步迁移并补充类型$.ajax → axios/fetch）react-project-standard 或 vue3-project-standard 的目录结构迁移时需遵循以下实施约束，确保视觉与交互一致、代码更简洁易维护。
<img src="*.svg" /> 或 CSS background-image），禁止使用内联 SVG（<svg>...</svg> 直接写在组件中）float、复杂 position、冗余嵌套!important 滥用、过深选择器、重复定义style={{ ... }} / style="..."），样式统一放在 CSS Modules、Tailwind 类或样式文件中，便于维护每个迁移单元完成后，确认：
any 滥用react-project-standard / vue3-project-standard）迁移分析或迁移计划完成后，将报告保存为 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 — 大型迁移的架构设计与风险评估