module-federation-examples 实战:用 @module-federation/nextjs-mf 搭建 Next.js SSR 全向联邦应用

原创2026-10-14 13:46:361,866 阅读
文章标签:示例工程微前端前端

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 充当“路由 ↔ 联邦模块”的映射表,例如:

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 联邦与纯客户端联邦的差异,这份示例与本文的配置拆解都可以作为直接参考起点。

登录后查看全文
module-federation-examples