微前端实践：如何让子项目脱离 React Router，优雅支持主项目的 Next.js 路由系统？

在微前端、多模块系统或模块联邦架构中，常见的一个问题是：

子项目是 Vite + React + React Router 构建的组件库，主项目是 Next.js，如何处理 Link 路由跳转？

如果子项目中大量使用了 React Router 的 <Link> 组件，部署到 Next.js 主项目中时就会报错：

 

Uncaught TypeError: Cannot destructure property 'basename' of 'React.useContext(...)' as it is null.

 

这是因为子项目依赖了 BrowserRouter 上下文，而主项目并没有提供这个 context。

那该怎么办？本文将讲清楚：如何将 <Link> 抽象为“注入式组件”，实现路由系统解耦，达到“UI 组件独立 + 路由行为由主项目控制”的目的。

---

❌ 错误做法：子项目自行包裹 <BrowserRouter>

许多开发者尝试在子项目中包裹：

<BrowserRouter> <App /> </BrowserRouter>

这样虽然可以让 <Link> 不报错，但在主项目（尤其是 SSR 的 Next.js）中引入后会产生：

• ✅ 不可控的 History 实例

• ❌ 无法与主项目共享路由

• ❌ 地址栏行为混乱

• ❌ SSR Hydration mismatch（首次渲染时 HTML 内容对不上）

---

✅ 正确做法：将 <Link> 抽象为“注入式组件”

🎯 核心理念

子项目不再直接使用 <Link>，而是通过 props.linkComponent 或 Context 注入方式，将导航行为交由主项目决定。

---

🔧 Step by Step：组件注入式解耦方案

✅ 第一步：定义 linkComponent props

 

type LinkProps = { href: string; children: React.ReactNode; className?: string; onClick?: () => void; }; type MyCardProps = { linkComponent: (props: LinkProps) => JSX.Element; };

 

---

✅ 第二步：子项目组件中使用注入的 linkComponent

 

export function MyCard({ linkComponent }: MyCardProps) { const Link = linkComponent; return ( <Link href="/product/123" className="text-blue-600 hover:underline"> 查看商品详情 </Link> ); }

 

---

✅ 第三步：在主项目中注入具体实现

🟦 在 React Router 项目中：

 

import { Link as RouterLink } from 'react-router-dom'; <MyCard linkComponent={({ href, ...rest }) => <RouterLink to={href} {...rest} />} />

 

🟪 在 Next.js 中：

 

import NextLink from 'next/link'; <MyCard linkComponent={({ href, children, ...rest }) => ( <NextLink href={href} {...rest}> {children} </NextLink> )} />

 

✅ 第四步：加入BrowserRouter

✅ 最小本地调试示例（Vite 子项目）

🔧 main.tsx（或 main.jsx）

import React from 'react';
import ReactDOM from 'react-dom/client';
import { BrowserRouter, Link as RouterLink } from 'react-router-dom';
import MyCard from './MyCard'; // 你的组件文件 

const App = () =>

  (<MyCard linkComponent={({ href, children, ...rest }) => (<RouterLink to={href} {...rest}> {children} </RouterLink>)} />);

ReactDOM.createRoot(document.getElementById('root')!).render(<BrowserRouter> <App /> </BrowserRouter>);

 

 

---

🚀 Bonus：抽象整个 Routing Context（进阶）

如果子项目中还用到了 useNavigate() 等跳转逻辑，我们可以统一抽象为：

 

type RoutingContextValue = { linkComponent: (props: LinkProps) => JSX.Element; push: (path: string) => void; }; const RoutingContext = React.createContext<RoutingContextValue | null>(null); export const useRouting = () => { const ctx = useContext(RoutingContext); if (!ctx) throw new Error('RoutingContext not provided'); return ctx; };

 

然后子项目中统一使用：

 

const { push, linkComponent: Link } = useRouting(); return ( <Link href="/profile">我的主页</Link> ); // 或跳转 <button onClick={() => push('/checkout')}>结账</button>

 

主项目注入：

 

<RoutingContext.Provider value={{ push: (url) => router.push(url), linkComponent: ({ href, ...rest }) => <NextLink href={href} {...rest} />, }} > <SubApp /> </RoutingContext.Provider>

 

---

✅ 总结

方案	是否推荐	说明
子项目包 BrowserRouter	❌	会和 Next.js 路由系统冲突
主项目包 MemoryRouter	⚠️	勉强可行，但无地址栏联动
抽象 linkComponent 注入	✅	通用、安全、强扩展性
使用 RoutingContext 管理跳转	✅✅	推荐：支持 Link 和 push() 双能力

 

---

🧠 适用场景

• 多项目整合

• 微前端架构

• 模块联邦（Module Federation）

• 任意非同源路由系统整合（如 Vue 主项目 + React 子项目）

---

🧩 最终收益

• 子项目可独立运行（本地包 BrowserRouter）

• 子项目可被 Next.js / Vue / 原生项目安全嵌入

• 组件逻辑纯粹，UI 与行为彻底解耦

• 未来支持 SSR、CSR、SPA 多种模式