如何阻止托管式Blazor WASM刷新时跳转到API服务

问题根源 #

刷新浏览器时，服务器会优先匹配Razor Pages或API路由，而非回退到WASM的index.html，导致加载Server端内容而非WASM应用。核心问题在于路由匹配优先级、中间件顺序设置不当，以及API与WASM客户端路由存在潜在冲突。

具体修复方案 #

1. 为API添加统一路由前缀 #

给所有API控制器添加[Route("api/[controller]")]前缀，让所有API请求都以/api开头，彻底避免和WASM客户端路由冲突：

[Route("api/[controller]")]
[ApiController]
public class SampleController : ControllerBase
{
    // 控制器业务方法
}

2. 调整中间件执行顺序 #

确保静态资源、Blazor框架文件优先处理，同时把ApiKeyMiddleware放在正确位置（路由之后、授权之前）：

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
        app.UseWebAssemblyDebugging();
    }
    else
    {
        app.UseHsts();
    }

    // 优先处理Blazor框架文件与静态资源
    app.UseBlazorFrameworkFiles();
    app.UseStaticFiles();
    app.UseHttpsRedirection();

    app.UseForwardedHeaders(new ForwardedHeadersOptions
    {
        ForwardedHeaders = ForwardedHeaders.All
    });

    app.UseRouting();

    // API密钥验证中间件放在授权逻辑之前
    app.UseMiddleware<ApiKeyMiddleware>();
    app.UseAuthorization();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapRazorPages();
        endpoints.MapControllers();
        // 确保所有未匹配的请求都回退到WASM的入口文件
        endpoints.MapFallbackToFile("index.html");
    });
}

3. 确认回退路由的优先级 #

保证MapFallbackToFile("index.html")是UseEndpoints中最后一个端点映射规则，这样任何不匹配Razor Pages、API的请求都会被导向WASM应用，确保客户端路由刷新正常。

4. 检查路由冲突 #

排查WASM客户端路由与Server端API/Razor Pages路由是否存在重复，比如Server端有/users接口时，WASM客户端避免使用/users作为路由路径，或通过API前缀彻底隔离。

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