企业官网建设流程全解析

干了这么多年前端，我越来越觉得“标准化技能栈的跨框架移植”这件事，真正的成本从来不在语法，而在习惯和架构。你说React转Vue，Hook变composition API，JSX变template，这些其实都是表面功夫，真正要命的是路由、状态管理、数据请求这些“基础设施”全部被框架绑死了。最近我们正好把一个基于React的某数据可视化系统移植到Vue 3，前期把路由配置和数据逻辑做了标准化拆解，中期只写了两层适配，后期大部分业务代码几乎是原封不动搬过去的。这篇就来聊聊“标准化技能栈的跨框架移植”到底怎么落地，以及路由机制是怎么在底层支撑这种迁移的。适合正在准备技术栈切换、或者项目中想保留跨团队多框架方案的开发者做参考。

1. 跨框架移植的本质：先标准化，再迁移

1.1 为什么React到Vue的迁移总在“重写”？

先说一个现象。大部分团队在换框架时，第一反应是“把页面照着新框架重新写一遍”。组件要重写、hooks要重写、路由要重写、请求写在组件里的也要重写。最后你会发现，表面上是换框架，实际上是把整个项目推倒重来，工时翻倍，老板还不理解为什么“明明啥都没变，还要做这么久”。

为什么会这样？因为很多项目根本没有把“框架相关”和“框架无关”分开。业务逻辑、路由meta、状态管理、API调用全都和组件文件耦合在一起。React组件里直接调useNavigate，Vue组件里直接调useRouter，看起来只是API不一样，但背后的路由模型、历史记录管理、权限校验逻辑全都散落在各个组件里。这时候想移植，除非你肯花时间把散落的逻辑捞出来，否则就只能重写。

所以跨框架移植的第一步，不是安装Vue，而是先做技能栈的“标准化”。所谓标准化技能栈，就是把那些不依赖具体渲染层的技术能力——类型系统、状态容器、路由配置、副作用处理、模块加载方式——沉淀成一套框架中立、可复用的“技能栈”。组件库可以换，但这些底层模块在一个团队里应该是统一的。这也是为什么很多人说“不管React还是Vue，我都用同一套状态管理和数据请求方式”，本质就是让自己不被某一家框架绑架。

1.2 可以从框架里“剥出来”的标准化模块

我自己的经验，一个前端项目里，真正值得跨框架复用的模块通常有四层：

• 状态层：包括全局状态、本地缓存、用户会话。不管用Zustand还是Pinia，底层都是订阅发布加上不可变更新的思路，区别只在于响应式引擎。
• 路由层：路径、meta、嵌套关系、守卫逻辑，这一层本质上是纯数据，完全可以和渲染框架解耦。
• 业务逻辑层：数据处理、权限判断、格式化、组件内复用的副作用逻辑，通过依赖注入的方式让框架适配器提供宿主能力。
• 模块加载层：懒加载、异步组件、错误边界，在不同框架里都有对应物。

这四层里，路由层特别适合作为“标准化”的起点。原因很简单：路由对象的本质是“URL-配置-组件”的映射，这个映射关系在React和Vue里几乎是一模一样的。差别只在怎么把配置喂给框架、以及渲染组件时怎么调用框架的组件定义。把路由层做成标准化配置，再把薄薄一层适配器垫在框架下面，迁移成本能一下子降下来。

下面我们进入路由机制本身，看看它到底由哪几个零件构成，这也是后面写适配器的“地图”。

2. 一套可跨框架复用的路由抽象方案

2.1 路由机制底层拆解：history、location、matcher、renderer

不管React Router还是Vue Router，不管它包装得多花哨，底层都在干同一件事：监听浏览器地址变化，把URL变成结构化数据，再根据配置匹配出要渲染的内容。拆开来看，核心就四部分。

• history：负责和浏览器URL打交道。提供push、replace、go这些方法，还要监听popstate/hashchange事件。React Router和Vue Router都内置了web版本的历史实现，只是暴露的API名字和返回值不太一样。
• location：当前URL被解析后的结构化对象，至少包含pathname、search、hash，可能还有params、state。两个路由库都有一份自己的location，但字段命名并不完全相同。
• matcher：拿着用户配置的路由表，把当前location匹配成一条“激活”的路由记录。这块要处理动态段、通配符、嵌套路由、优先级，两个库的实现细节差异很大。
• renderer：匹配出结果之后，由框架负责把路由记录中的组件渲染到页面。React用的是element或Component字段，Vue用的是component字段，但最终都会落到各自的渲染函数上。

所以，你用React Router里的useLocation拿到的location，和Vue Router里useRoute拿到的route，虽然字段名不一样，但描述的是同一件事。理解了这个“四件套”，就会发现跨框架复用路由的突破口：只要我们自己定义一套中间格式，让React和Vue各自用适配器把这套中间格式翻译成自己的路由模型，大部分路由逻辑就能一次性写好。

这套中间格式就是标准化路由Schema。

2.2 用“路由配置Schema”屏蔽框架差异

我采用的方案是定义一份与框架无关的路由配置Schema。简单来说，就是一份TypeScript接口：

export interface RouteConfig { path: string; // 路径，支持动态段 /user/:id name?: string; // 路由名称 component?: () => Promise<unknown>; // 组件加载器，返回框架组件 meta?: Record<string, unknown>; // 权限、标题、过渡动画等自定义信息 children?: RouteConfig[]; // 嵌套路由 guards?: RouteGuard[]; // 框架无关的守卫函数数组 } export type RouteGuard = ( to: RouteContext, from: RouteContext, next: RouteNext ) => void | Promise<void> | RouteNext;

这里面最关键的设计是component字段。它没有直接存React组件，也没有存Vue组件，而是存了一个异步工厂函数。这个函数可以在React适配器里返回一个React.lazy(() => import(...))，也可以在Vue适配器里返回一个defineAsyncComponent(() => import(...))。也就是说，标准化层只负责约定“异步取一个组件”，具体取出来的是什么，由各框架适配器决定。

guards字段也很有意思。它不接受框架的路由守卫，而是接受一个纯粹的函数签名，接收一个标准化的RouteContext（我自己定义的、包含解析后参数和meta的上下文对象），返回一个可以控制跳转的结果。这样权限校验、登录判断这些通用逻辑，可以在两个框架里复用一套。

有了Schema之后，React端我自己写了一个createReactRouterFromConfig，Vue端写了一个createVueRouterFromConfig。两者做的事完全对称：把标准化配置转成各自路由表，再把标准化guard注册到对应的路由钩子里。从这以后，业务侧只需要维护一份routes.ts，剩下的交给适配器。React项目里那份几千行的路由配置，迁移时几乎不用改。

当然，这里有一个绕不开的问题：React Router和Vue Router对“组件”的接收方式不同。一个接收React Element，一个接收组件定义数组。如果不做标准化，只把路由表硬从React搬到Vue，那你需要把每一个element: <Dashboard />改成component: Dashboard，还要处理懒加载、嵌套等等，看起来是小活，但几十个页面下来就全是机械劳动。而标准化之后，这个改动被收敛到适配器的一个转换函数里，改一次，处处生效。

3. 实操：在某数据可视化系统中将React路由移植到Vue Router

3.1 项目背景与改造目标

具体说一个案例。有个某数据可视化系统，前端是React 18 + React Router v6 + Zustand + Vite，一共有四十多个页面，路由表分布在十几处嵌套路由里。因为团队后续想在部分业务线用Vue 3，所以决定先把核心业务逻辑和路由配置剥离出来，做一个跨框架移植验证。

改造目标定得很明确：不追求组件级复用，因为JSX和template的语法差异太大，硬啃HTML成本不划算；我们追求的是业务逻辑层和路由配置层能做到“迁移时一字不改”。也就是状态管理逻辑、权限判断、路由meta、数据预取这些代码，从React项目里拷到Vue项目里，不用再动逻辑。这个目标听起来不大，但做起来需要把每一条“框架人行道”都拆掉。

项目里最大的障碍就是路由。React Router v6惯用的写法是<Routes>嵌套加useRoutes()，权限判断分散在好几个高阶组件里；Vue Router这边是配置式routes数组加beforeEach钩子。两种模型看起来完全不同，如果不做标准化，光是把这四十个页面搬到Vue Router，就要一行行改路径、改组件引用、改懒加载，更别提把散落的鉴权逻辑收拢起来。

3.2 移植步骤详解：从React Router到Vue Router

整个移植过程我拆成了五步，每一步都蛮关键，我按顺序写一下。

第一步：把React Router的路由表提取成标准化RouteConfig。原来的React路由表长这样：

const routes = [ { path: '/dashboard', element: <Dashboard />, children: [ { path: 'analysis', element: <Analysis /> }, { path: 'users/:id', element: <UserDetail /> } ] } ];

我把它改写成标准化配置，element字段改成component异步工厂：

export const routes: RouteConfig[] = [ { path: '/dashboard', meta: { title: '工作台', needAuth: true }, component: () => import('../pages/Dashboard'), children: [ { path: 'analysis', component: () => import('../pages/Analysis'), meta: { title: '分析' } }, { path: 'users/:id', component: () => import('../pages/UserDetail'), meta: { title: '用户详情' } } ] } ];

注意这里的../pages/Dashboard是React组件，因为我们在React端。到了Vue项目里，这份配置同样能用，只要页面文件的相对路径能对应上。这就是异步工厂的好处：路径不变，组件可以用适配器解析成对应框架组件。如果某个页面在Vue端是单独写的SFC，那也只要把import路径换成../vue-pages/Dashboard.vue，其余结构完全不变。

第二步：写React适配器，把标准化配置转成React Router的createBrowserRouter可用的格式。简单说就是递归遍历RouteConfig，构造{ path, element, children, loader, shouldRevalidate }。这里我给出一个最小的递归转换逻辑：

import { createBrowserRouter } from 'react-router-dom'; import React from 'react'; function toReactRoutes(configs: RouteConfig[]): any[] { return configs.map(cfg => { const element = cfg.component ? React.createElement(React.lazy(cfg.component as React.ComponentType)) : null; return { path: cfg.path, element, children: cfg.children ? toReactRoutes(cfg.children) : [], loader: async () => { const ctx = createRouteContextFromLocation(window.location); const redirect = await runGuards(cfg.guards || [], ctx, {} as any); return redirect ? { __redirect: redirect } : null; }, }; }); } export const reactRouter = createBrowserRouter(toReactRoutes(routes));

loader只是其中一个接入点。如果你的React Router版本较老，也可以用beforeEnter（v6早期）或者在高阶组件里拦截，但逻辑是一样的：把标准化guards转换成React Router能识别的钩子。

第三步：写Vue适配器，把同一份配置转成Vue Router的createRouter可用的格式。Vue Router 4的格式是routes: [{ path, component, children }]，而且懒加载组件可以直接用() => import(...)。但注意，Vue Router的component字段不能直接接收() => Promise<React组件>——所以在Vue端适配器里要做一次转换：

import { createRouter, createWebHistory, defineAsyncComponent } from 'vue-router'; function normalizeComponent(loader: RouteConfig['component']) { if (!loader) return undefined; return () => loader().then(m => (m as any).default); } function toVueRoutes(configs: RouteConfig[]): any[] { return configs.map(cfg => ({ path: cfg.path, component: normalizeComponent(cfg.component), children: cfg.children ? toVueRoutes(cfg.children) : [], })); } export const vueRouter = createRouter({ history: createWebHistory(), routes: toVueRoutes(routes), });

如果你的页面文件是Vue SFC，那import()出来的是带default的模块，直接返回就行。如果某些页面用的是命名导出，就改成(m as any)[loaderName]。这个转换函数本质上是把标准化加载器翻译成Vue的懒加载函数。

第四步：统一路由守卫。原来的React项目里，权限校验写在若干组件内部或者路由beforeEnter里，散得不成样子。我全部捞出来，改成标准化的guard数组：

const authGuard: RouteGuard = async (to, from, next) => { const session = await getSession(); if (to.meta?.needAuth && !session.user) { next({ name: 'login', query: { redirect: to.fullPath } }); } else { next(); } };

然后在适配器里把authGuard注册进去。React端挂到loader或者shouldRevalidate，Vue端挂到router.beforeEach。这样权限判断函数本身，在两端项目里是同一份代码。我甚至把用户点击菜单、刷新页面、直接输入URL这三种进入方式都验证了一遍，确保守卫行为一致。

第五步：验证嵌套路由的基准路径。这里有个坑，后面会专门讲。总之要保证标准化RouteConfig里的children路径，在两个框架里拼接出来的最终URL一致。我们项目里最终把所有children path都强制改成不带开头/的相对路径，并且在适配器里做了一次递归检查，一旦发现绝对路径就输出warning。

到这步，React项目里的路由定义、路由守卫、权限逻辑，已经可以原封不动搬到Vue项目里了。组件层还是得重写，但数据层和路由层基本零成本迁移。

4. 路由守卫、懒加载与权限控制的跨框架实现

4.1 为什么路由守卫必须“框架无关”

很多人在迁移时最容易忽略的就是“路由守卫”。React Router v6.4之后推出了loader和action，TanStack Router有beforeLoad，Vue Router有beforeEach。它们名字不同，却都在回答同一个问题：在渲染目标组件之前，要不要拦一下、要不要预取一些数据、要不要重定向。

如果这层逻辑直接写在框架钩子里，那迁移时几乎等于重写。所以我强烈建议在标准化层设计一套“Guard Pipeline”。思路很简单，就是一个数组，按顺序执行：

async function runGuards(guards: RouteGuard[], to: RouteContext, from: RouteContext) { let redirect: RouteNext | undefined; for (const guard of guards) { let nextCalled = false; await guard( to, from, (arg) => { nextCalled = true; redirect = arg; } ); if (redirect) return redirect; } return undefined; }

别看完美，其实实现时要处理“是否调用next”的语义，不同路由库对这个概念的处理不太一样。我在React适配器里会把最终是否“重定向”的结果返回给loader或shouldRevalidate，在Vue适配器里则直接调用next(redirect)。但核心函数里的业务判断，一行都不用改。

当然，不同路由库的守卫触发时机并不完全一样。React Router的loader只会在路由匹配变化时触发，Vue Router的beforeEach每次导航都可能触发。为了尽量统一，我在标准化层做了一个“触发类型”标记，比如guards可以在onEnter、onUpdate、onLeave三种时机执行，适配器把自己能识别的时机映射过去。这个设计让同一个Guard在两个框架里能尽量对齐行为。

4.2 实现统一权限守卫的完整示例

我把上面提到的authGuard写完整一点，顺便展示它如何在两套框架里复用。

标准化层：

// route-guard.ts export const authGuard: RouteGuard = (to, from, next) => { const user = getCurrentUser(); const needAuth = to.meta?.needAuth === true; const allowedRoles = (to.meta?.roles as string[]) || []; if (needAuth && !user) { next({ name: 'login', query: { redirect: to.path } }); return; } if (user && allowedRoles.length && !allowedRoles.includes(user.role)) { next({ name: '403' }); return; } next(); };

React适配器注册的部分，在3.2的loader里已经示例过了。Vue适配器注册，可以在创建路由时统一加：

import { createRouter, createWebHistory } from 'vue-router'; const router = createRouter({ history: createWebHistory(), routes: toVueRoutes(routes), }); router.beforeEach((to, from) => { const ctx = createRouteContext(to.path, to.query, to.params, to.meta); return runGuards(routes[0].guards || [], ctx, from); });

这里我简化了一点：实际项目里不是直接取routes[0].guards，而是根据to.path找到匹配的RouteConfig，再把从父级到当前级的guards合并为一个数组。这样做是为了解决“嵌套路由守卫需要逐级叠加”的问题。

这样写完之后，业务侧只需要在routes.ts里给路由配上guards: [authGuard]，具体由哪个框架执行，适配器自己处理。在实际项目中，我们还加了一个meta.log，在守卫被拦截时统一输出日志，省得调试时到处找。

这里有个很重要的细节：Vue Router的beforeEnter只对当前路由有效，而React Router的loader会在匹配整个路由分支时都执行。如果你的权限校验必须从根路由开始逐级执行，最好在标准化层设计成“叠加所有嵌套路由的guards”，而不是只取当前路由的guards。我当时就栽在这上面，后面踩坑部分再说。

懒加载的跨框架处理也值得多写两行。React那边React.lazy需要组件模块是默认导出，Vue那边defineAsyncComponent默认也是找default。但实际项目里总有人写出import { Dashboard } from './Dashboard'这种命名导出的页面。我最终在两边适配器里都加了一个resolveModule函数，优先读default，读不到就读指定的导出名，这样至少能兼容大部分写法。

5. 踩坑实录：跨框架路由移植的5个典型问题

5.1 问题与解决方案速查表

这个表里的内容，大部分是我实际跑迁移时踩过的，写出来给后来人避坑。

补充一句，表格里“嵌套路由守卫重复执行”那条，是我这次迁移中遇到的最隐蔽的问题。React Router的loader在子路由匹配时，会沿着父级一层层执行，而Vue Router的beforeEach是全局级，beforeEnter是单级级。如果标准化层不做合并，就会出现React端守卫跑了三次、Vue端只跑了一次的情况。最终我的解决办法是在标准化Schema里增加了一个guardsMeta字段，合并所有父级guards后再调用runGuards，保证两边的真实执行次数一致。

5.2 几个移植时的备忘技巧

第一，路由配置的meta里多放点标准化字段，别偷懒。比如页面标题、是否鉴权、对应权限角色、埋点名称、过渡动画名称，全部写进meta。这样路由层就成了一个可被任何框架消费的“配置文件”，将来做权限系统、埋点系统、页面标题管理，都能直接用，不需要重新定义数据结构。

第二，适配器不要写太厚。跨框架移植最容易犯的错，是想在适配器里实现一堆框架特有功能，结果适配器越写越厚，最后比业务代码还难懂。正确姿势是：标准化层只做最通用的约定，框架特有功能（比如React Router的handle、Vue Router的alias）留在各框架的项目里单独补充，不要硬塞进公共Schema。

第三，一定统一路径拼接规则。React Router和Vue Router对“绝对路径”和“相对路径”的解析有一些微妙差别。我的建议是标准化RouteConfig里children的path只用相对路径（不带/开头），这样做出来的嵌套路由在两个框架里都能正确拼接。那些写绝对路径的老路由，迁移时优先改成相对路径。

第四，测试的时候不要只在开发模式跑。Vite开发模式下，import()懒加载的报错信息很友好，但构建后的路由懒加载分包大小可能差异很大。切框架之后，一定要看一次生产构建产物，确认路由级分包已经被正确切开，不然几十个页面打包成一个JS文件，首屏会很难受。

第五，如果可以，给适配器加一个“路由Schema校验器”。我用TypeScript的zod写了一个很小的校验函数，专门检查路径参数是否配对、meta是否必填、children嵌套是否超过五层这类问题。两边的适配器在启动时都会跑一遍校验，能省掉很多低级错误。

上面那些问题，都是我这次迁移里一个个撞出来的。最后说点我个人实际操作的体会。跨框架移植这件事，真正改变认知的是：你不需要把每个组件都变成“框架无关”，那是理想主义，不现实；你需要做的，只是把那些不长在UI上的东西——路由、状态、权限、数据请求——尽可能抽成纯逻辑。只要这些纯逻辑是标准化的，换框架时你就能保住项目最值钱的部分。我做完这次移植之后，最大的感触是路由机制远比想象中简单，它本质上就是“地址到组件的映射”加一层拦截器。谁能在你的技能栈里把这层映射和拦截器抽象好，谁就掌握了跨框架迁移的主动权。以后如果再遇到“要不要换框架”这种灵魂拷问，至少我们会更有底。