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