企业官网建设流程全解析

先把结论放在前头：路由机制理解得越深，跨框架移植就越像做翻译而不是做重构。

我这些年接手过不少技术栈换血的项目，最典型的是把一套基于 Vue 的上古后台系统迁移到 React，后来又零零散散把一些 React 组件挪到过 Angular 项目里。每次第一眼看上去，两套代码长得完全不一样，组件写法不同、状态管理不同、甚至连目录风格都不同。但真的动手拆的时候会发现，真正能让你“少掉头发”的，不是哪个框架的 API 背得多熟，而是你有没有一套不依赖具体框架的标准化技能栈：语言能力、代码组织习惯、对路由状态机的理解、对权限和懒加载的抽象。尤其是路由这一块，它几乎是所有跨框架移植的“第一试金石”。

这篇文章不打算讲某个框架的入门教程，也不会给出一份“Vue 转 React 速查表”就完事。我想跟你聊的是：为什么我说标准化技能栈是跨框架移植的前提，路由机制在三个主流框架里到底对应什么，以及我踩过哪些坑之后总结出来的一套可复用移植流程。适合正在做技术选型迁移、微前端拆分，或者单纯想提升自己抽象能力的开发者参考。

1. 为什么标准化技能栈是跨框架移植的前提

1.1 技能栈不是工具栈，先把“标准化层”抽出来

很多团队在讨论技术栈时，动不动就说“我们用的是 Vue 技术栈”“我们团队是 React 技术栈”。这句话在日常沟通里没毛病，但如果你真的把它当成跨框架移植的出发点，会非常痛苦。因为 Vue 和 React 只是工具，真正的技能栈应该是你对 JavaScript 语言本身、模块化规范、组件通信方式、状态变化规律、路由导航模型、构建产物结构等一系列通用能力的综合掌握。

我拿一个实际例子来说。之前有个老项目用 AngularJS 写得挺乱，公司决定整体迁移到 Vue 3。刚开始大家信心很足，觉得 AngularJS 那种双向绑定和数据脏检查已经过时了，正好全部重写。结果做了两个月发现不对劲：因为团队把“迁移”理解成了“重写”，所有页面都要重做，连路由配置、菜单权限、标签页缓存这些非业务逻辑也全部重写了一遍，等于把原本可以复用的一部分“骨架能力”也扔掉了。

后来我把拆解方式改了一下，先不看框架，先把项目里那些不依赖框架的东西抽出来。比如路由的路径设计、菜单的层级结构、权限点的编码规则、接口返回的数据模型，先用普通 TypeScript 模块描述清楚，然后才针对 Vue 写适配层。那一次之后我才真正意识到，所谓标准化技能栈，不是在某个框架里熟练到什么程度，而是你能不能在框架之外建立一个“标准层”，然后让各个框架去适配这个标准层。

这个道理其实特别像开车。手动挡和自动挡是两种工具，但交规、方向盘、刹车油门的逻辑是通用的。一个老司机换辆车，熟悉几分钟就能上路，不是因为记住了每个档位的位置，而是因为他已经把“驾驶技能”抽象成了肌肉记忆。代码里也一样，只有把路由表、权限校验、组件注册方式这些公共能力抽出来，换框架才不会让你从零开始。

1.2 路由机制是移植的“第一试金石”

为什么单独把路由拿出来讲？因为在一个中后台系统里，路由几乎承担了所有“入口级”复杂度。它不只是 URL 和组件的对应关系，还牵扯到嵌套布局、登录拦截、权限判断、菜单高亮、标签页缓存、页面标题、面包屑、懒加载，甚至某些业务系统还会在路由切换时做埋点上报和动画过渡。

我记得一次给另一个团队做技术咨询，他们是把 React 项目迁移到 Vue。当时他们觉得先把页面组件全部移植过去就行，路由最后再改。结果真到了改路由那一步，发现页面的组件结构其实还好说，真正麻烦的是路由守卫里的权限判断：原来写在 React Router 外围封装组件里的逻辑，在 Vue Router 里根本没有一一对应的概念，你得理解 beforeEach 钩子的执行顺序才能把它塞进去。那一块卡了他们将近一周。后来我帮他们梳理了一套“路由守卫”的抽象，事情才顺起来。

所以我才说，路由机制是跨框架移植的试金石。如果一个人能不看官方文档就把当前项目的路由体系讲清楚：哪里是入口、哪里是守卫、哪里是懒加载、哪些页面共享布局，那他对这个项目的理解基本是合格的。反过来，如果只知道在页面组件里调用某个路由 hook，对其他东西一概不知，那大概率会在移植阶段翻车。

这个试金石同时也在考察团队的抽象能力：你能不能把业务路由规则和框架 API 解耦。能解耦，React 和 Vue 之间的差异就只是语法层面的；不能解耦，你就会被困在“Vue 思维”或“React 思维”里，走到哪里都觉得新框架不顺手。

2. 路由机制的核心模型：路由表、匹配器与渲染出口

2.1 几乎所有框架都离不开这三件套

我反复跟团队里的小朋友说，前端路由本质上是一个 UI 状态机。它做的事情无非三件：拿到当前浏览器地址，去一张“路径对应表”里找到应该渲染哪个组件，然后把这个组件放到页面上预先挖好的坑里。这张表叫路由表，查找过程叫匹配，那个坑叫渲染出口。

不管你是 Vue Router、React Router 还是 Angular Router，底层思路全都绕不开这三个东西。只不过每个框架管它们叫法不同、表现形式不同。我从这么多年的使用经验里总结了一张对照表，方便你在脑海里建立映射关系：

这三个东西有一个很典型的场景可以帮助你理解：假如你要实现一个“当前菜单高亮”的功能。理论上你需要知道当前 URL 匹配到了路由表里哪一项，然后拿着这个匹配结果去和菜单数据对比。框架不同，只是取“当前匹配项”的 API 不同，比如 Vue 里是route.matched，React Router 里是useMatches，Angular 里有ActivatedRoute。但你的项目逻辑，迁移时完全不需要改：还是要从“某个变量”里拿到当前路由的层级，然后去更新菜单状态。

这就是标准化技能栈的价值：你把“拿当前匹配层级”这件事抽象成一个函数，每个框架的适配层只负责实现这个函数，业务层根本感觉不到切换。

2.2 标准化路由配置的通用结构

为了做到抽象，第一步就是设计一份不依赖框架的路由配置结构。我一般会先定义 TypeScript 接口，把路由表应该包含哪些字段固定下来。通常我会用这样一组字段：

interface NormalizedRoute { id: string; path: string; component: string; children?: NormalizedRoute[]; meta?: { title?: string; auth?: boolean; roles?: string[]; keepAlive?: boolean; [key: string]: unknown; }; guards?: RouteGuard[]; lazy?: () => Promise<{ default: unknown }>; }

这里有两个地方是比较讲究的。

第一，component我用的是字符串，不是组件对象。很多人在写框架路由时直接component: () => import('./views/Dashboard.vue')，这在当时项目里很方便，但一旦你要跨框架移植，import的路径和组件注册方式就是两套体系。Vue 组件和 React 组件连 SFC 与 JSX 都存在差异，直接引用只会让配置层越沉越重。用字符串作为“组件 ID”，再通过每个框架适配器里的组件注册表去解析，就能把这种差异挡在外面。

第二，guards我用的是纯函数数组。Routers 内置的守卫执行时序各不相同，但你的项目规则很简单：某个路由需要登录、某个路由需要某种角色，或者某个路由跳转时需要记录一下来源页。这些规则本身是稳定不变的，完全可以写成不依赖框架的纯函数：入参是to和from的标准化对象，出参是“放行”或“重定向到某个路径”。适配层只需要在合适的时机调用这些纯函数。

这样做的好处是你得到了一份很干净、很好测试的静态路由表。你可以在 Node 环境里直接用单元测试跑一遍：路径对不对、meta 字段齐不齐、父级路由下有没有冲突的 path。这些工作在框架内部做起来反而不方便，因为在框架里路由和 UI 是绑定的，测试牵扯太多环境问题。

2.3 为什么先设计配置结构，再对接框架 API

很多人不习惯这种“先配置、后对接”的方式，觉得绕了一圈，最后还是要在框架代码里写createRouter或者createBrowserRouter，那不如直接写框架 API，省得维护两份东西。这想法在单框架小项目里没错，但只要你有一丁点跨框架迁移的预期，或者将来要接微前端，这个“绕一圈”就非常值得。

我经历过的几个踩坑项目，无一例外都是因为把业务规则写死在了框架的配置里。举个最直白的例子：Vue Router 的嵌套子路由，子级path默认是相对路径；React Router 的嵌套路由同样支持相对路径，但如果你在父级路由里混用了绝对路径，两边对“路径拼接”的规则就会产生差异。假如你直接在 Vue Router 里写了/parent/child，到 React 这边也照抄，然后发现子路由不生效，得花一大段时间排查，最后才发现是路径拼接规则和末尾斜杠处理不同。

如果我们先把路由表标准化成“父级 path 一律以/开头、子级 path 一律不带/、最终完整路径由适配层拼接”，那这个问题根本不会发生。因为你在业务层看到的永远是最小粒度、最明确的写法，框架的拼接癖好被适配层吸收掉了。

所以我的纪律很简单：**先问一下“我的路由表应该长什么样”，再问“React 里怎么写”，顺序绝对不能反。**先把标准层做稳，再去对接框架 API，结构上至少稳定。

3. 实操：跨框架移植中的路由迁移全流程

3.1 从 Vue 到 React：一份配置，两套渲染

来看一个我在实际项目里跑通过的操作流程。场景是把一套 Vue 3 + Vue Router 管理后台迁移到 React 18 + React Router v6，组件层面已经抽得差不多了，主要难点集中在路由层。

第一步，抽出路由配置。我先把原先 Vue Router 里散落的页面路由改写成上面那种标准化结构：

// routes.ts export const routes: NormalizedRoute[] = [ { id: 'dashboard', path: '/dashboard', component: 'dashboard', meta: { title: '工作台', auth: true }, children: [ { id: 'overview', path: 'overview', component: 'dashboard/overview' }, { id: 'analysis', path: 'analysis', component: 'dashboard/analysis' } ] }, { id: 'system', path: '/system', component: 'system', meta: { title: '系统管理', auth: true, roles: ['admin'] }, children: [ { id: 'user', path: 'user', component: 'system/user' }, { id: 'role', path: 'role', component: 'system/role' } ] } ];

注意这里component的值是一个逻辑 ID，不是直接引组件。后续每个框架的适配器会自己提供一套resolveComponent(id)方法，负责把 ID 映射到真正可渲染的组件上。

第二步，写 Vue 适配器。适配器要做的就是把标准化结构转换成 Vue Router 的createRouter需要的格式，同时补上一套组件映射表。

// adapter/vue.ts import { createRouter, createWebHistory } from 'vue-router'; import { routes } from '../routes'; const viewMap = { 'dashboard': () => import('@/views/dashboard/index.vue'), 'dashboard/overview': () => import('@/views/dashboard/overview.vue') }; function normalizeView(id: string) { return viewMap[id] || (() => null); } export function createVueRouter() { const vueRoutes = routes.map(route => ({ path: route.path, component: normalizeView(route.component), meta: route.meta, children: route.children?.map(child => ({ path: child.path, component: normalizeView(child.component), meta: child.meta })) })); return createRouter({ history: createWebHistory(), routes: vueRoutes }); }

第三步，写 React 适配器。React Router v6 使用createBrowserRouter或<Routes>，我一般用前者，因为它允许直接把路由配置和懒加载传进去，外面再用RouterProvider包起来，结构上更像一个独立的路由层。

// adapter/react.tsx import { createBrowserRouter, RouterProvider, Outlet } from 'react-router-dom'; import { Suspense, lazy } from 'react'; import { routes } from '../routes'; const viewMap = { 'dashboard': lazy(() => import('@/views/dashboard/index.jsx')), 'dashboard/overview': lazy(() => import('@/views/dashboard/overview.jsx')) }; function resolveView(id: string) { const Component = viewMap[id]; return ( <Suspense fallback={<div>loading...</div>}> <Component /> </Suspense> ); } function Layout() { return <Outlet />; } export function createReactRouter() { const reactRoutes = routes.map(route => ({ path: route.path, element: ( <BeforeEach routeMeta={route.meta}> {resolveView(route.component)} </BeforeEach> ), children: route.children?.map(child => ({ path: child.path, element: resolveView(child.component) })) })); return createBrowserRouter([ { path: '/', element: <Layout />, children: reactRoutes } ]); }

看这两份适配器的差异，你会发现真正在变的只有三件事：路由注册方式、组件解析方式、渲染出口标签。业务里写好的路由表和meta全都没动。这就叫“一份配置，两套渲染”。

3.2 嵌套路由与布局体系的移植

嵌套路由在中后台系统里基本是标配，它对应的真实场景是：“不管你在哪个业务模块里，外层都套着一套统一的布局，包含侧边栏、顶栏和内容区域；只有内容区域内部变化。”

在 Vue 里，外层布局通常是一个 父级组件，使用<RouterView />渲染子内容。而在 React Router v6 里，父级路由的element是这布局，里面用<Outlet />占位。从效果上看，两者完全一致，但迁移时经常因为一个细节踩坑：父子路由的path拼接规则。

我的建议是：标准化配置里强制规定，path的规则分为两种，父级必须以/开头，并且域名只写到父级这一层；子级一律是相对路径，不写/。这样适配器拼接时不会有歧义。

解释一下为什么要这么做：比如父级是/dashboard，子级如果写成overview，最终就是/dashboard/overview；但如果你子级写成/overview，有些框架的拼接结果是/overview，完全脱离了父级，页面就跑到别的模块去了。一旦你手滑多写一个斜杠，页面不是 404 就是渲染错位。我在项目里见过最离奇的 bug 就是菜单详情配置和路由详情长得一模一样十来个页面，排查半天最终发现只是子路由 path 前多了一个符号。

所以标准化配置里，子级 path 的规定就是“只写相对路径，不带斜杠”。适配器如果发现不合规就直接报错，不要默默容忍。这样在项目的骨架层就把潜在问题拦住了。

3.3 路由守卫与拦截机制的等价替换

这块应该是跨框架移植里最经典的话题了，因为 Vue Router 和 React Router 对“跳转前拦截”的暴露方式完全不同。Vue Router 提供了全局前置守卫beforeEach、全局解析守卫beforeResolve、全局后置钩子afterEach；React Router 在 v6 版本之前也提供了onEnter，但在 v6 里基本废除了这种“路由配置式”的守卫，转而倡导在组件内部通过useEffect和useLocation实现拦截。

很多从 Vue 转 React 的人在这里会很不适应，总觉得“React 连个路由守卫都没有，真难用”。但实际上你只要想清楚守卫的本质，就知道它其实是一种“在渲染组件之前的导航拦截”：你拿到目标路由信息，做一系列检查，然后决定继续跳还是重定向。这个逻辑是通用的，只是框架负责调用它的时机不同。

标准化做法是定义一组纯函数守卫：

type RouteGuard = (context: { to: NormalizedRoute | null; from: NormalizedRoute | null; meta: Record<string, unknown>; auth: { isLogin: boolean; roles: string[]; }; }) => { allow: boolean; redirect?: string };

每个路由在路由表里都声明自己需要哪些守卫。适配器拿到这份配置后，分别往两个框架的机制里塞：

• Vue 适配器里，把这些守卫合并到beforeEach里，逐个执行，遇到redirect就调用next({ path: redirect })。
• React 适配器里，因为没有全局beforeEach，我会把守卫逻辑放在一个包裹组件BeforeEach里，它会在路由切换时获取当前meta并执行同样的纯函数，如果发现需要重定向，就调用useNavigate，并且不渲染子组件，避免页面闪烁。

这里有一条重点经验：守卫的执行时机不同，会导致状态获取的时机也不同。比如在 Vue 里，你在beforeEach里可以同步访问全局状态管理库，比如 Pinia，而且此时根组件已经创建，状态读取一般没问题。但在 React 里，如果你的BeforeEach组件是在RouterProvider内部的，那它执行渲染时可能还没完成权限初始化。我遇到过刷新页面时权限数据没到位，守卫生生把已经登录的用户弹回登录页的情况。解决方案是：在守卫组件里加一个waiting状态，等待权限数据初始化完成后才执行守卫判断，或者干脆把权限加载逻辑再提前，挪到路由渲染之前。

3.4 懒加载与组件注册中心的差异

懒加载也是容易出戏的地方。Vue Router 里写component: () => import('./xx.vue')是自带异步组件能力的，React 里则需要配合React.lazy和Suspense才能看到 loading 效果。迁移时如果你只是在适配器里把普通组件return出去，React 会提示你Element type is invalid，然后整个页面白屏。

更稳妥的做法是把组件注册中心单独封装。我在前面适配器里写到的viewMap，本质上是一个注册中心，它记录了componentId -> 加载函数。这样标准化路由表完全不关心加载细节，只传字符串，适配器再通过注册中心拿到真正的组件。换框架时只需要换注册表里的实现方式，路由配置不用动。

我后来在项目里甚至把注册中心做成了脚本扫描的，自动读取views目录下所有页面，按照目录结构生成映射表。这样新增页面时不需要手工改路由注册表，路由配置里只要写对了路径，适配器就会自动找到对应组件。虽然这个方案有一点黑科技味道，但对迁移期间动辄几十上百个页面的项目来说，能省下大量时间。

4. 常见问题排查与避坑实录

4.1 路由路径对不齐，页面 404

这是跨框架移植里出现频率最高的问题。表现形式非常统一：原来项目里一切都好，迁移后点某个菜单，路由地址变了，页面提示 404，或者干脆白屏。

排查看几个点：

• 父级路径末尾是否有斜杠。很多框架对/system和/system/的处理态度不一样，标准化配置里最好明确规定不允许带尾斜杠。
• 子级路径是否带了绝对前缀。按照前面的约定，子级必须是相对路径。
• 路由表顺序是否颠倒。Vue Router 和 React Router 在做路径匹配时，如果你有两个相似路径如/user/:id和/user/new，顺序不同可能会导致不同的匹配结果。React Router 通常会把更大的权重放在静态结点上，但也别太过迷信，尽量把更具体的路由放在前面。
• 路由大小写问题。Linux 环境下面，URL 路径是区分大小写的，模块路径也是区分大小写的。迁移时如果原来组件叫system/user，新项目里注册中心写成了system/User，就会报“找不到模块”或空白页。

我通常会在 CI 里加一个路径自检脚本：遍历标准化路由表，把所有完整路径拼出来，然后拿去和路由表匹配器做一次反向解析，解析不出来就挂掉构建。这样路径问题在提交阶段就能解决，而不是上线之后靠用户反馈。

4.2 懒加载与动态 import 的差异

迁移 React 项目时，最容易忘掉Suspense。如果你在createBrowserRouter的配置里直接放了一个lazy组件，外面没有包Suspense，React 会抛错，页面卡在加载中。在 Vue 里因为 Vue Router 自带的组件解析机制，很多时候不显式写Suspense也不会出问题，顶多没有 loading 效果。所以很多 Vue 出身的人会在 React 里踩坑。

我的心得是：在标准化适配器里统一处理，不要在业务层写lazy。也就是说，业务侧只提供一个能返回Promise的函数，适配器内部判断这个函数存在，就在 React 适配器外面包Suspense，在 Vue 适配器里则直接交给异步组件处理。业务层永远不需要感知框架的懒加载差异。

另外还要注意，不同的打包器对动态 import 的拆分规则不同。同样在适配器里写组件加载函数，Vite 会按目录拆分 chunk，React 项目用 Webpack 时则要看chunkFilename和魔法注释。迁移时如果遇到“首页正常，深层页面半天加载不出来”的问题，可以去网络面板确认 chunk 是不是加载失败了，多数情况是打包产物路径或publicPath有问题。

4.3 权限守卫的“时序坑”

我前面提到过刷新页面时权限数据没初始化导致被踢回登录页，这个值得单独列一条。

具体场景是这样的：标准化路由表里给某个页面配置了auth: true，守卫函数里判断auth.isLogin是否为 true。在 Vue 的beforeEach里，如果我们把权限初始化的 Promise 放到router.beforeEach之前执行，那刷新页面时因为路由监听还没开始，所以数据可以先等一步。但把代码迁移到他 React 的BeforeEach包裹组件中后，渲染时机早于异步数据初始化，于是第一次渲染就会带着“未登录”状态执行守卫，结果直接跳到登录页。

这个问题在本地开发时很难发现，等你部署到线上，用户刷新页面就批量复现，属于那种很让人心梗的 bug。解决方案有两个：一是在BeforeEach组件里用useEffect监听 auth 状态，数据未就绪时返回 loading；二是把权限初始化提前到应用入口，在渲染RouterProvider之前await initAuth()。

我倾向于使用第二种，因为思路更接近 Vue 的全局前置逻辑。它相当于把“进入任何路由之前必须先初始化权限”这条规则固化在应用启动流程里，不管以后前端换成什么框架，约束都成立。

4.4 滚动恢复、查询参数保留等细节

中后台系统迁移时，还有几个让人觉得“没问题但其实问题不小”的细节。

第一个是滚动恢复。Vue Router 自带了scrollBehavior，React Router 的createBrowserRouter也提供了scrollRestoration，但默认行为不一定完全一致。如果你原先页面切换后能自动回到顶部，迁移后却停留在上一次滚动位置，用户会觉得页面卡住了。我的标准化做法是在适配器里统一包一层ScrollToTop组件，路由变化时重置滚动到顶部，然后再根据各框架的能力叠加“恢复历史位置”的逻辑。

第二个是查询参数保留。比如原项目里列表页跳详情页时用了?from=search这种参数，迁移时如果某个地方用了router.push而没带完整 query，就会丢失来源标记，导致详情页的“返回”按钮行为异常。我在做迁移时会把所有“跳转行为”梳理成一个跳转方法集，统一走封装函数：传入path和query，由适配层拼接成目标地址。这么做的好处是，将来换框架时，业务代码里不会出现裸的useNavigate或router.push，替换面就很小。

4.5 我踩过几次坑之后的心得速查表

最后给你一份我在跨框架路由迁移过程里用到的自检清单，不一定多高深，但很管用：

5. 关于“标准化技能栈”这件事的最后一句话

做了这么多跨框架迁移，我最大的感受就是：你的技能栈不应该长在某个框架上，而应该长在那些几十年都不会变的东西上。JavaScript 语言规范会变，但模块化思维不会；React 和 Vue 的 API 会变，但“路由表 + 匹配器 + 渲染出口”这个模型不会；状态管理库会一个接一个地冒出来，但“单一数据源 + 单向数据流”的思考方式不会。

所以你在新项目里，哪怕觉得“这辈子都不会换框架”，我也建议你在应用外围加一个薄薄的适配层，至少把路由配置抽成一个独立的纯数据模块。这件事的成本很低，可能只是一个文件、一个接口定义，但收益会在未来某天你不得不做框架升级、做微前端拆分、做页面级重构时成倍放大。路由机制看似只是技术知识里的一个小点，实际上它是最能检验一个人是否具备“站在框架之上看问题”能力的地方。先把路由想明白，其他层的跨框架移植基本就是手到擒来。

如果你正在准备做技术栈迁移，我的建议是不要急着开新分支复制页面，先花两天时间把路由规则、守卫规则、懒加载规则整理成一份和框架无关的文档，然后让团队里两个人分别用 Vue 和 React 各自实现一版适配器。这个过程会把大部分风险提前暴露出来，也比你在迁移后期手忙脚乱强得多。毕竟，翻译一篇文章永远比重新写一篇文章容易，前提是你得先有原文。