Angular Universal对接.NET 5 WebApi实现服务端渲染方案咨询

第一步：Angular 12 项目接入Universal SSR #

• 先在Angular项目根目录执行命令安装对应版本的Universal依赖，版本需和Angular大版本对齐避免冲突：ng add @nguniversal/express-engine@12
• 命令执行完成后，确认项目根目录生成server.ts、tsconfig.server.json文件，同时package.json新增dev:ssr、build:ssr、serve:ssr三个执行脚本
• 修改编译输出配置：打开angular.json，将architect -> build -> options -> outputPath设置为.NET 5 WebApi项目的静态文件目录，例如../YourWebApi/wwwroot；再将architect -> server -> options -> outputPath设置为../YourWebApi/ssr-dist，方便.NET项目直接调用SSR编译产物
• 本地验证SSR能力：执行npm run build:ssr && npm run serve:ssr，访问本地4000端口查看页面源码，确认已包含服务端渲染完成的HTML内容，确保SSR本身运行正常

第二步：.NET 5 WebApi 适配SSR请求 #

• 安装.NET侧Node服务调用包：Install-Package Microsoft.AspNetCore.NodeServices -Version 3.1.25，该版本兼容.NET 5运行环境
• 修改Startup.cs配置：
  • 在ConfigureServices方法中注册Node服务：services.AddNodeServices();
  • 调整中间件执行顺序，保证接口请求优先级最高，非接口、非静态资源请求走SSR渲染逻辑，顺序要求为：静态文件服务 → 路由匹配 → 接口端点映射 → SSR fallback
• 编写SSR fallback处理逻辑，核心代码参考：

app.UseEndpoints(endpoints =>
{
    // 优先映射接口路由
    endpoints.MapControllers();
    // 所有未匹配到的请求走SSR渲染
    endpoints.MapFallback(async context =>
    {
        var nodeServices = context.RequestServices.GetRequiredService<INodeServices>();
        // 调用Angular SSR编译后的入口文件渲染页面
        var renderResult = await nodeServices.InvokeAsync<string>("./ssr-dist/main.js", context.Request.Path.Value);
        context.Response.ContentType = "text/html; charset=utf-8";
        await context.Response.WriteAsync(renderResult);
    });
});

• 本地验证联动效果：启动.NET WebApi项目，访问非接口路径，查看返回的页面源码是否包含渲染完成的内容，确认前后端联动正常

第三步：Heroku 部署配置适配 #

• 在项目根目录新增Procfile文件，内容为：web: dotnet run --project YourWebApi/YourWebApi.csproj --urls http://0.0.0.0:$PORT，指定Heroku的启动命令
• 配置Heroku编译环境的buildpack，按顺序添加两个buildpack：先添加Node.js buildpack，再添加.NET Core buildpack，保证编译阶段先完成Angular项目的构建，再编译.NET项目
• 在.NET项目的.csproj文件中添加预编译脚本，实现发布时自动构建Angular SSR产物：

<Target Name="BuildAngularSSR" BeforeTargets="Build">
  <Exec WorkingDirectory="../YourAngularProject" Command="npm install" />
  <Exec WorkingDirectory="../YourAngularProject" Command="npm run build:ssr -- --prod" />
</Target>

• 在Heroku环境变量中添加NODE_ENV=production，同时如果遇到构建内存不足问题，可将Angular构建命令调整为node --max_old_space_size=4096 ./node_modules/@angular/cli/bin/ng build:ssr --prod
• 在.csproj中添加配置，将SSR编译产物包含到发布目录中，避免部署后找不到SSR文件：

<ItemGroup>
  <None Include="ssr-dist/**" CopyToPublishDirectory="PreserveNewest" />
</ItemGroup>

常见问题排查 #

• SSR渲染失败：首先排查ssr-dist目录是否正确输出到.NET项目的运行目录，可在本地发布后查看输出目录确认
• 静态资源404：检查Angular项目的base href配置是否和Heroku的访问路径匹配
• 接口请求被SSR拦截：确认接口路由映射的优先级高于SSR fallback路由，调整端点配置顺序即可

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