Angular Universal SSR 与 Module Federation 实战:基于 module-federation-examples 的双端联邦构建解析

原创2026-10-14 11:37:311,669 阅读
文章标签:示例工程微前端前端

Angular Universal SSR 与 Module Federation 实战:基于 module-federation-examples 的双端联邦构建解析

本文基于 module-federation-examples 仓库中的 angular-universal-ssr 示例,讲解如何用 Angular 15(Angular Universal + @nguniversal/express-engine)与 webpack 5 ModuleFederationPlugin 构建一个「宿主应用做服务端渲染、远程应用以联邦方式提供 Angular 模块与组件」的完整系统。读完本文,你将掌握:Angular 应用在浏览器端与 Node.js 端分别为 Module Federation 生成两套构建产物的方法、远程模块如何作为懒加载路由被宿主消费,以及 shared 依赖(@angular/core 等)在 SSR 场景下的 singleton 配置策略。

示例结构:host-app 与 client-app 的分工

该示例位于 angular-universal-ssr/ 目录,由两个 pnpm workspace 子包组成(见 angular-universal-ssr/package.json):

  • client-app(包名 angular-universal-ssr_client-app):联邦远程(remote)应用。它既是一个可独立访问的静态站点,又通过 ModuleFederationPlugin 对外暴露一个组件(./Component)和一个完整的 Angular 模块(./Module)。它由 serve 以纯静态方式运行,不做服务端渲染。
  • host-app(包名 angular-universal-ssr_host-app):联邦宿主应用,也是本示例中唯一启用 Angular Universal 的服务端渲染应用。它基于 Express + ngExpressEngine 在 Node 端渲染 HTML,并通过联邦机制懒加载 client-app 暴露的模块。

两个子包均基于 Angular ^15.2.10、zone.js ~0.14.10、TypeScript 4.9.5,构建链使用 webpack 5.105.3 + @ngtools/webpack 15.2.11(见 angular-universal-ssr/host-app/package.json)。host-app 额外依赖 @nguniversal/express-engine ^15.2.1、@angular/platform-server ^15.2.10 和 express ^4.22.1,这正是 Angular Universal SSR 的核心依赖组合。

值得注意的是,示例虽然名为 "Angular Universal SSR",但从 angular-universal-ssr/client-app/package.json 可以看到 client-app 只有 serve dist -l 3000 -s 的静态服务脚本,并未引入 platform-server;也就是说 SSR 只发生在 host-app 一侧,client-app 侧的“SSR 构建”仅为产出可被 Node 端 require 的联邦 remoteEntry,后文详述。

运行示例:一键构建与端口说明

在示例目录下执行(见 angular-universal-ssr/README.md):

pnpm run start

该脚本在根 angular-universal-ssr/package.json 中定义为:

{
  "start": "pnpm build:shell && pnpm build:client && pnpm start:shell & pnpm start:client",
  "build:shell": "npm --prefix ./host-app run build:federation",
  "start:shell": "npm --prefix ./host-app run serve:federation",
  "build:client": "npm --prefix ./client-app run build:federation",
  "start:client": "npm --prefix ./client-app run serve:federation"
}

执行顺序是:先构建 host-app,再构建 client-app,随后把 host 的服务端进程放入后台、前台启动 client 的静态服务。两个子包中 build:federation 均为 webpack(即执行 angular-universal-ssr/host-app/webpack.config.js 中导出的双配置构建),serve:federation 分别为:

  • host-app:node dist/server/main.js —— 启动 Angular Universal 的 Express 服务器;
  • client-app:serve dist -l 3000 -s —— 用 serve 以 SPA 模式在 3000 端口托管静态产物。

实际端口与 README 的差异:README 正文提到端口 4000、5000,而其给出的链接又指向 localhost:4000 与 localhost:3000,表述本身存在不一致。以脚本与源码为准:client-app 的静态服务固定监听 3000(serve dist -l 3000),host-app 的 Node 服务器监听 process.env.PORT || 4000(见 angular-universal-ssr/host-app/server-bootstrap.ts)。因此正确访问地址为 localhost:3000(client 独立站)与 localhost:4000(host SSR 应用),5000 在任何配置中均未出现。

双端构建管线:每个应用为什么要跑两套 webpack

本示例最关键的技术点是:同一份 Angular 源码被编译成两个 webpack target 的产物——面向浏览器的 bundle 和面向 Node.js 的 SSR bundle。两个子包的 webpack.config.js 都导出一个配置数组:

// angular-universal-ssr/host-app/webpack.config.js
const host = require('./webpack/host-app');
const hostSsr = require('./webpack/host-ssr');
module.exports = [host, hostSsr];

angular-universal-ssr/client-app/webpack.config.js 同理导出 [client, clientSsr]。四份配置的职责划分如下:

配置文件 产物 target / library 作用
client-app/webpack/client-app.js dist/(浏览器) web + library: { type: 'var', name: 'clientApp' } client 的 SPA 站点 + 暴露给宿主的浏览器端 remoteEntry
client-app/webpack/client-ssr.js dist/server/(Node) target: 'async-node' + libraryTarget: 'commonjs2' 产出可被 Node require 的 remoteEntry,供宿主 SSR 消费
host-app/webpack/host-app.js dist/(浏览器) web host 的浏览器 bundle,通过全局变量消费 remote
host-app/webpack/host-ssr.js dist/server/(Node) target: 'async-node' + entry: ['./server.js'] 打包 Express + Angular ServerModule 的服务端 bundle

两份 SSR 配置共同呈现了 Angular Universal 构建的典型特征(见 angular-universal-ssr/host-app/webpack/host-ssr.js):

entry: ['./server.js'],
output: {
  filename: '[name].js',
  path: resolve(__dirname, 'dist/server'),
  chunkFilename: '[id].[chunkhash].js',
  libraryTarget: 'commonjs2',   // 让 dist/server/main.js 可被 node 直接加载
},
target: 'async-node',
resolve: { mainFields: ['es2015', 'module', 'main'] },

而浏览器端配置则由 @ngtools/webpack 的 AngularWebpackPlugin 接管 TypeScript 编译与模板处理(jitMode: true),并共用一份 loader 规则(angular-universal-ssr/host-app/webpack/_loaders.js):.ts/.ngfactory.js 走 Angular 插件,.scss 经 sass-loader 后由 raw-loader 转字符串,.html 模板用 raw-loader 读取。host-app 的 SSR 端还将 @ngtools/webpack 指定为 platform: 1(server 平台)并切换入口模块为 app.server.module#AppServerModule,这是区分浏览器/服务端 Angular 编译的开关(见 angular-universal-ssr/host-app/webpack/host-ssr.js)。

client-app 侧:用 ModuleFederationPlugin 暴露 Component 与 Module

client-app 的浏览器端联邦配置位于 angular-universal-ssr/client-app/webpack/client-app.js:

new ModuleFederationPlugin({
  name: 'clientApp',
  filename: 'remoteEntry.js',
  library: { type: 'var', name: 'clientApp' },
  exposes: {
    './Component': './src/app/client-cities/client-city/client-city.component.ts',
    './Module': './src/app/client-cities/client-cities.module.ts',
  },
  shared: [
    { '@angular/core': { singleton: true, eager: true } },
    { '@angular/common': { singleton: true, eager: true } },
    { '@angular/router': { singleton: true, eager: true } },
  ],
}),

几个要点:

  1. exposes 暴露的是 TypeScript 源码入口。./Component 指向 ClientCityComponent,./Module 指向 ClientCitiesModule。Angular 插件会把模板与样式一并编译进暴露的模块,因此宿主拿到的不是裸 JS 而是带装饰器元数据的完整 Angular 构件。
  2. shared 中把 @angular/core、@angular/common、@angular/router 声明为 singleton: true, eager: true。这对 Angular 联邦场景至关重要:Angular 的 Injector、装饰器注册表和路由状态都是基于单一运行时实例的,若宿主与远程各自打包一份 @angular/core,会出现“两个 Angular 世界”的实例冲突。singleton: true 保证双方共用同一份共享实例,eager: true 则让共享模块随初始 bundle 同步加载,避免首屏异步竞争。
  3. library: { type: 'var', name: 'clientApp' } 使 remoteEntry 以全局变量 clientApp 挂载,配合宿主的 remotes: { clientApp: 'clientApp' }(var 形式)完成浏览器端握手。

被暴露的组件本身非常轻量,见 angular-universal-ssr/client-app/src/app/client-cities/client-city/client-city.component.ts:它带一个 @Input() city: string,模板(client-city.component.html)渲染一行 “The weather in {{ city }} is good!”。

而 ClientCitiesModule(angular-universal-ssr/client-app/src/app/client-cities/client-cities.module.ts)聚合了两个组件:ClientCitiesHomeComponent(城市列表页)与 ClientCityComponent(详情组件),并导入自己的 RouterModule.forChild 路由。其中 ClientCitiesHomeComponent 展示了一个运行时动态创建组件的手法——通过 ComponentFactoryResolver + ViewContainerRef 在用户点击城市后才动态 import() 详情组件并创建实例(angular-universal-ssr/client-app/src/app/client-cities/client-cities-home/client-cities-home.component.ts),这保证了联邦链路中“模块级懒加载 + 组件级动态创建”两层粒度都被覆盖。

host-app 浏览器端:以全局变量方式消费 remote

host-app 的浏览器 bundle 通过 angular-universal-ssr/host-app/webpack/host-app.js 声明远程:

new ModuleFederationPlugin({
  library: { type: 'var' },
  remotes: {
    clientApp: 'clientApp',
  },
  shared: [
    { '@angular/core': { singleton: true, eager: true } },
    { '@angular/common': { singleton: true, eager: true } },
    { '@angular/router': { singleton: true, eager: true } },
  ],
}),

remotes: { clientApp: 'clientApp' } 是 var 形式(不带 promise new 之类),意味着运行时直接读取全局变量 clientApp。这个全局变量由宿主页面静态脚本注入——angular-universal-ssr/host-app/src/index.html 中有:

<script src="http://localhost:3000/remoteEntry.js"></script>

即宿主页面直接 <script> 加载 3000 端口(client-app 静态服务)上的 remoteEntry.js,加载完成后全局 clientApp 就绪,import('clientApp/Module') 才能解析。

源码中还能看到一段被注释掉的旧式 ContainerReferencePlugin(host-app.js),从源码结构看,这是 Module Federation v0 时代的写法,后被统一的 ModuleFederationPlugin 取代,保留为注释仅具历史参考价值。

TypeScript 侧则通过一行环境声明让编译期认识联邦模块,见 angular-universal-ssr/host-app/src/declarations.d.ts:

declare module 'clientApp/Component';
declare module 'clientApp/Module';

host-app SSR 端:Node 中从本地文件路径解析 remote

这是本示例最有教学价值的部分:SSR 构建中,remote 不再指向 HTTP 地址,而是指向 client-app 已构建产物的本地文件路径。见 angular-universal-ssr/host-app/webpack/host-ssr.js:

new ModuleFederationPlugin({
  name: 'hostApp',
  filename: 'remoteEntry.js',
  library: { type: 'commonjs2' },
  remotes: {
    clientApp: resolve(__dirname, '../../client-app/dist/server/remoteEntry.js'),
  },
  shared: [
    { '@angular/core': { singleton: true, eager: true } },
    { '@angular/common': { singleton: true, eager: true } },
    { '@angular/router': { singleton: true, eager: true } },
  ],
}),

当 Node 服务器执行 import('clientApp/Module') 时,webpack 生成的运行时会在 Node 环境中 require 这个绝对路径对应的 client 端 server bundle。这解释了 client-app 为什么要有一份 dist/server/ 产物:angular-universal-ssr/client-app/webpack/client-ssr.js 以 target: 'async-node'、libraryTarget: 'commonjs2'、platform: 1(Angular 服务端平台)重新编译同一套源码,产出 Node 可加载的 remoteEntry.js。

这也带来一个部署顺序约束:宿主 SSR bundle 构建完成后,运行时依赖 client 侧 server 产物必须已经存在于 client-app/dist/server/。根 start 脚本先 build:shell、再 build:client、最后才启动服务,正是为了满足该依赖。若在生产环境拆分为两台机器部署,就需要自行保证该文件可达,或改用运行时远程发现方案——这一点仓库源码中未做进一步封装,属于自行扩展的空间。

其余 SSR 配置细节:externals: <a href="https://link.gitcode.com/i/7689d75a3668c93de787ace3d99a0495" target="_blank">'enhanced-resolve'] 把 Node 内置生态留给运行时;两个 ContextReplacementPlugin(/@?hapi/) 与 (/express/) 是 Angular Universal 早期模板中抑制动态上下文告警的惯用手法([host-ssr.js);optimization: { minimize: false } 关闭服务端产物压缩。

服务端入口链路为:server.js → server-bootstrap.ts → AppServerModule。

客户端 AppModule 也按 Universal 要求使用了 BrowserModule.withServerTransition({ appId: 'serverApp' })(angular-universal-ssr/host-app/src/app/app.module.ts),用于服务端渲染状态到客户端 hydration 的衔接。

联邦路由:把远程 Angular 模块作为懒加载路由

宿主消费远程模块的入口在路由表里,见 angular-universal-ssr/host-app/src/app/app-routing.module.ts:

const routes: Routes = [
  { path: '', pathMatch: 'full', component: HomeComponent },
  {
    path: 'lazy',
    pathMatch: 'full',
    loadChildren: () =>
      import('./host-lazy-module/host-lazy-module.module').then(x => x.HostLazyModuleModule),
  },
  {
    path: 'federation',
    loadChildren: () => import('clientApp/Module').then(x => x.ClientCitiesModule),
  },
];

对比可见本示例刻意构造的两种懒加载形态:/lazy 是宿主自身的本地懒加载模块(host-lazy-module.module.ts),/federation 则通过 webpack 的模块联邦解析器把 clientApp/Module 解析为远程暴露的 ClientCitiesModule。两者对 RouterModule.forRoot 的 API 完全一致,宿主路由层无需感知“模块来自另一个独立构建的应用”这一事实。宿主根组件(app.component.html)提供 Home / Angular lazy module / Federation lazy module 三个导航标签与一个 <router-outlet>,并在 forRoot 中使用 initialNavigation: 'enabledNonBlocking',避免 SSR 首屏阻塞在导航上。

访问 localhost:4000/federation 时,宿主从联邦运行时取到 ClientCitiesModule,其内部路由渲染出城市列表;点击某个城市后,ClientCitiesHomeComponent 再动态创建联邦暴露的 ClientCityComponent 实例并注入 city 输入——组件在 4000(宿主 SSR 应用)与 3000(client 独立站)两个端口上呈现的内容应完全一致,这正是 E2E 测试要验证的点。

E2E 验证:跨宿主的一致性检查

示例自带 Playwright 端到端测试。angular-universal-ssr/playwright.config.ts 配置了 webServer 自动拉起服务:

webServer: {
  command: 'pnpm run serve',
  url: 'http://localhost:4000',
  timeout: 300_000,
  reuseExistingServer: !process.env.CI,
},

根目录另有 e2e:ci 脚本(pnpm run build && pnpm exec playwright test,见 angular-universal-ssr/package.json)用于 CI 流水线。测试文件位于 angular-universal-ssr/e2e/tests/,其中:

  • hostChecks.spec.ts:在 4000 端口点击 "Federation lazy module" 标签后,断言城市区块出现,并调用 compareInfoBetweenHosts(citiesBlock, 3000) 将宿主的联邦区块与 3000 端口 client 独立站渲染的同区块做逐字符比对,验证“同一份联邦模块在两个应用中渲染结果一致”;
  • clientChecks.spec.ts:针对 3000 端口的 client 独立站,验证城市可点击、点击后出现选城市信息、刷新后状态可重置;
  • commonChecks.spec.ts:参数化验证三个标签页与对应组件文本的联动、以及切换标签后 URL 的 hash/path 变化(含 federationLink 的 URL 断言)。

这套断言把“联邦模块跨应用渲染一致性”固化成了可重复执行的回归用例。关于 e2e 测试的更多工程约定,可参考仓库的 playwright-e2e/README.md(原 angular-universal-ssr/README.md 末尾亦链接了该文档作为最佳实践指引)。

版本与运行前提

基于当前仓库依赖声明,复现本示例需满足以下前提(以 angular-universal-ssr/host-app/package.json 与 angular-universal-ssr/client-app/package.json 为准):

  • Angular 15.2.x + @nguniversal/express-engine 15.2.x:本示例未使用 Angular 16 之后的独立 @angular/ssr 包,走的是 Universal + Express 引擎路线;
  • JIT 编译模式:AngularWebpackPlugin 显式 jitMode: true、skipCodeGeneration: true,即依赖 @angular/compiler 运行时编译(服务端入口 server-bootstrap.ts 也显式 import '@angular/compiler'),不依赖构建期 AOT 产物;
  • ngcc 兼容编译:client-app 的 postinstall 执行 ngcc --properties es2015 browser module main --first-only --create-ivy-entry-points(client-app/package.json),因为 @ngtools/webpack 直连构建需要 Ivy 兼容的第三方库入口;
  • TypeScript 4.9.5 / webpack 5.105.3:ModuleFederationPlugin 从 webpack 包自身的 container 命名空间导入(require('webpack').container.ModuleFederationPlugin),无需单独安装联邦运行时插件;
  • 构建顺序依赖(host SSR 运行时 require client 的 server 产物)意味着两应用不能先启 host 后补 client,pnpm run start 的脚本顺序即是约束的体现。

小结

angular-universal-ssr 示例用最小规模演示了一条完整链路:Angular Universal(Express 引擎)宿主在 4000 端口做服务端渲染,同时以 webpack 双 target 构建出浏览器与 Node 两套联邦产物;client-app 以 exposes 暴露带路由的 Angular 模块和组件,宿主通过 import('clientApp/Module') 将其作为与普通懒加载模块无异的路由消费;shared 的 @angular/core/@angular/common/@angular/router 以 singleton + eager 保证单运行时;浏览器端靠 <script> 注入 remoteEntry 全局变量握手,Node 端靠本地文件路径直接 require 远程 server bundle。E2E 层则用“跨端口区块内容比对”把联邦渲染一致性纳入回归。若你正在评估 Angular 15 世代应用接入 Module Federation(尤其是涉及 SSR 的场景),这份源码是最值得逐文件阅读的参考实现。

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