在 Vue 3 项目中混入 React 生态能力的项目，将其迁移至 React 的完整教程，手把手带你体验 VuReact 的编译能力
🎯 写在前面
这是一篇贴近真实业务场景的多渠道客服协同后台迁移实战教程。通过一个 Vue + React 混合开发 项目，你将完整经历一次 VuReact 在复杂后台场景下的混写与转换迁移闭环。
读完本文，你将学会：
- ✅ 克隆并启动示例仓库
- ✅ 理清项目目录，定位迁移关键文件
- ✅ 使用
build/watch观察编译产物 - ✅ 启动 React 产物并完成业务验收
重点使用的混合技术栈：
- Vue 3
- Vue Router 4
- Ant Design 6（React）
- Zustand（React）
在线体验入口
- 📦 仓库：example-customer-support-hub
- 🏄♂️ CodeSandbox：在线演示
- 🌐 直接预览：skx7pn-5173.csb.app/
🧩 项目结构速览
先对目录有个整体印象（重点看加粗部分）：
customer-support-hub/
├─ package.json
├─ vureact.config.ts # 编译配置
├─ vite.config.ts
├─ index.html
└─ src/
├─ main.ts # Vue 入口 → 编译后为 React 入口
├─ App.vue
├─ styles/
├─ store/
│ └─ useAppStore.ts # 🔑 跨页面状态（验收核心）
├─ components/
│ └─ ...（多个业务组件）
├─ pages/ # 🔑 所有业务页面
│ ├─ Dashboard.vue
│ ├─ TicketsList.vue
│ ├─ Customers.vue
│ ├─ KnowledgeBase.vue
│ ├─ SlaBoard.vue
│ └─ auth/Login.vue
└─ router/
├─ index.ts # 🔑 路由适配关键文件
└─ routes.ts
迁移时的三个关键盯防点：
src/main.ts— 决定产物入口src/router/index.ts— 路由守卫与适配src/store/useAppStore.ts— 状态联动是否正常
📦 Step 1：克隆 & 安装依赖
git clone https://github.com/vureact-js/example-customer-support-hub.git
cd customer-support-hub
npm install
确认 package.json 中包含以下脚本：
"scripts": {
"vr:watch": "vureact watch",
"vr:build": "vureact build"
}
✅ 验收标准
npm install无报错- 项目根目录存在
vureact.config.ts - 可以执行
npm run vr:build
⚙️ Step 2：跑通编译闭环
执行全量编译：
npm run vr:build
若希望源码改动后自动增量编译，开启监听模式：
npm run vr:watch
📌 你会看到
- 控制台输出编译统计（SFC / script / style 处理数量）
- 根目录生成
.vureact/react-app文件夹 - React 产物结构与 Vue 源码保持高度一致
💡 关键理解
- 这一步的目标是确认编译器能稳定产出 React 工程，而不是立刻看到页面
- 若产物未生成，优先检查
vureact.config.ts是否存在 - 示例通过
onSuccess钩子自动修复样式导入，以最终产物为准
🔧 常见问题
| 症状 | 排查 |
|---|---|
build 失败 | 检查 Vue 源码是否有语法错误 |
| 产物目录缺失 | 命令是否在项目根目录执行？ |
watch 不同步 | 确认监听进程是否仍在运行 |
✅ 验收标准
.vureact/react-app成功生成- 重复执行
npm run vr:build可稳定得到产物
🔍 Step 3：理解三个关键文件
1️⃣ 路由入口 — src/router/index.ts
它决定了 Vue 路由如何被适配到 React 产物：
router: {
configFile: 'src/router/index.ts',
}
2️⃣ 状态入口 — src/store/useAppStore.ts
管理会话、筛选条件、活动流等跨页面状态。
状态变化链路通 → 页面联动通。
3️⃣ 页面入口 — src/pages/
验收时重点关注这些页面：
Dashboard.vueTicketsList.vueTicketDetail.vueCustomers.vueKnowledgeBase.vueSlaBoard.vueauth/Login.vue
建议阅读顺序：
路由 → 状态 → 页面
🚀 Step 4：启动 React 产物
进入生成的 React 工程并启动开发服务器：
cd .vureact/react-app
npm install # 首次需要安装依赖
npm run dev
🧪 你会看到
- Vite dev server 正常启动
- 浏览器打开登录页
- 登录后进入客服协同主界面
- 修改 Vue 源文件 → React 产物热更新
⚠️ 重要提醒
- 这一步验证的是产物能否独立运行
- 对于混写项目，Vue 源码和 React 产物是两条同时存在但职责不同的链路
- 请把 React 产物当作编译结果来验证，不要直接修改它
✅ 验收标准
npm run dev成功启动- 可从登录流进入业务主页
- 修改 Vue 源码后，React 页面同步更新
✅ Step 5：业务验收（核心！）
页面启动后，按以下链路验收：
你应该能完成的操作
- 登录 → 进入系统
- 打开 Dashboard / Tickets / Customers / KnowledgeBase / SlaBoard / Settings
- 工单列表：筛选、切换、查看详情
- 客户页：查看风险信息，观察状态联动
- SLA 看板：风险状态实时变化
- 知识库：浏览 + 检索
重点观察的状态变量
| 状态 | 作用 | 如何验证 |
|---|---|---|
session | 登录与路由守卫 | 未登录访问业务页 → 跳转登录 |
ticketFilters | 工单列表筛选 | 修改筛选条件 → 列表刷新 |
activities | 活动流记录 | 执行接单/升级 → 活动流新增记录 |
slaConfig | SLA 风险配置 | 修改配置 → SLA 看板同步 |
🔧 常见问题速查
| 现象 | 排查方向 |
|---|---|
| 登录后仍回登录页 | 检查路由守卫 + session 状态 |
| 列表筛选不生效 | 检查筛选条件是否正确写入 store |
| 活动流不更新 | 检查动作是否调用了对应的 mock-api |
✅ 验收标准
- 登录、路由、筛选、详情、SLA、知识库等核心链路全部跑通
- 能明确说出每个页面依赖的状态和动作
- 已完成一次从 Vue 源码到 React 产物的完整闭环验证
🔗 相关问题与资源
- 路由报错 → 路由适配指南
- 编译告警 → 编译约定
- 问题反馈：编译器 Issues | 路由 Issues
🧠 总结
按照上述顺序走完 克隆 → 安装 → 编译 → 启动 → 验收，你就建立了 VuReact 的最小工作流：
先让编译成立 → 再让产物运行 → 最后用业务链路验证迁移结果
很多开发者会疑惑：Vue 的响应式、路由守卫、生命周期等逻辑，如何平稳运行在 React 中？
核心依靠两个底层依赖：@vureact/runtime 与 @vureact/router，它们为编译转换提供了稳定的运行时与路由适配能力。
📢 特别说明：VuReact 不同于 Veaury、Vuera 等运行时套壳方案，它采用语义级编译路线，直接将 Vue 转换为纯净、无耦合、可独立维护的 React 代码，在性能、包体积与可维护性上更具优势。
📚 后续学习导航
- Build 增量编译 | Watch 监听模式 — 掌握
build/watch命令 - 配置 API — 深入理解
input/exclude/output/router核心配置 - 编译约定 — 明确编译器行为边界，降低迁移偏差
如果这篇文章对你有帮助，欢迎点赞、收藏、评论～
也欢迎在 GitHub 上给 VuReact 点个 ⭐️，开源不易，感谢支持！
