signalr在c#中需严格遵循hub生命周期、ihubcontext推送规范及negotiate细节；90%故障源于方法签名不匹配、maphub注册错位、new hub()误用、群组未清理或negotiate失败。
SignalR 在 C# 中不是“配好就能用”的通信库，90% 的推送失败、收不到消息、连接静默断开，都卡在 Hub 生命周期、IHubContext 使用方式或 negotiate 环节的细节上。
Hub 方法调用失败：大小写、签名、返回值全得对
客户端 invoke("SendMessage") 调不到服务端方法，第一反应不是网络问题，而是签名不匹配。
- 方法名必须完全一致（
SendMessage≠sendmessage），且为public，不能是private或protected - 参数类型要能被 JSON 反序列化：基础类型（
string,int）、DTO 类（必须有无参构造函数 +get/set） - 返回类型必须是
Task或Task<t></t>；async void会导致调用静默失败，毫无日志 - 不要在方法里访问
HttpContext——SignalR 连接不携带 HTTP 上下文，会直接抛NullReferenceException
.NET 6+ 中 MapHub 注册错位 = 404，且 negotiate 请求根本发不出
MapHub<chathub>("/hubs/chat")</chathub> 必须出现在 UseEndpoints 内部，否则路由系统压根不认识这个端点。
- 错误写法：
app.MapHub<chathub>("/hubs/chat");</chathub>放在app.UseEndpoints(...)外面 → 404，浏览器 Network 标签页里看不到/hubs/chat/negotiate请求 - 正确写法（Minimal Hosting）：
app.MapHub<chathub>("/hubs/chat");</chathub>直接挂在app.链式调用末尾，且确保builder.Services.AddSignalR()已提前注册 - 若项目仍用传统
UseEndpoints块，MapHub必须写在endpoints => { ... }里面，顺序不能颠倒
服务端主动推送只能走 IHubContext，new Hub() 是死路
想从 Controller、BackgroundService 或定时任务里发消息？别碰 new ChatHub()，也别试图缓存 Clients 属性——它会在 Hub 实例销毁后变 null。
- 必须在
Program.cs中注册：builder.Services.AddSignalR() - 在 Controller 构造函数中注入：
IHubContext<chathub> hubContext</chathub> - 发送时明确目标范围：
hubContext.Clients.All.SendAsync("ReceiveMessage", user, message)（广播）、Clients.Group("admin")（需先Groups.AddToGroupAsync）、Clients.User("alice")（依赖 JWT 的sub或nameid声明） - 群组不会自动清理离线连接——必须在
OnDisconnectedAsync里显式调用Groups.RemoveFromGroupAsync(Context.ConnectionId, groupName)
JavaScript 客户端连不上？先盯死 negotiate 请求和 WebSocket 升级状态
前端报 Failed to start the connection: Error: Failed to complete negotiation with the server，本质是握手第一步就失败了。
- 打开浏览器 Network 标签页，过滤
negotiate，确认是否发出请求、返回状态码是不是 200；404 说明路径错，500 说明 Hub 构造函数里注入了未注册的服务 - 检查 WebSocket 是否成功升级：在 Network 里找 WS 类型连接，Status 应为
101 Switching Protocols；若看到大量poll请求，说明降级到了 Long Polling，延迟高且易断 - 确保前后端协议一致：开发用 HTTP，就别开
app.UseHttpsRedirection()；部署到 IIS，得确认 Windows Server 已启用 WebSocket 协议支持 - JS 客户端
start()是 Promise，不await或.catch就永远不知道它卡在哪——CORS、认证失败、路径错误，全静默
最常被忽略的是群组清理和 negotiate 响应体结构：JWT 认证下，negotiate 返回必须含 accessToken 字段，否则 JS 客户端拒绝升级；而 Group 名拼错、大小写不一致、没手动移出离线连接，都会导致消息“发出去了却没人收到”。
