唯一可靠的服务端推送方式是通过 IHubContext<T>，因 Hub 实例由 SignalR 按连接创建、生命周期短，手动 new 会导致 Clients 未初始化而抛出 InvalidOperationException；控制器等场景必须注入 IHubContext<ChatHub>。
服务端主动推送消息，唯一可靠方式是通过 IHubContext<T>，不是调用 Hub 实例的方法，也不是静态方法或手动 new 出来的 Hub。
为什么不能在控制器里 new ChatHub() 然后调 SendAsync？
Hub 实例由 SignalR 运行时按连接粒度创建和销毁，生命周期极短。手动 new ChatHub() 会导致 InvalidOperationException: Hub has not been initialized —— 因为它没被框架托管，Clients 属性根本没初始化。
- Hub 类不能有 public 无参构造函数以外的初始化逻辑；所有依赖必须通过构造函数注入（且注册为
Scoped或Transient） - 想从控制器、后台服务、定时任务发消息？必须注入
IHubContext<ChatHub>，别存字段、别静态缓存 -
Clients.All.SendAsync("MethodName", ...)中的MethodName是字符串，大小写、拼写必须与前端connection.on("MethodName", ...)完全一致
MapHub 路由位置错，404 或 negotiate 失败
MapHub<ChatHub>("/chathub") 必须写在 UseRouting() 之后、UseEndpoints(...) 内部，顺序错会导致 negotiate 请求返回 404，浏览器控制台只显示 Failed to start the connection: Error: Failed to complete negotiation with the server，但 Hub 代码本身完全没问题。
- 错误写法：
app.MapHub<ChatHub>("/chathub"); app.UseEndpoints(...); - 正确写法：
app.UseRouting(); app.UseEndpoints(endpoints => { endpoints.MapHub<ChatHub>("/chathub"); }); - 前端
new HubConnectionBuilder().withUrl("/chathub")的路径必须与MapHub参数严格一致（区分大小写，不加额外前缀）
Clients.Group / Clients.User 推送静默失败？检查字符串标识
Clients.Group("admin") 和 Clients.User("uid123") 中的字符串不会被 SignalR 校验，拼错、多空格、大小写不一致，都会导致消息直接丢弃，且无日志、无异常。
- Group 名建议从 token 或 query string 动态提取：
Context.GetHttpContext().Request.Query["group"]，避免硬编码 - User ID 应该来自认证上下文（如
Context.UserIdentifier），而不是随意取Context.ConnectionId - 加入 Group 后，必须在
OnDisconnectedAsync里调用Groups.RemoveFromGroupAsync，否则断连用户仍留在群组中，后续推送会发给无效连接
客户端连不上？先看 negotiate 响应体里有没有 accessToken
如果用了 JWT 认证，SignalR 的 negotiate 请求成功后，响应体里必须包含 accessToken 字段。JS 客户端靠它完成后续 WebSocket 握手。漏掉这个字段，连接会卡在 negotiate 阶段，报错同上，但根源是服务端没把 token 写进响应。
- 确保认证中间件在
UseRouting()之后、UseEndpoints()之前注册 - 检查
MapHub路由是否被 [Authorize] 保护，且策略能正确解析 token - 客户端必须显式传入：
new HubConnectionBuilder().withUrl("/chathub", { accessTokenFactory: () => localStorage.getItem("token") })
最常被忽略的一点：Group 和 User 标识是纯字符串匹配，SignalR 不做任何合法性校验，也不报错——错一个字符，消息就消失，连 trace 日志都不会打。调试时别只盯 Hub 方法，先确认 identifier 来源和拼写。
