Angular 17 SSR场景下库中懒加载模块未服务端加载问题排查

问题描述 #

我正在使用Angular 17搭配SSR，当前遇到的问题是：部分路由通过懒加载方式引入来自不同库的模块，但这些模块并未在服务端完成加载。为验证该问题，我查看对应路由的页面源码，发现模块相关的HTML内容缺失，说明这些模块仅在客户端加载。

路由代码 #

import { Routes, UrlMatchResult, UrlSegment } from '@angular/router';
import { TabMetaDataResolver } from './shared/inteceptors/tab-metadata-resolver';
import { defaultTabs, TabKeyEnum, SubTypeEnum } from "ngx-exdr-stmx-common";


export const routes: Routes = [
    {
        path: '',
        loadComponent: () => import('./layout/pages-layout/pages-layout.component').then(c => c.PagesLayoutComponent),
        children: [
            {
                path: '',
                loadComponent: () => import('./layout/home/home.component').then(c => c.HomeComponent)
            },
            {
                path: defaultTabs[TabKeyEnum.Chat], // For following enums Chat & Language, both have same endpoint
                loadComponent: () => import('./coming-soon/coming-soon.component').then(c => c.ComingSoonComponent),
            },
            {
                path: defaultTabs[TabKeyEnum.Blogs],
                loadChildren: () => import('ngx-pxdr-ptmx-idpdi/blogs').then(m => m.BlogsModule),
                data: {
                  tabKey: TabKeyEnum.Blogs
                }
            },
            {
                path: defaultTabs[TabKeyEnum.Library],
                // path: 'test-product',
                data: {
                  tabKey: TabKeyEnum.Library
                },                        
                loadChildren: () => import('ngx-pxdr-ptmx-techmeAk').then(m => m.ProductsModule)
            },
            {
                path: '**',
                //redirectTo: ''
                loadComponent: () => import('./coming-soon/coming-soon.component').then(c => c.ComingSoonComponent),
            },                    
            
        ]        
        .map((r: any) => {
            let obj: any = { metaData: TabMetaDataResolver };                  
            if (!r.resolve) {
              r.resolve = obj;
            } else {
              r.resolve['metaData'] = TabMetaDataResolver;
            }
            return r;
          })
    },
    //add route that will be used to navigate to if route not found
];

疑问 #

请问这是可能存在的问题，还是SSR的正常行为？

解答 #

这不是SSR的正常行为，Angular SSR的核心能力之一就是在服务端预加载懒加载模块（包括外部库提供的模块）并完成HTML渲染，最终返回完整的页面源码。出现这个问题通常有以下几类原因：

• 外部库未适配SSR：你引入的ngx-pxdr-ptmx-idpdi/blogs和ngx-pxdr-ptmx-techmeAk库可能未做SSR兼容处理，比如直接使用了window、document等浏览器专属API，却没有在服务端环境下做降级或判断，导致服务端加载模块时抛出错误，被迫回退到客户端加载。
• 路由解析器的干扰：你通过map给所有子路由统一添加了TabMetaDataResolver，如果这个解析器中包含了客户端特有的逻辑，或者异步操作未在服务端正确处理（比如依赖浏览器环境的请求），可能会阻塞服务端对懒加载模块的加载流程。
• SSR配置遗漏：检查你的server.ts文件，确认是否正确配置了provideSsr，且没有禁用懒加载模块的服务端预加载。同时要确保外部库被包含在服务端打包的范围内，没有被构建工具排除。
• 模块导出或组件依赖问题：外部库的BlogsModule、ProductsModule是否正确导出了路由组件？这些组件是否存在依赖客户端环境的代码（比如在构造函数中调用浏览器API）？

排查建议 #

• 先临时移除所有路由的TabMetaDataResolver，测试懒加载模块是否能在服务端正常渲染，以此排除解析器的影响。
• 查看服务端控制台的错误日志，模块加载失败通常会输出具体错误信息，能快速定位问题根源。
• 检查外部库的文档或源码，确认其支持SSR，若有服务端初始化逻辑需按要求配置。
• 尝试将外部库的模块临时复制到本地项目中导入，测试是否能正常服务端渲染，排除库本身的打包问题。

内容的提问来源于stack exchange，提问作者Muhammad Mudassir