Blazor应用Debug模式正常，Release模式API调用返回页面HTML异常排查

场景复现 #

已在最小API管道中添加端点：

app.MapGet("/complaint/getorder", (Guid fileid, CancellationToken ct, [FromServices] ITrackTraceApiClient client) => client.GetOrder(ct))

Blazor应用通过IFlurlClient调用服务：

private readonly IFlurlClient _client = .......;

public async Task<Order?> GetOrder(Guid fileId, CancellationToken ct)
{
    var req = _client.Request("complaint", "getorderbyfileid", fileId);
    // DEBUG
    await Console.Out.WriteLineAsync(await req.GetStringAsync());
    return await req.GetJsonAsync<Order?>(ct);
}

首页index.razor初始化时导航至目标页面：

@page "/"

@inject NavigationManager NavigationManager

@code {
    protected override void OnInitialized()
    {
        NavigationManager.NavigateTo("/order/new");
    }
}

问题现象：

• Debug模式下调用正常，能打印Order的JSON数据；
• Release模式下API调用返回index.razor的HTML内容，导致反序列化异常；
• .NET8中设置"launchUrl": "/"会出现双斜杠https://localhost:7096//并提示“endpoint not found”，改为空字符串后导航正常，但Release模式的API问题仍存在；
• 该问题在.NET7和.NET8中均存在。

可能原因及解决方向 #

1. API端点与前端请求路径不匹配 #

后端API端点定义为/complaint/getorder（通过fileid查询参数接收值），但前端FlurlClient构造的请求路径是/complaint/getorderbyfileid/{fileId}（将fileId作为路径参数传递）。这种路径不一致会导致请求无法匹配到API端点，进而被Blazor的SPA fallback路由捕获，返回首页HTML。

解决：

• 统一前后端路径：要么将后端API修改为路径参数形式：

  app.MapGet("/complaint/getorderbyfileid/{fileid}", (Guid fileid, CancellationToken ct, [FromServices] ITrackTraceApiClient client) => client.GetOrder(ct))
  

• 要么调整前端请求为查询参数形式：

  var req = _client.Request("complaint", "getorder").SetQueryParam("fileid", fileId);
  

2. Release模式下中间件顺序问题 #

若API端点的注册顺序晚于Blazor SPA的fallback中间件，Release模式下的路由匹配逻辑会优先将未匹配的请求导向SPA首页，而非API端点。

解决：
确保API端点注册在Blazor相关中间件之前：

var app = builder.Build();

// 先注册所有API端点
app.MapGet("/complaint/getorder", ...);

// 再注册Blazor相关中间件
app.MapBlazorHub();
app.MapFallbackToPage("/_Host");

3. .NET8对launchUrl的行为变更 #

.NET8中launchUrl的处理逻辑较.NET7更严格，当设置为"/"时，会和index.razor中的NavigateTo操作冲突，导致出现双斜杠异常。

解决：

• 将launchUrl设置为空字符串""，或直接指定目标页面"/order/new"；
• 也可移除launchUrl配置，让应用默认加载根路径后由Blazor导航完成跳转。

4. Release模式下的路径拼接优化 #

Release模式下可能存在路径拼接的隐式优化（如多余斜杠处理），导致实际请求路径与预期不符。建议在前端打印完整请求URL进行验证：

await Console.Out.WriteLineAsync(req.Url.ToString());

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