将ASP.NET Core 7部署到IIS后SignalR无法正常工作的问题排查

1. 确认IIS已启用WebSocket协议 #

SignalR默认优先使用WebSocket传输，IIS默认未开启该功能：

• 打开「控制面板」→「程序和功能」→「启用或关闭Windows功能」
• 展开「Internet Information Services」→「万维网服务」→「应用程序开发功能」
• 勾选「WebSocket协议」后重启IIS

2. 检查web.config的ASP.NET Core模块配置 #

确保web.config配置正确支持WebSocket，重点确认以下节点：

<system.webServer>
  <handlers>
    <add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModuleV2" resourceType="Unspecified" />
  </handlers>
  <aspNetCore processPath="dotnet" arguments=".\YourProject.dll" stdoutLogEnabled="false" stdoutLogFile=".\logs\stdout" hostingModel="inprocess">
    <environmentVariables>
      <environmentVariable name="ASPNETCORE_ENVIRONMENT" value="Production" />
    </environmentVariables>
  </aspNetCore>
  <webSocket enabled="true" /> <!-- 必须存在这一行 -->
</system.webServer>

进程内托管模式下，AspNetCoreModuleV2会自动处理WebSocket，但仍需确认webSocket enabled="true"配置。

3. 验证SignalR Hub的路由配置 #

确保Program.cs中SignalR路由注册正确，且未被其他中间件拦截：

// Program.cs
app.MapHub<YourChatHub>("/chatHub"); // 该路径需与前端连接地址完全匹配
// 注意：需放在app.UseRouting()之后、app.UseAuthorization()之前（若有授权配置）

前端连接代码的路径必须一致：

const connection = new signalR.HubConnectionBuilder()
    .withUrl("/chatHub")
    .build();

4. 检查CORS设置（跨域场景） #

若前端与后端端口不同，需确保CORS允许SignalR请求：

// Program.cs
builder.Services.AddCors(options =>
{
    options.AddPolicy("AllowSignalR", policy =>
    {
        policy.WithOrigins("http://localhost:3000") // 替换为你的前端地址
              .AllowAnyHeader()
              .AllowAnyMethod()
              .AllowCredentials(); // SignalR必须开启此项
    });
});

app.UseCors("AllowSignalR"); // 需放在app.UseRouting()之前

5. 启用详细日志排查具体错误 #

在appsettings.Production.json中开启SignalR相关的调试日志，定位具体错误：

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore.SignalR": "Debug",
      "Microsoft.AspNetCore.Http.Connections": "Debug"
    }
  }
}

发布后查看站点目录下logs文件夹的stdout日志，或通过IIS事件查看器的应用程序日志获取错误详情。

6. 检查IIS应用程序池设置 #

确保应用程序池的.NET CLR版本设置为「无托管代码」：

• 打开IIS管理器，找到站点对应的应用程序池
• 右键→「高级设置」→「.NET CLR版本」选择「无托管代码」
• 重启应用程序池

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