SignalR不是开箱即用的魔法盒，需精确配合服务端Hub与客户端连接生命周期；90%收不到消息源于Hub方法签名不匹配、客户端未启动连接或跨域/路由配置遗漏。

SignalR 不是“开箱即用”的实时通信魔法盒，它依赖服务端 Hub 和客户端连接生命周期的精确配合；直接照搬教程代码却收不到消息，90% 是 Hub 方法签名不匹配、客户端未正确启动连接，或跨域/路由配置遗漏。

Hub 方法为什么客户端调不到？

SignalR 的方法调用是大小写敏感且严格匹配签名的。客户端 invoke 调用的方法名必须与 Hub 中 public 方法名完全一致（包括大小写），且参数类型和数量要能被自动反序列化。

• Hub 方法不能是 async void，必须返回 Task 或 Task<T>；否则调用会静默失败
• 参数若为自定义类，该类必须有无参构造函数，且所有需传输的字段/属性要有 get 和 set 访问器
• 不要在 Hub 方法里直接操作 HttpContext —— SignalR 连接不绑定 HTTP 上下文，会抛出 NullReferenceException
• 示例：Hub 中定义 public async Task SendMessage(string user, string message)，客户端必须用 connection.invoke("SendMessage", "Alice", "Hi")，写成 "sendmessage" 或漏掉一个参数都会失败

.NET 6+ 项目中 Hub 端点注册容易漏哪几步？

从 .NET 6 开始，AddSignalR 和 MapHub 必须分别在 Program.cs 的两个不同位置调用，顺序和位置错一个就 404。

C#

"避开 C# 常见错误——空陷阱、异步陷阱、LINQ 陷阱及资源泄漏。"

下载

• 必须在 builder.Services.AddSignalR() —— 否则依赖注入容器不认识 IHubContext
• 必须在 app.MapHub<ChatHub>("/hubs/chat")（注意路径以 /hubs/xxx 为惯例，不能和静态文件中间件冲突）
• 如果用了 UseRouting() 和 UseEndpoints()（旧模板），MapHub 必须放在 UseEndpoints 内部；新 Minimal Hosting 模式下则直接写在 app. 链式调用里
• 若启用了 app.UseHttpsRedirection()，但开发时用 HTTP 测试，浏览器会因混合内容阻止连接 —— 确保前后端协议一致

JavaScript 客户端连不上，先查这三件事

前端报 Failed to start the connection: Error: Failed to complete negotiation with the server 或连接后收不到广播，大概率是基础链路没通。

• 检查浏览器控制台 Network 标签页：是否发出了 /hubs/chat/negotiate 请求？状态码是不是 404 或 500？404 说明 MapHub 路径错了；500 则 Hub 构造函数抛异常（比如注入了未注册的服务）
• 确认客户端 JS 已加载 @microsoft/signalr 6.x+ 版本，并且 new HubConnectionBuilder().withUrl(...) 的 URL 和后端 MapHub 的路径完全一致（含末尾斜杠差异也会影响）
• 调用 start() 后必须 await，且要加 try/catch —— 很多人忽略拒绝原因，直接写 connection.start().then(...)，错误被吞掉
• 示例正确写法：

  const connection = new HubConnectionBuilder()
    .withUrl("/hubs/chat")
    .build();
  
  try {
    await connection.start();
    console.log("Connected");
  } catch (err) {
    console.error("Connection failed:", err); // 这里才能看到真实错误
  }

广播消息收不到？检查 IHubContext 使用时机

用 IHubContext<ChatHub> 在非 Hub 类（如 Controller、BackgroundService）中发消息很常见，但容易误用。

• IHubContext 是单例，但它的 Clients.All.SendAsync 等方法只推送给当前已连接的客户端 —— 如果客户端刚断开或还没 start()，自然收不到
• 不要在 Hub 实例内部再注入 IHubContext（循环依赖），Hub 本身就有 Clients 属性可用
• 若需向特定用户广播，确保客户端连接时调用了 connection.invoke("SetUserName", "Alice") 并在 Hub 中重写 OnConnectedAsync，用 Context.UserIdentifier 关联身份
• 调试技巧：在 Hub 的 OnConnectedAsync 和 OnDisconnectedAsync 里加日志，确认连接数变化是否符合预期

SignalR 的坑不在语法多难，而在连接建立、方法绑定、上下文生命周期这些“看不见的契约”上。最常被跳过的，是检查 negotiate 请求的响应体里有没有返回 connectionId 和 availableTransports —— 这个响应不对，后面全白搭。