.NET9升级.NET10后Blazor Server重连模态框故障修复方案

问题重现步骤 #

• 在VS 2026中创建目标框架为.NET 9的全新Blazor Server应用
• 编辑.csproj文件，将目标框架修改为.NET 10：<TargetFramework>net10.0</TargetFramework>
• 启动应用，确保至少在两个浏览器标签页中打开（停止调试时其中一个可能自动关闭）
• 停止调试
• 稍作等待后重启应用

现象 #

步骤3中打开的标签页无法重连，页面底部出现黄色提示栏显示“发生未处理的错误”，重连模态框从“重新加载中”变为“无法恢复会话，请重新加载页面”。已尝试复制.NET 10全新项目中的ReconnectModal组件到升级项目，问题未解决。

修复方案 #

1. 配置Circuit管理参数 #

.NET 10调整了Blazor Server的Circuit默认配置，升级项目需手动指定相关参数以兼容重连逻辑。在Program.cs中更新服务配置：

builder.Services.AddServerSideBlazor(options =>
{
    // 延长断开的Circuit保留时间，给重连留足够窗口
    options.DisconnectedCircuitRetentionPeriod = TimeSpan.FromMinutes(5);
    // 调整JS互操作超时时间，避免重连时因超时失败
    options.JSInteropDefaultCallTimeout = TimeSpan.FromSeconds(30);
});

2. 清理旧会话缓存 #

旧标签页保留的.NET 9时期Circuit ID与新应用生成的ID不匹配，导致重连失败。在_Host.cshtml的body末尾添加JS代码，重连失败时自动清理缓存并刷新：

<script>
    window.addEventListener('blazor:reconnectfailed', () => {
        localStorage.removeItem('blazor-circuit-id');
        sessionStorage.clear();
        location.reload();
    });
</script>

3. 验证Blazor脚本版本 #

确保_Host.cshtml中引用的是.NET 10版本的blazor.server.js，不要使用本地缓存的旧版本脚本：

<script src="_framework/blazor.server.js"></script>

若存在手动引用的旧版本脚本路径，立即替换为上述默认路径。

4. 启用日志排查具体错误 #

在appsettings.json中添加Circuit相关日志配置，查看重连失败的详细原因：

{
  "Logging": {
    "LogLevel": {
      "Microsoft.AspNetCore.Components.Server.Circuits": "Debug"
    }
  }
}

启动应用后查看调试日志，可定位到Circuit ID不匹配、会话过期或其他底层错误，针对性修复。

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