如何在.NET 6中手动为ASP.NET Core Web API添加Blazor客户端

没有特殊的非公开实现逻辑，官方「ASP.NET Core Hosted」模板本质就是自动完成了项目创建、依赖引用、中间件注册的流程，手动配置完全符合官方标准，非常适配增量迁移场景，不会破坏现有Web API的已有业务逻辑，操作步骤如下：

项目结构准备 #

• 在现有解决方案中新增独立的Blazor WebAssembly项目，创建时不要勾选「ASP.NET Core Hosted」选项，框架版本选择.NET 6，和现有Web API项目版本保持对齐
• 保持两个项目独立，不要把Blazor代码直接嵌套在API项目目录中，后续前后端单独迭代、版本升级时不会互相干扰，常规结构如下：
  • 解决方案根目录
    • 现有ASP.NET Core Web API项目（增量迁移完成的项目）
    • Blazor WASM客户端项目

宿主API项目配置 #

• 首先在Web API项目中安装NuGet包Microsoft.AspNetCore.Components.WebAssembly.Server，包版本必须和项目使用的.NET 6 SDK版本完全匹配，不要跨大版本引用
• 修改API项目的Program.cs，保留所有原有配置，按顺序新增Blazor托管相关的中间件，注意顺序不能乱，否则会导致接口路由失效：

// --- 原有API配置全部保留，无需修改 ---
var builder = WebApplication.CreateBuilder(args);
// 原有服务注册：控制器、Swagger、CORS、DbContext、鉴权配置等
builder.Services.AddControllers();
// ... 其他原有服务代码
var app = builder.Build();
// 原有中间件：开发环境异常页、Swagger、Https重定向等
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}
app.UseHttpsRedirection();
// --- 原有配置结束，新增以下Blazor托管配置 ---

// 处理Blazor框架自带的_framework目录下的系统资源请求
app.UseBlazorFrameworkFiles();
// 托管wwwroot目录下的Blazor静态文件、自定义静态资源
app.UseStaticFiles();

app.UseRouting();
// 原有鉴权中间件位置不动，保持在路由之后、端点映射之前
app.UseAuthorization();

// 原有控制器端点映射必须保留，且放在Blazor兜底路由前面
app.MapControllers();

// 最后添加兜底规则：所有没匹配到控制器、静态文件的请求，返回Blazor入口页
app.MapFallbackToFile("index.html");

app.Run();

• 新手调试阶段不用先配置复杂的构建流程，右键Blazor项目选择「发布」，选文件夹模式发布，把发布后生成的所有文件复制到API项目的wwwroot根目录，启动API项目就能通过API根地址访问Blazor页面，先跑通流程再优化自动化构建。

调试与发布注意事项 #

• 本地调试建议在解决方案属性中配置多启动项目，同时启动API和Blazor项目，在Blazor项目的wwwroot/appsettings.json中配置API基地址：

{
  "ApiBaseAddress": "https://localhost:你的API项目调试端口/"
}

在Blazor项目的Program.cs中注册HttpClient时绑定该地址即可：

builder.Services.AddScoped(sp => new HttpClient 
{ 
  BaseAddress = new Uri(builder.Configuration["ApiBaseAddress"]) 
});

• 调试阶段如果是跨端口访问API，把Blazor的调试端口加入API项目的CORS允许源即可；生产环境Blazor静态文件和API同域部署，不需要额外配置CORS
• 正式发布时可以在Blazor项目的.csproj文件中添加构建事件，编译完成后自动把Blazor发布文件输出到API项目的wwwroot目录，不需要手动复制
• 鉴权逻辑和普通前端调用API没有区别，JWT、Cookie等鉴权方案都可以正常使用，不需要特殊适配

常见踩坑点 #

• 中间件顺序不能随意调整：MapFallbackToFile必须放在MapControllers之后，否则所有API请求都会被拦截返回Blazor入口页
• 版本必须严格对齐：Blazor项目、API项目、Microsoft.AspNetCore.Components.WebAssembly.Server包的.NET版本要完全一致，否则会出现静态资源加载失败、框架版本不匹配的报错
• 不要把Blazor的编译源码直接放到API项目的wwwroot目录，必须放发布后的产物，否则会出现文件找不到的问题

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