Angular Universal SSR 与 Module Federation 实战:基于 module-federation-examples 的双端联邦构建解析
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 } },
],
}),
几个要点:
exposes暴露的是 TypeScript 源码入口。./Component指向ClientCityComponent,./Module指向ClientCitiesModule。Angular 插件会把模板与样式一并编译进暴露的模块,因此宿主拿到的不是裸 JS 而是带装饰器元数据的完整 Angular 构件。shared中把@angular/core、@angular/common、@angular/router声明为singleton: true, eager: true。这对 Angular 联邦场景至关重要:Angular 的Injector、装饰器注册表和路由状态都是基于单一运行时实例的,若宿主与远程各自打包一份@angular/core,会出现“两个 Angular 世界”的实例冲突。singleton: true保证双方共用同一份共享实例,eager: true则让共享模块随初始 bundle 同步加载,避免首屏异步竞争。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。
- angular-universal-ssr/host-app/server.js:先判断当前文件是否为 Node 入口模块(
__non_webpack_require__.main),再异步 importserver-bootstrap.ts并调用run(); - angular-universal-ssr/host-app/server-bootstrap.ts:创建 Express 应用,用
ngExpressEngine({ bootstrap: AppServerModule })注册 HTML 渲染引擎,静态资源从dist/提供(maxAge: '1y'),所有普通路由走 Universal 引擎渲染index.html并注入APP_BASE_HREF: req.baseUrl; - angular-universal-ssr/host-app/src/app/app.server.module.ts:标准的 Universal 服务端模块,在
AppModule之外叠加ServerModule。
客户端 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 的场景),这份源码是最值得逐文件阅读的参考实现。