Spring Boot集成WebSocket推送失败的核心原因在于机制混淆与配置错配：@ServerEndpoint为原生轻量方案，不支持STOMP路由；@EnableWebSocketMessageBroker是Spring STOMP封装，需严格匹配broker前缀、客户端订阅时机、集群广播及JWT鉴权配置，混用必崩。
Spring Boot集成WebSocket做实时消息推送，不是配几个注解就能跑通的。真正卡住人的地方，是连接能建但推不出去、前端收不到、集群下会话丢失、或者一上生产就报Connection closed。核心问题不在“会不会写”，而在“为什么推不到”。
WebSocket配置用@ServerEndpoint还是@EnableWebSocketMessageBroker
两者根本不是同一套机制，混用必崩。
-
@ServerEndpoint是Java EE原生API，靠ServerEndpointExporter注册，适合轻量、点对点、自管理会话（比如按userId存进ConcurrentHashMap），但不支持STOMP、无消息路由、无法广播到订阅路径 -
@EnableWebSocketMessageBroker是Spring的STOMP封装，必须搭配registerStompEndpoints和configureMessageBroker，天然支持/topic广播、/user私有推送、权限拦截、心跳保活，适合中大型项目 - 如果你要用JWT鉴权、要对接Vue前端的
@stomp/stompjs、要部署在Nginx后且带路径重写——只能选后者；否则@ServerEndpoint写起来快，但后续加功能全是补丁
SimpMessagingTemplate推送失败的常见原因
调了convertAndSend却没收到？别急着查前端，先看这几点：
WebSocket 8.18.2
下载
WebSocket 8.18.2 是该协议规范的一个重要迭代版本，主要优化了连接稳定性与数据传输效率。它通过全双工通信机制，允许客户端与服务器在单一长连接上实时交换数据，大幅降低传统 HTTP 轮询的开销。该版本增强了心跳保活、自动重连及二进制帧传输能力，适用于即时通讯、在线游戏及金融行情推送等低延迟场景，为开发者提供更可靠的实时网络交互基础。
- 目标地址必须严格匹配Broker配置：如果
enableSimpleBroker("/topic")，那推送地址就得是/topic/notify，不能少/topic前缀，也不能写成/notify - 客户端必须已订阅该路径：前端用STOMP时，
client.subscribe("/topic/notify", ...)得在连接建立后、且connected事件触发之后执行，否则订阅无效 - 集群环境下
SimpMessagingTemplate默认只推本机会话：没配Redis广播或消息代理（如RabbitMQ）时，其他节点上的客户端永远收不到 - 如果用了
@PreAuthorize("hasRole('USER')")但没配jwtChannelInterceptor，权限校验会直接拒绝消息，日志里可能只打印Denied而无堆栈
前端连不上ws://或wss://的硬性检查项
浏览器控制台显示net::ERR_CONNECTION_REFUSED或Error during WebSocket handshake，优先排查这些：
- Nginx反向代理必须显式升级协议：
proxy_http_version 1.1;+proxy_set_header Upgrade $http_upgrade;+proxy_set_header Connection "upgrade";，缺一不可 - Spring Boot的
server.servlet.context-path会影响WebSocket端点路径：比如设了/api，那@Endpoint("/ws")实际访问地址是ws://host/api/ws，前端new WebSocket()时得写全 - Chrome 120+默认阻止
ws://混合内容（HTTP页面里连WS），开发环境务必用https://+wss://，或改用sockjsfallback（需后端withSockJS()） - 前端
Stomp.over(new SockJS(...))里的URL不能带http://前缀，应为/notification（相对路径）或https://host/notification（绝对路径），错写成http://host/notification会导致降级失败
最常被忽略的是消息模型设计：不要把所有通知都往/topic/all里塞。未读数变化、审批状态、订单物流——三类数据更新频率、权限范围、前端处理逻辑完全不同，强行共用一个主题会让消费端逻辑越来越臃肿，后期改一个字段就得全量回归测试。
