SignalR Hub类必须是非静态且显式继承Hub，否则运行时报InvalidOperationException；需在Startup中注册MapHub路径，前端连接地址须完全匹配，方法名大小写和参数顺序必须严格一致。
SignalR Hub类必须继承Hub，且不能是静态类
Hub是SignalR服务端通信的入口，所有客户端调用的方法都通过它分发。如果写成静态类或没继承Hub，运行时会直接报InvalidOperationException: No service for type 'Microsoft.AspNetCore.SignalR.IHubContext`1[YourHub]' has been registered。
实操建议：
- Hub类必须是普通非静态类，且显式继承
Hub（不是Hub<T>，除非你用了强类型客户端） - 不要在Hub里存状态——它每次调用都是新实例，
this.Clients.All.SendAsync这类调用依赖IHubContext，不是靠类字段缓存 - 若需跨请求共享数据（如在线用户列表），改用
IDistributedCache或注入单例服务，别往Hub里塞static Dictionary
前端JavaScript连接Hub时，路径必须带/hub后缀且匹配Startup.cs注册路径
SignalR默认不自动挂载Hub，必须在Startup.ConfigureServices中调用services.AddSignalR()，再在Configure中用app.UseEndpoints(endpoints => endpoints.MapHub<ChatHub>("/chat-hub"))显式注册。前端new HubConnectionBuilder().withUrl()里的地址必须和这个路径完全一致，否则404或连接后立刻断开。
常见错误现象：
立即学习“前端免费学习笔记（深入）”；
- 控制台报
Failed to start the connection: Error: Unexpected server response: 200→ 路径错成了API地址（如/api/chat）而非Hub地址 - 连接成功但
on("ReceiveMessage")收不到消息 → Hub名大小写不一致（C#里叫ChatHub，前端连了/chathub，Linux服务器会严格区分） - 使用Azure App Service时出现
WebSockets not supported→ 检查平台是否启用了WebSockets（App Service设置里要手动打开）
SendAsync参数顺序不能错，且方法名需与客户端on监听名严格对应
服务端调用await Clients.All.SendAsync("ReceiveMessage", user, message)，前端必须用connection.on("ReceiveMessage", (user, message) => {...})接收。方法名是字符串匹配，大小写、拼写差一个字符就收不到。
参数差异要注意：
- 服务端传3个参数，前端回调函数就要定义3个形参，顺序不能颠倒；多传或少传不会报错，但后续参数为
undefined - 如果前端用的是.NET Client（比如WPF），方法名要用
[HubMethodName("receive-message")]特性标记，避免驼峰转连字符出问题 - 避免在
SendAsync里传复杂对象：JSON序列化可能失败（如循环引用、DateTime.Kind不一致），优先传简单POCO或明确标注[JsonObject]
Hub里调用Clients.Client(connectionId)前，必须确保connectionId真实存在且未过期
每个客户端连接都有唯一ConnectionId，但它只在连接期间有效。页面刷新、网络中断、主动disconnect后，旧ID立即失效。直接拿前端传来的ID调用Clients.Client(id).SendAsync(...)，如果ID已失效，调用会静默失败（不抛异常，也不触发客户端回调）。
实操建议：
- 不要长期缓存
ConnectionId到数据库——改用Groups（如按用户ID建组），连接建立时await Groups.AddToGroupAsync(Context.ConnectionId, userId)，发消息时Clients.Group(userId).SendAsync(...) - 需要校验ID是否存在？SignalR没提供内置API，只能自己维护在线ID集合（用ConcurrentDictionary + 连接/断开事件），但注意并发安全和内存泄漏
- 调试时可在
OnConnectedAsync里打日志：Console.WriteLine($"Connected: {Context.ConnectionId}")，配合浏览器Network面板看WS连接是否真建立了
最容易被忽略的是：Hub方法里抛异常不会自动断开连接，但客户端收到InvocationException后可能停止监听。别指望服务端throw new Exception()就能让前端重连——得自己处理错误回调并触发reconnect逻辑。
