VuReact 实现 Vue Router 到 React Router 的无缝迁移
通过 @vureact/router 实现路由系统自动转换
借助 @vureact/router 适配库，VuReact 编译器可将基于 Vue Router 的路由逻辑自动转换为兼容 React 的实现。该方案支持组件、API 和配置层面的平滑迁移，无需手动重写路由结构。
支持的转换能力
<router-link>转换为<RouterLink><router-view>替换为<RouterView>- 核心 API 映射：
createRouter、useRouter()、useRoute()等保持一致调用方式 - 导航守卫保留行为：如
beforeEach、afterEach可继续使用 - 元信息访问不变：
to.meta在转换后依然可用 - 完整嵌套路由支持，包括命名视图和懒加载组件
- 自动引入
@vureact/router作为运行时依赖
依赖替换机制
编译过程中会智能替换模块导入路径：
// 编译前（Vue 环境）
import { createRouter, useRoute } from 'vue-router';
// 编译后（React 环境）
import { createRouter, useRoute } from '@vureact/router';
自动化集成配置
启用自动路由适配需完成以下配置步骤。
1. 配置路由入口文件
在项目根目录的 vureact.config.js 或 vureact.config.ts 中指定原始 Vue 路由配置文件位置：
import { defineConfig } from '@vureact/compiler-core';
export default defineConfig({
router: {
// 必填项：指向导出 createRouter 实例的文件
configFile: 'src/router/index.ts',
},
});
注意：若设置 output.bootstrapVite: false，则此自动注入功能将被禁用。
2. 规范化路由模块导出格式
确保路由配置文件使用 export default 导出由 createRouter 创建的实例：
// src/router/index.ts
import { createRouter, createWebHistory } from 'vue-router';
import App from '@/App.vue';
// 必须以 default 方式导出
export default createRouter({
history: createWebHistory(),
routes: [
{ path: '/', component: App }
]
});
3. 检查编译输出结果
构建完成后，系统将自动执行如下变更：
- 所有
vue-router引用替换为@vureact/router - React 入口文件中渲染节点更新为路由提供者组件
示例：编译后的主入口 main.tsx
import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import './index.css';
import RouterInstance from './router/index';
createRoot(document.getElementById('root')!).render(
<StrictMode>
<RouterInstance.RouterProvider />
</StrictMode>
);
生成的路由文件内容：
import { createRouter } from '@vureact/router';
export default createRouter({ /* 原始配置 */ });
核心优势在于：除包名外，所有路由定义与交互逻辑均无需修改，完全保留原有开发体验。
重要限制说明
- 仅当
bootstrapVite启用时生效 - 路由源文件必须符合标准 Vue Router 写法
- 仅影响路由相关代码，业务组件不受干扰
手动接入方案（适用于非自动场景）
当无法使用自动注入时，可通过以下流程完成迁移。
前置条件
- 已完成源码转换（执行
npx vureact build） - 已安装
@vureact/router - 路由配置文件结构清晰且有效
实施步骤
步骤一：明确路由实例导出
在原路由文件中导出路由对象（不限定导出方式）：
// src/router/index.ts
import { createRouter, createWebHistory } from 'vue-router';
import App from '../App.vue';
import Dashboard from '../views/Dashboard.vue';
const routes = [
{
path: '/',
component: App,
children: [
{ path: 'dashboard', component: Dashboard }
]
}
];
const router = createRouter({
history: createWebHistory(),
routes
});
export { router }; // 支持具名导出
步骤二：更新应用入口渲染逻辑
修改 React 主文件，使用 RouterProvider 包裹应用：
import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import './index.css';
import { router } from './router/index';
createRoot(document.getElementById('root')!).render(
<StrictMode>
<router.RouterProvider />
</StrictMode>
);
关键提示：
- 不要直接渲染
<App />，应将其作为根路径的组件注册到路由表中；RouterProvider是@vureact/router提供的上下文容器，负责初始化路由状态并传递给RouterView和RouterLink；- 兼容 Vue Router 的全部特性，包括动态添加路由、滚动行为控制等。
手动适配总结
- 确保路由实例正确导出
- 替换根节点渲染为
RouterProvider - 验证各类路由功能是否正常工作
整个过程无需重构现有路由逻辑，开发者可沿用熟悉的 Vue Router 编程模型。
验证流程
构建产物生成后，进入输出目录（如 .vureact/react-app），执行以下操作：
- 安装依赖：
npm install - 启动服务：
npm run dev - 测试页面跳转：点击链接检查是否能正确导航
- 验证嵌套路由：确认子视图是否按预期渲染
