module-federation-examples 实战:用 @module-federation/nextjs-mf 搭建 Next.js SSR 全向联邦应用
module-federation-examples 实战:用 @module-federation/nextjs-mf 搭建 Next.js SSR 全向联邦应用
导读
本篇以仓库中 nextjs-ssr/README.md 为骨架,深入拆解一个由 checkout、home、shop 三个 Next.js 应用组成的 SSR 模块联邦示例:三个应用彼此互为 Host 与 Remote,通过 @module-federation/nextjs-mf 插件实现页面级、组件级的双向联邦与全向路由,并借助插件底层的 Software Streams 机制在服务端运行时流式共享 CommonJS 模块。读完本文,你将掌握该示例的启动方式、三个应用的端口与角色划分、next.config.js 中 NextFederationPlugin 的完整配置写法、服务端/客户端双路径 remoteEntry 的区分逻辑,以及 SSR 场景下模块联邦的安全边界与依赖共享约束。
前置说明:该示例 README 顶部注明 Next.js 的官方支持正在收尾(
Support For Next.js is ending),当前仓库版本锁定@module-federation/nextjs-mf@8.8.56与next@^14.2.35,文中所有配置均以此版本为准。
三个 Next.js 应用:全向联邦的拓扑结构
该示例由三个独立的 Next.js 应用组成,定义于 nextjs-ssr/package.json 的 workspace 过滤规则(nextjs-ssr_*)以及 playwright.config.ts 的启动配置中:
| 应用 | 端口 | 目录 | 在联邦中的角色 |
|---|---|---|---|
| checkout | 3000 | nextjs-ssr/checkout | 消费 home、shop;暴露 ./title、./checkout、./pages-map |
| home | 3001 | nextjs-ssr/home | 消费 checkout、shop;暴露 ./nav、./home、./pages-map |
| shop | 3002 | nextjs-ssr/shop | 消费 home、checkout;暴露 ./shop、./pdp、./pages-map |
从源码结构看,三个应用内部保持着高度同构的目录布局:每个应用都有 components/、pages/、pages-map.js、next.config.js。README 中明确描述其特性为“omnidirectional routing”,即全向路由——任意一个应用都可以像 SPA 一样消费另外两个应用暴露的页面或组件。以 nextjs-ssr/home/pages/shop.js 为例,home 直接以 import ShopPage from 'shop/shop' 的方式把 shop 的结账页当作本地页面渲染:
import ShopPage from 'shop/shop';
const Shop = ShopPage;
Shop.getInitialProps = ShopPage.getInitialProps;
export default Shop;
README 特别强调:全向路由已经接入 webpack federation 的加载函数,因此当动态加载 remote 时,可以复用 webpack 在“已知静态导入”(如 home/title)场景下加载 remote 的同一套函数,这也是页面联邦能够像普通 SPA 路由一样无缝切换的基础。
快速启动与验证
在仓库根目录完成依赖安装后,进入 nextjs-ssr 目录执行 README 给出的启动命令:
pnpm run start
该命令实际映射为 nextjs-ssr/package.json 中的 pnpm --parallel --filter nextjs-ssr_* dev,即并行启动三个应用的开发服务器。随后可以访问:
http://localhost:3000(checkout)http://localhost:3001(home,README 推荐的入口)http://localhost:3002(shop)
每个应用都带有共享导航(Home / Shop / Checkout),点击任意链接即可跨应用跳转到联邦页面。除了开发模式,仓库还提供了构建与生产运行脚本:
pnpm run build # 并行执行三个应用的 next build
pnpm run serve # 并行执行三个应用的 next start
值得注意的是,三个应用的 package.json(如 nextjs-ssr/home/package.json)在 dev / start 脚本中设置了 NEXT_PRIVATE_LOCAL_WEBPACK=true,并分别以 -p 3001、-p 3002 指定端口(checkout 使用默认 3000),这保证了模块联邦插件能挂载到 Next.js 本地 webpack 实例上。
核心配置:NextFederationPlugin 的完整形态
三个应用的 next.config.js 采用同一套配置范式,其中 checkout 的配置最具代表性:
const NextFederationPlugin = require('@module-federation/nextjs-mf');
// this enables you to use import() and the webpack parser
// loading remotes on demand, not ideal for SSR
const remotes = isServer => {
const location = isServer ? 'ssr' : 'chunks';
return {
home: `home@http://localhost:3001/_next/static/${location}/remoteEntry.js`,
shop: `shop@http://localhost:3002/_next/static/${location}/remoteEntry.js`,
};
};
module.exports = {
webpack(config, options) {
config.plugins.push(
new NextFederationPlugin({
name: 'checkout',
filename: 'static/chunks/remoteEntry.js',
dts: false,
exposes: {
'./title': './components/exposedTitle.js',
'./checkout': './pages/checkout.js',
'./pages-map': './pages-map.js',
},
remotes: remotes(options.isServer),
shared: {},
extraOptions: {
exposePages: true,
},
}),
);
return config;
},
};
该配置的关键点可以拆解如下:
remotes(isServer)与服务端/客户端双路径:函数接收 webpack 编译时的options.isServer,据此拼接_next/static/ssr/remoteEntry.js(服务端)或_next/static/chunks/remoteEntry.js(客户端)作为远端入口地址。这是 SSR 联邦的关键细节——同一份代码在两端拉取不同形态的 remoteEntry。README 注释也提示,按需import()加载 remote 的方式“not ideal for SSR”,与全量预加载静态依赖存在取舍。name与filename:name: 'checkout'声明自身联邦模块名,其他应用通过该名字引用;filename: 'static/chunks/remoteEntry.js'固定了客户端 remoteEntry 的输出位置。exposes与页面暴露:除组件外,还直接暴露页面文件(如./pages/checkout.js)以及./pages-map.js。extraOptions.exposePages: true:这是页面联邦的开关,配合 pages-map 把 Next.js 路由声明为可被远程消费的入口。shared: {}:示例中显式留空。README 明确指出,Next.js 内部模块已由插件预共享,开发者只需通过插件分享 react 即可满足 share scope 的运行时要求;额外共享的代码会经插件重新编排,以适配 Next.js 的限制。
home 与 shop 的 next.config.js、nextjs-ssr/shop/next.config.js 结构一致,只是 name、exposes 与 remotes 各自指向另外两个应用,三者两两互联形成闭环。
pages-map:如何把路由暴露成联邦入口
每个应用根目录下的 pages-map.js 充当“路由 ↔ 联邦模块”的映射表,例如:
- nextjs-ssr/home/pages-map.js:
{ '/': './home' } - nextjs-ssr/checkout/pages-map.js:
{ '/checkout': './checkout' } - nextjs-ssr/shop/pages-map.js:
{ '/shop': './shop', '/p/*': './pdp' }
shop 的映射支持通配路径 /p/*,对应其暴露的 nextjs-ssr/shop/pages/p/[...slug].js(PDP 动态详情页,通过 useRouter 读取 slug 参数渲染)。也就是说,pages-map.js 是 extraOptions.exposePages 生效的数据源:远端据此知道“哪些路由可以跨应用被引用”,Host 端据此在导航到 /shop、/p/1 等路径时定位到对应联邦页面。
页面与组件的跨应用消费模式
顶层布局:远程导航组件
三个应用的 _app.js 都通过 lazy(() => import('home/nav')) 消费 home 暴露的导航组件,并用 Suspense 包裹。例如 nextjs-ssr/checkout/pages/_app.js:
const Nav = lazy(() => {
console.log(import('home/nav'));
return import('home/nav');
});
而 nextjs-ssr/home/pages/_app.js 与 nextjs-ssr/shop/pages/_app.js 则直接 import Nav from '../components/nav' 使用本地导航,或同样懒加载远程 home/nav。远程导航组件本身(nextjs-ssr/home/components/nav.js)内部还用 lazy 包裹了本地组件 helloWorld,展示了组件级懒加载与 Suspense 的嵌套用法。
页面级联邦:getInitialProps 透传
Home 消费 checkout 暴露的结账页时(nextjs-ssr/home/pages/checkout.js),不仅把远程组件当成本地默认导出,还透传了它的 getInitialProps:
import CheckoutPage from 'checkout/checkout';
const Checkout = CheckoutPage;
Checkout.getInitialProps = CheckoutPage.getInitialProps;
export default Checkout;
这一模式在三个应用的所有联邦页面中重复出现(如 nextjs-ssr/shop/pages/checkout.js、nextjs-ssr/checkout/pages/shop.js、nextjs-ssr/home/pages/p/[...slug].js)。其意义在于:远程页面在服务端预取数据(getInitialProps)的能力被完整保留,SSR 场景下宿主页面可以拿到远端页面的数据后再渲染。
被消费的远端页面同样支持两种数据获取范式:checkout 页面使用 getInitialProps(见 nextjs-ssr/checkout/pages/checkout.js,返回 { test: 123 } 并在页面中 JSON 展示),而 shop 页面使用 getServerSideProps(见 nextjs-ssr/shop/pages/shop.js),说明该示例同时兼容两类服务端数据获取 API。
组件级消费:跨应用 React.lazy
Home 首页(nextjs-ssr/home/pages/index.js)通过 lazy(() => import('checkout/title')) 消费 checkout 暴露的 exposedTitle 组件,并用 Suspense fallback={'loading remote title'} 兜底;远端组件 nextjs-ssr/checkout/components/exposedTitle.js 内部使用了 useEffect(README 强调通过 hooks 避免服务端或客户端作用域内加载多份 react),并带有 CSS Modules 样式(sample.module.css)。
服务端渲染的底层机制:Software Streams
README 用较大篇幅介绍了该示例 SSR 能力背后的专有技术 Software Streams:它能够在运行时把 CommonJS 模块“流式”推送给消费方应用。要点如下:
- SSR 如何工作:服务端渲染正是依赖 Software Streams 在运行时流式共享模块;客户端侧则使用增强的 federation 接口(enhanced federation interfaces),保证顶层 API 行为符合预期。
- 支持的导入语法:README 声称应能支持
import()、require、import from三种形式,其中服务端已充分测试,客户端除import()外尚未验证其他形式。 - 历史与现状:一个半年前泄露的 alpha 版本虽然可用,但存在多处安全缺陷;federation 团队已在流式传输的强化上投入了大量工作。
- 适用边界:README 强烈建议现阶段只在这类技术信任的服务器之间联邦可信软件,不要传播到不可信环境。
从源码侧观察,服务端流式模块的落地体现在两处:一是 remotes(isServer) 函数把服务端 remoteEntry 指向 _next/static/ssr/remoteEntry.js;二是自定义 _document.js(nextjs-ssr/home/pages/_document.js)从 @module-federation/nextjs-mf/utils 引入 revalidate、FlushedChunks、flushChunks,在文档初始化阶段冲刷联邦 chunk,并把 FlushedChunks 注入 <head>——这正是服务端把已流式获取的远程模块产物正确输出到 HTML 的关键环节。
安全边界:保护 _next/static/ssr* 路径
README 的安全章节是该示例最具实战警示价值的部分,必须原样保留并展开:
- 为了让插件开箱即用,CommonJS 模块会被暴露在
_next/static/ssr*路径下。 - README 强烈建议通过 CDN 或中间件,只允许内网或 VPN 访问该路径,公共互联网不应触达。
- 原因在于:这里暴露的是服务端代码,而
process.browser不会作用于服务端代码,因此不会摇树掉服务端机密(如环境变量、密钥等)。 - 简言之,一旦
_next/static/ssr*对公网开放,等于把含敏感逻辑的 SSR 产物直接交给攻击者分析。
从配置侧印证:remotes(isServer) 中服务端地址固定为 _next/static/ssr/remoteEntry.js,这正是 README 所述“暴露路径”的具体形态。部署时应在网关层对该前缀做网络白名单,或参考插件后续版本的安全强化手段。
依赖共享机制与 Next.js 的异步边界限制
README 在 Sharing 章节解释了该示例的共享模型:
- 预共享内部模块:Next.js 的所有内部模块由
@module-federation/nextjs-mf预先共享,并以运行时挂载的方式附加到 share scope(因为 Next.js 内部模块无法像普通模块一样参与常规共享流程)。 - 必须显式共享 react:开发者仍需通过插件分享 react,以满足 share scope 的运行时要求;除此之外的额外共享代码会由插件重新配置共享方式,使其适配 Next.js 的限制。
- 共享上限的根因:Next.js 没有异步边界(async boundary),因此在 webpack 编排 share scope 的过程中无法“暂停”应用,这直接限制了可共享模块的规模与形态。
- 演进方向:README 透露作者正在研究解决 Next.js 模块共享问题的新方法,但这是一个复杂问题,需要深入理解 webpack 与 federation 在模块图内部的工作原理。
这与普通 webpack 联邦应用(可通过 shared 数组声明依赖、由运行时按需解析)形成鲜明对比,解释了为什么该示例的 shared: {} 为空且依赖插件预共享——这是 Next.js 运行时模型下的必要妥协。
未来方向:流加密与 WASM 隔离
README 对插件脱离 beta 后的演进计划做了前瞻性说明,属于文档明示的项目事实:
- 流式传输加密(Stream Encryption):计划为流式传输的代码构建加密能力,确保被推送的代码未经篡改;加密将依赖一个 consumer 与 remote 在构建时约定的加盐密钥(salted cipher key)。
- WASM 沙箱隔离:正在调研将流式软件运行在 WASM 隔离环境中,使其无法访问宿主资源、无法造成破坏,从而允许执行不可信代码。
- 现阶段结论:在以上能力落地前,只应在互信服务器之间联邦代码。
端到端验证:Playwright 测试覆盖
该示例带有完整的 Playwright 测试,可用于验证上述全向路由与联邦页面是否按预期工作:
- 测试文件 nextjs-ssr/e2e/checkNextjsSsr.spec.ts 以
appsUnderTest数组覆盖三个应用(3000/3001/3002),对每个应用分别验证:Home 页渲染共享导航(Hello World文本与导航链接)、渲染联邦内容(来自 checkout 的“This came fom checkout !!!”标题、来自 shop 的联邦文案)、以及跨页面导航流程(点击导航后 URL 断言)。 - nextjs-ssr/playwright.config.ts 通过
webServer数组以pnpm run --filter nextjs-ssr_* dev并行拉起三个应用,baseURL指向http://localhost:3001。 - 运行方式:在
nextjs-ssr目录执行pnpm test:e2e(即npx playwright test),或执行pnpm e2e:ci(先构建再跑测试)。
测试中使用的文案与断言数据统一维护在共享测试基建中(playwright-e2e/fixtures/constants.ts 中的 nextJsSsrApp 常量),测试数据文件为 playwright-e2e/fixtures/nextjsSsr.json。关于如何编写与运行仓库级 e2e 测试,README 同时推荐参考 playwright-e2e/README.md,其中说明了从仓库根目录执行 pnpm exec playwright test --config <sample>/playwright.config.ts 或 pnpm --filter <sample-name> e2e:ci 的通用流程。
小结
nextjs-ssr 示例完整展示了在 Next.js 中落地 SSR 模块联邦所需的全部要素:@module-federation/nextjs-mf 的插件配置、ssr/chunks 双路径 remoteEntry、pages-map.js 驱动的页面联邦、getInitialProps 透传的 SSR 数据流、以及 Software Streams 支撑的服务端运行时模块共享。同时它也划清了实践边界:共享依赖受限于 Next.js 无异步边界、_next/static/ssr* 必须内网隔离、现阶段只联邦可信代码。无论你是要在现有 Next.js 应用中引入微前端,还是想理解 SSR 联邦与纯客户端联邦的差异,这份示例与本文的配置拆解都可以作为直接参考起点。