WebSocket连接失败排查：Nginx+Tomcat+Spring全链路配置指南

1. 项目概述：为什么“苍穹外卖”本地测试时WebSocket连不上，不是代码写错了，而是环境链路断了

“苍穹外卖”本地测试WebSocket连接不上，客户催单功能失效——这问题在开发群里一冒头，十有八九会有人立刻甩出一句：“后端日志没报错啊，前端ws://localhost:8080/ws/也连得上，但就是收不到消息！”接着就是一顿重启、清缓存、换浏览器……折腾两小时，最后发现Tomcat里@ServerEndpoint注解的类压根没被扫描到，或者Nginx反向代理把WebSocket升级请求给拦腰截断了。这不是业务逻辑缺陷，而是本地开发环境与生产部署模型错位导致的协议级失联。

核心关键词“WebSocket”“nginx”“tomcat”“@Configuration”“@Component”“@ServerEndpoint”，其实已经勾勒出一条清晰的技术链路：前端通过new WebSocket('ws://...')发起连接 → Nginx作为反向代理需透传Upgrade和Connection头 → Tomcat容器需正确加载WebSocket Endpoint组件并完成HTTP升级 → Spring容器需识别@ServerEndpoint为有效Bean并注册到WebSocket引擎。任何一个环节配置偏差或版本兼容性缺失，都会让“客户催单”这种强实时功能彻底哑火。

我带过三个外卖类项目，这类问题平均每个项目复现2.3次。最典型的是：开发同学在IDEA里直接运行Spring Boot内置Tomcat（默认启用WebSocket支持），一切正常；但一换成外置Tomcat 9.0.85 + Nginx 1.24做反向代理，WebSocket就“黑屏”。根本原因不是代码，而是本地测试环境缺失了生产级网关层的协议协商能力。本文不讲抽象原理，只拆解真实场景下从Nginx配置、Tomcat参数、Spring组件注册到前端连接验证的全链路排查路径，每一步都附实测参数、错误日志特征和绕过方案。适合正在被催单功能卡住的后端、全栈，以及需要快速定位WebSocket失联根因的运维同学。

2. 全链路设计思路拆解：为什么必须同时动Nginx、Tomcat、Spring三层配置

2.1 WebSocket连接失败的本质：HTTP/1.1 Upgrade机制被中途破坏

WebSocket不是独立协议，它依赖HTTP/1.1的Upgrade机制完成握手。客户端发送如下请求：

GET /ws/order-notify HTTP/1.1 Host: localhost:8080 Upgrade: websocket Connection: Upgrade Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ== Sec-WebSocket-Version: 13

服务端必须返回：

HTTP/1.1 101 Switching Protocols Upgrade: websocket Connection: Upgrade Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=

这个101响应是WebSocket连接成立的唯一凭证。而本地测试失败，90%以上源于这个Upgrade流程在某一层被降级为200或400响应。常见断点有三处：

• Nginx层：未透传Upgrade和Connection头，或proxy_http_version未设为1.1；
• Tomcat层：WebSocket Servlet未启用，或@ServerEndpoint类未被Servlet容器扫描到（尤其外置Tomcat）；
• Spring层：@ServerEndpoint注解类被Spring管理但未注入到Tomcat的WebSocket引擎，或@Configuration类中遗漏ServerEndpointExporterBean。

这三层不是并列关系，而是洋葱式嵌套依赖：Nginx必须把Upgrade请求原样交给Tomcat → Tomcat的WebSocket Servlet引擎必须能识别并处理该请求 → Spring容器必须把@ServerEndpoint类注册到Tomcat引擎中。漏掉任何一层，连接就卡在“发送了请求，但没收到101”。

2.2 为什么不能只改代码？本地与生产环境的三大硬差异

很多开发者第一反应是检查@ServerEndpoint写法，比如：

@ServerEndpoint("/ws/order-notify") @Component public class OrderNotifyEndpoint { @OnOpen public void onOpen(Session session) { ... } }

这段代码在Spring Boot内嵌Tomcat下能跑通，但放到外置Tomcat中大概率失效。原因在于：

1. 组件扫描范围不同：Spring Boot默认扫描@ServerEndpoint，但外置Tomcat启动时，Spring上下文由ContextLoaderListener加载，若web.xml中未声明<listener>或@ServletComponentScan未覆盖包路径，@ServerEndpoint类根本不会被Spring管理；
2. WebSocket引擎初始化时机不同：内嵌Tomcat在Spring容器启动前已初始化WebSocket Servlet，而外置Tomcat需显式配置<servlet>和<servlet-mapping>，否则@ServerEndpoint注解无效；
3. Nginx代理行为不可控：本地直连http://localhost:8080无代理，但生产环境必经Nginx。Nginx默认将Upgrade头过滤掉，且对长连接超时时间设置过短（默认60秒），导致WebSocket连接建立后很快被断开。

因此，解决思路必须是环境适配优先于代码修改。先确保Nginx能透传Upgrade，再确认Tomcat能加载Endpoint，最后验证Spring能将其注册。顺序颠倒，比如先改Java代码再调Nginx，只会让问题更隐蔽。

2.3 技术选型背后的现实约束：为什么必须用Nginx+Tomcat组合

“苍穹外卖”采用Nginx+Tomcat架构，不是技术炫技，而是业务刚性需求决定的：

• 负载均衡刚需：订单高峰期并发WebSocket连接可达5万+/秒，单台Tomcat无法承载，Nginx的upstream模块可实现连接数分发；
• SSL卸载必要：微信小程序、APP等客户端强制要求wss协议，Nginx处理HTTPS加解密，Tomcat专注业务逻辑，降低CPU压力；
• 静态资源分离：HTML/CSS/JS由Nginx直接返回，避免Tomcat线程阻塞，提升整体吞吐量。

这意味着，本地测试必须模拟生产Nginx行为。很多团队用spring-boot-devtools热部署，却忽略Nginx配置同步，结果测试环境永远“没问题”，上线即故障。本文所有方案均基于最小化复现生产环境原则设计，拒绝“本地能跑就行”的侥幸心理。

3. 核心细节解析与实操要点：Nginx、Tomcat、Spring三层关键配置

3.1 Nginx配置：透传Upgrade头与长连接保活的黄金参数

Nginx是WebSocket链路的第一道关卡。错误配置会导致客户端收不到101响应，日志中表现为101 Switching Protocols缺失。以下是经过27个线上项目验证的最小可行配置：

upstream websocket_backend { server 127.0.0.1:8080; # 启用健康检查，避免后端宕机时Nginx仍转发请求 keepalive 32; } server { listen 80; server_name localhost; location /ws/ { proxy_pass http://websocket_backend; # 关键：必须透传Upgrade和Connection头 proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; # 关键：禁用缓冲，避免WebSocket消息被Nginx缓存 proxy_buffering off; # 关键：设置长连接超时，WebSocket心跳间隔通常为30秒，此处设为60秒 proxy_read_timeout 60; proxy_send_timeout 60; # 可选：添加X-Real-IP头，便于后端日志追踪真实IP proxy_set_header X-Real-IP $remote_addr; } # 其他location配置... }

提示：proxy_http_version 1.1是基础前提，Nginx 1.1.3+才支持WebSocket代理。低于此版本必须升级，不存在兼容方案。

参数详解与避坑点：

• proxy_set_header Upgrade $http_upgrade：$http_upgrade是Nginx内置变量，自动获取客户端请求中的Upgrade头值。若写死为"websocket"，当客户端发送Upgrade: websocket时能工作，但遇到某些旧版浏览器发送Upgrade: Websocket（大小写不敏感）时会失败；
• proxy_set_header Connection "upgrade"：必须用双引号包裹upgrade，否则Nginx会将其解析为指令而非字符串值；
• proxy_read_timeout 60：这是WebSocket连接空闲超时时间。若后端心跳间隔为30秒，此值必须大于30秒，否则Nginx会在心跳间隔后主动断开连接。实测中，设为心跳间隔的2倍（如60秒）最稳；
• proxy_buffering off：WebSocket消息是流式传输，开启缓冲会导致消息延迟甚至丢失。曾有项目因开启此选项，客户催单消息平均延迟8秒。

验证方法：用curl模拟Upgrade请求，观察Nginx access.log是否记录101状态码：

curl -i -H "Connection: Upgrade" -H "Upgrade: websocket" \ -H "Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==" \ -H "Sec-WebSocket-Version: 13" \ http://localhost/ws/order-notify

若返回HTTP/1.1 101 Switching Protocols，说明Nginx层通畅；若返回HTTP/1.1 200 OK，则检查proxy_http_version和proxy_set_header是否生效。

3.2 Tomcat配置：启用WebSocket Servlet与外置容器的组件扫描

外置Tomcat（非Spring Boot内嵌）需手动激活WebSocket支持。Tomcat 7.0.47+默认启用，但需确认conf/web.xml中<servlet>配置未被注释：

<!-- conf/web.xml 中确保以下servlet未被注释 --> <servlet> <servlet-name>default</servlet-name> <servlet-class>org.apache.catalina.servlets.DefaultServlet</servlet-class> <init-param> <param-name>debug</param-name> <param-value>0</param-value> </init-param> <init-param> <param-name>listings</param-name> <param-value>false</param-value> </init-param> <load-on-startup>1</load-on-startup> </servlet> <!-- 关键：WebSocket Servlet必须存在且未被禁用 --> <servlet> <servlet-name>websocket</servlet-name> <servlet-class>org.apache.catalina.websocket.WsServlet</servlet-class> <load-on-startup>1</load-on-startup> </servlet> <servlet-mapping> <servlet-name>websocket</servlet-name> <url-pattern>/ws/*</url-pattern> </servlet-mapping>

注意：Tomcat 8.5+已弃用WsServlet，改用javax.websocket.server.ServerEndpointConfig，但@ServerEndpoint注解仍需容器支持。若使用Tomcat 9.x，无需配置servlet-mapping，但必须确保lib/tomcat-websocket.jar存在。

外置Tomcat下@ServerEndpoint不生效的三大主因：

1. Spring上下文未扫描到Endpoint类：@ServerEndpoint类需被Spring容器管理，否则Tomcat无法识别。解决方案是在@Configuration类中添加@ServletComponentScan，并指定包路径：

@Configuration @ServletComponentScan(basePackages = "com.cangqiong.websocket") // 必须明确指定包 public class WebSocketConfig { // 此处无需@Bean，Spring Boot 2.0+自动注册ServerEndpointExporter }

2. Web应用未启用注解扫描：web.xml中需声明<listener>加载Spring上下文：

<listener> <listener-class>org.springframework.web.context.ContextLoaderListener</listener-class> </listener> <context-param> <param-name>contextConfigLocation</param-name> <param-value>classpath:spring-context.xml</param-value> </context-param>

3. Tomcat版本与JDK不匹配：Tomcat 9.0要求JDK 8+，若用JDK 11运行Tomcat 8.5，@ServerEndpoint会因类加载器问题无法注册。检查catalina.out日志，搜索Failed to load class或NoClassDefFoundError: javax/websocket/ServerEndpoint。

实测技巧：在Tomcat启动日志中搜索WebSocket关键字。正常应出现：

INFO [main] org.apache.coyote.AbstractProtocol.start Starting ProtocolHandler ["http-nio-8080"] INFO [main] org.apache.coyote.AbstractProtocol.start Starting ProtocolHandler ["ajp-nio-8009"] INFO [main] org.apache.catalina.startup.HostConfig.deployDirectory Deployment of web application directory [.../webapps/ROOT] has finished in [X] ms

若无WebSocket相关日志，说明WebSocket引擎未启动。

3.3 Spring配置：@ServerEndpoint注册与ServerEndpointExporter的隐式依赖

Spring Framework 4.0+对WebSocket的支持依赖ServerEndpointExporterBean。该Bean负责将@ServerEndpoint注解类注册到Tomcat的WebSocket引擎中。Spring Boot 2.0+默认自动配置，但外置Tomcat需手动声明：

@Configuration public class WebSocketConfig { /** * 关键：必须声明ServerEndpointExporter Bean * 否则@ServerEndpoint类不会被注册到Tomcat WebSocket引擎 */ @Bean public ServerEndpointExporter serverEndpointExporter() { return new ServerEndpointExporter(); } /** * 可选：自定义WebSocketConfigurer，用于设置最大文本消息长度等 */ @Bean public WebSocketConfigurer webSocketConfigurer() { return new WebSocketConfigurer() { @Override public void registerWebSocketHandlers(WebSocketHandlerRegistry registry) { registry.addHandler(new OrderNotifyHandler(), "/ws/order-notify") .setAllowedOrigins("*"); } }; } }

注意：ServerEndpointExporterBean必须在Spring容器启动早期创建，否则@ServerEndpoint类可能在Exporter初始化前就被销毁。若项目使用@ImportResource加载XML配置，需确保<bean class="org.springframework.web.socket.server.support.ServerEndpointExporter"/>在XML中声明。

@ServerEndpoint类的四大存活条件：

• 类必须被Spring容器管理（加@Component或@Service）；
• 类必须在@ServletComponentScan或@ComponentScan扫描路径内；
• 类必须有无参构造函数（Spring通过反射实例化）；
• 类不能是内部类（匿名内部类、Lambda表达式均不支持）。

曾有一个项目因OrderNotifyEndpoint定义为private static class，导致ServerEndpointExporter扫描时跳过，日志中无任何错误，但连接始终失败。解决方案是改为顶层public类。

验证Spring注册是否成功：在OrderNotifyEndpoint的@OnOpen方法中添加日志：

@OnOpen public void onOpen(Session session) { System.out.println("WebSocket connection opened: " + session.getId()); // 或用SLF4J log.info("WebSocket connected, session id: {}", session.getId()); }

若启动Tomcat后访问ws://localhost:8080/ws/order-notify，控制台无此日志输出，说明Spring未成功注册Endpoint。

4. 实操过程与核心环节实现：从零搭建可验证的本地WebSocket环境

4.1 环境准备清单：Nginx、Tomcat、JDK版本与端口规划

为避免版本冲突，推荐以下组合（已在12个“苍穹外卖”分支项目中验证）：

组件	推荐版本	下载地址	关键说明
Nginx	1.24.0	https://nginx.org/en/download.html	Windows用户用nginx-1.24.0.zip，Linux用nginx-1.24.0.tar.gz
Tomcat	9.0.85	https://tomcat.apache.org/download.cgi	必须选择tar.gz或zip包，勿用Windows Service Installer（服务模式不支持WebSocket调试）
JDK	1.8.0_391	https://adoptium.net/	Tomcat 9.0要求JDK 8+，JDK 17+需Tomcat 10.1+，暂不推荐

端口规划（避免冲突）：

• Nginx监听80端口（本地测试可用8081，避免权限问题）；
• Tomcat监听8080端口（conf/server.xml中<Connector port="8080" />）；
• WebSocket路径统一为/ws/**（如/ws/order-notify），便于Nginx location匹配。

操作步骤：

1. 解压Nginx到C:\nginx（Windows）或/usr/local/nginx（Linux）；
2. 解压Tomcat到C:\tomcat或/opt/tomcat；
3. 设置JAVA_HOME指向JDK安装目录；
4. 修改Tomcatconf/server.xml，确保<Connector port="8080" protocol="HTTP/1.1" />未被注释；
5. 将项目WAR包放入tomcat/webapps/ROOT.war（或解压为ROOT文件夹）；
6. 启动Tomcat：bin/startup.bat（Windows）或bin/startup.sh（Linux）；
7. 启动Nginx：nginx.exe -c conf/nginx.conf（Windows）或nginx -c conf/nginx.conf（Linux）。

提示：首次启动Nginx时，若提示nginx: [emerg] bind() to 0.0.0.0:80 failed，说明80端口被占用。Windows可执行net stop http释放端口；Linux执行sudo fuser -k 80/tcp。

4.2 前端连接验证：用Postman和浏览器双通道测试

仅靠后端日志无法确认WebSocket是否真正连通。必须从前端发起真实连接并观察双向通信。

Postman WebSocket测试（推荐Postman v10.20+）：

1. 打开Postman → New → WebSocket Request；
2. URL填ws://localhost:8081/ws/order-notify（Nginx端口）；
3. 点击“Connect”，观察状态栏是否显示Connected；
4. 发送JSON消息：{"type":"ping","data":"test"}；
5. 查看右侧响应区是否收到{"type":"pong","data":"test"}。

若连接失败，Postman会显示具体错误，如：

• Error: connect ECONNREFUSED 127.0.0.1:8081→ Nginx未启动或端口错误；
• Error: Unexpected response from server. Status code: 200→ Nginx未透传Upgrade头；
• Error: WebSocket is closed before the connection is established→ Tomcat未加载Endpoint或Spring未注册。

浏览器JavaScript测试（Chrome/Firefox）：

<!DOCTYPE html> <html> <head><title>WebSocket Test</title></head> <body> <script> const ws = new WebSocket('ws://localhost:8081/ws/order-notify'); ws.onopen = function(event) { console.log('WebSocket connected'); ws.send(JSON.stringify({type: 'join', orderId: 'ORD123456'})); }; ws.onmessage = function(event) { console.log('Received:', event.data); }; ws.onerror = function(error) { console.error('WebSocket error:', error); }; ws.onclose = function(event) { console.log('WebSocket closed:', event.code, event.reason); }; </script> </body> </html>

打开此HTML文件，打开浏览器开发者工具（F12）→ Console，观察日志。关键指标：

• onopen触发 → 连接建立成功；
• onmessage收到后端推送 → 消息通道畅通；
• 若onerror频繁触发，检查Nginxproxy_read_timeout是否过短。

4.3 后端Endpoint实现：一个可直接复用的订单通知示例

以下是一个经过生产验证的OrderNotifyEndpoint完整实现，包含心跳保活、连接池管理、异常处理：

@Component @ServerEndpoint("/ws/order-notify") public class OrderNotifyEndpoint { // 使用ConcurrentHashMap存储Session，避免HashMap线程不安全 private static final Map<String, Session> SESSIONS = new ConcurrentHashMap<>(); @OnOpen public void onOpen(Session session) { String sessionId = session.getId(); SESSIONS.put(sessionId, session); System.out.println("WebSocket opened: " + sessionId + ", total sessions: " + SESSIONS.size()); // 发送欢迎消息 try { session.getBasicRemote().sendText( JSON.toJSONString(Map.of("type", "welcome", "message", "Connected successfully!")) ); } catch (IOException e) { System.err.println("Send welcome message failed: " + e.getMessage()); } } @OnMessage public void onMessage(String message, Session session) { System.out.println("Received from " + session.getId() + ": " + message); // 解析前端发送的订单ID，加入通知队列 try { JSONObject json = JSON.parseObject(message); String orderId = json.getString("orderId"); if (orderId != null && !orderId.trim().isEmpty()) { // 模拟推送给该订单的WebSocket连接 broadcastToOrder(orderId, Map.of("type", "order_update", "orderId", orderId, "status", "confirmed")); } } catch (Exception e) { System.err.println("Parse message failed: " + e.getMessage()); } } @OnError public void onError(Session session, Throwable error) { System.err.println("WebSocket error for session " + session.getId() + ": " + error.getMessage()); error.printStackTrace(); } @OnClose public void onClose(Session session) { String sessionId = session.getId(); SESSIONS.remove(sessionId); System.out.println("WebSocket closed: " + sessionId + ", remaining sessions: " + SESSIONS.size()); } /** * 向指定订单的所有WebSocket连接广播消息 * 实际项目中应替换为Redis Pub/Sub或消息队列 */ public static void broadcastToOrder(String orderId, Map<String, Object> data) { String msg = JSON.toJSONString(data); SESSIONS.values().forEach(s -> { try { if (s.isOpen()) { s.getBasicRemote().sendText(msg); } } catch (IOException e) { System.err.println("Broadcast to session failed: " + e.getMessage()); } }); } }

关键细节说明：

• @Component确保Spring管理该Bean，@ServerEndpoint让Tomcat识别为WebSocket端点；
• ConcurrentHashMap替代HashMap，避免多线程并发修改导致ConcurrentModificationException；
• session.getBasicRemote().sendText()是阻塞式发送，生产环境建议用session.getAsyncRemote().sendText()异步发送，避免线程阻塞；
• broadcastToOrder方法是简化版，实际项目中订单可能被多个骑手、商家、客户订阅，需用Redis的PUB/SUB或Kafka实现分布式广播。

4.4 日志与监控：快速定位每一层的失败点

当WebSocket连接失败时，按以下顺序检查日志，可80%定位问题：

层级	日志位置	关键搜索词	典型错误表现	解决方案
Nginx	logs/access.log	101、400、502	无101记录，大量400或502	检查proxy_http_version和proxy_set_header配置
Nginx	logs/error.log	upstream timed out	upstream timed out (110: Connection timed out)	增大proxy_read_timeout
Tomcat	logs/catalina.out	WebSocket、ServerEndpoint	无WebSocket日志，或ClassNotFoundException	检查tomcat-websocket.jar是否存在，JDK版本是否匹配
Spring	logs/spring.log	ServerEndpointExporter、registerEndpoint	无registerEndpoint日志	检查@Bean ServerEndpointExporter是否声明，包扫描路径是否正确
应用	logs/app.log	onOpen、onError	onOpen无日志，onError频繁触发	检查@ServerEndpoint类是否被Spring加载，构造函数是否无参

实操技巧：在Tomcat启动脚本bin/setenv.sh（Linux）或bin/setenv.bat（Windows）中添加JVM参数，增强WebSocket日志：

# Linux setenv.sh export JAVA_OPTS="$JAVA_OPTS -Dorg.apache.tomcat.util.http.parser.HttpParser.debug=true" export JAVA_OPTS="$JAVA_OPTS -Dorg.apache.coyote.http11.Http11Processor.debug=true"

重启Tomcat后，catalina.out中会出现详细的HTTP协议解析日志，可看到Upgrade请求是否被正确识别。

5. 常见问题与排查技巧实录：27个真实项目踩过的坑与速查表

5.1 Nginx层高频问题与修复方案

问题现象	错误日志特征	根本原因	修复方案	验证方式
连接立即关闭	access.log中101后紧跟499	Nginxproxy_read_timeout过短，WebSocket心跳间隔超过此值	将proxy_read_timeout设为心跳间隔的2倍（如60秒）	Postman连接后等待30秒，观察是否断开
返回200而非101	access.log中"GET /ws/... HTTP/1.1" 200	proxy_http_version未设为1.1，或proxy_set_header Upgrade未生效	检查Nginx配置语法：nginx -t，确认proxy_http_version 1.1在location块内	curl模拟Upgrade请求，检查响应头
跨域被拦截	浏览器Console报WebSocket connection to 'ws://...' failed: Error during WebSocket handshake: Unexpected response code: 403	Nginx未透传Origin头，后端校验失败	在Nginx中添加proxy_set_header Origin "";（清空Origin）或后端@CrossOrigin(origins = "*")	前端new WebSocket时添加{headers: {'Origin': 'http://localhost'}}
Nginx启动失败	nginx: [emerg] unknown directive "proxy_set_header"	Nginx版本过低（<1.1.3），不支持WebSocket代理	升级Nginx至1.24.0或更高版本	nginx -v查看版本

独家技巧：若Nginx配置复杂，可在location块中添加add_header X-Debug "Nginx-Proxy-OK";，然后用curl检查响应头是否包含此字段，快速确认Nginx配置已生效。

5.2 Tomcat层致命陷阱与绕过方案

问题现象	错误日志特征	根本原因	修复方案	验证方式
@ServerEndpoint不注册	catalina.out中无ServerEndpointExporter日志，onOpen无输出	Spring未扫描到该类，或@ServletComponentScan路径错误	在@Configuration类中添加@ServletComponentScan(basePackages = "com.xxx.websocket")	在Endpoint类中加System.out.println("Class loaded");，启动时观察是否打印
ClassNotFoundException	catalina.out中java.lang.ClassNotFoundException: javax.websocket.Session	tomcat-websocket.jar缺失或版本不匹配	检查tomcat/lib/目录，确认存在tomcat-websocket.jar；若用Tomcat 10+，需改用jakarta.websocket.*包	jar -tf tomcat/lib/tomcat-websocket.jar | grep Session
连接后立即断开	onOpen触发后onClose立即触发，session.isOpen()返回false	Tomcatconf/web.xml中<servlet>被注释，WebSocket Servlet未启动	取消conf/web.xml中<servlet>和<servlet-mapping>的注释	访问http://localhost:8080/ws/test，应返回404而非500
JDK版本冲突	catalina.out中Unsupported major.minor version 61.0	JDK 17编译的class被JDK 8运行	统一JDK版本：编译和运行均用JDK 8	java -version和javac -version必须一致

避坑心得：外置Tomcat下，@ServerEndpoint类必须是public顶层类。曾有个项目因开发者将Endpoint写成public class WebSocketConfig { public static class OrderEndpoint { ... } }，导致ServerEndpointExporter扫描时跳过内部类，耗时3天定位。

5.3 Spring层隐蔽Bug与调试秘籍

问题现象	错误日志特征	根本原因	修复方案	验证方式
ServerEndpointExporter未生效	catalina.out中无registerEndpoint日志	@Bean ServerEndpointExporter声明在@Configuration类中，但该类未被Spring加载	确保@Configuration类在@ComponentScan路径内，或用@Import显式导入	在@Bean方法中加System.out.println("Exporter created");
@OnMessage不触发	onOpen正常，但发送消息无响应	@ServerEndpoint类被Spring管理，但未注入到Tomcat WebSocket引擎	必须声明ServerEndpointExporterBean，且确保其在Spring容器启动早期创建	检查Spring Bean列表：ApplicationContext.getBeansOfType(ServerEndpointExporter.class)
Session为空指针	onMessage中session.getBasicRemote()抛NullPointerException	session对象在@OnMessage中为null，因@ServerEndpoint未被正确注册	检查@ServerEndpoint类是否有无参构造函数，且未被final修饰	在@OnOpen中打印session.getId()，确认Session对象有效
@Component失效	@ServerEndpoint类未被Spring扫描	@ComponentScan未覆盖该包，或@ServletComponentScan未启用	在Spring Boot主类上加@ServletComponentScan(basePackages = "com.xxx")	启动时搜索"Found @ServerEndpoint"日志

调试秘籍：在ServerEndpointExporter的afterPropertiesSet()方法中打断点（需下载Spring源码），可直观看到哪些@ServerEndpoint类被扫描到。若列表为空，说明包路径配置错误。

5.4 前端与网络层疑难杂症

问题现象	错误日志特征	根本原因	修复方案	验证方式
Chrome 109+连接失败	WebSocket connection to 'ws://...' failed: Error during WebSocket handshake: net::ERR_CONNECTION_RESET	Chrome 109+默认禁用不安全的WebSocket（ws://），需启用chrome://flags/#unsafely-treat-insecure-origin-as-secure	本地测试用wss://（Nginx配置SSL）或临时启用Chrome标志	访问chrome://flags搜索insecure，启用并重启
移动端连接超时	iOS Safari连接缓慢，Android WebView报net::ERR_CONNECTION_TIMED_OUT	移动端网络运营商拦截WebSocket，或DNS解析慢	在Nginx中添加proxy_set_header Host $host;，确保Host头正确	用手机访问http://ip:port/ws/test，观察是否能建立连接
Postman连接失败	Error: Unexpected server response: 404	Postman WebSocket URL路径错误，如ws://localhost:8080/order-notify少/ws/前缀	确保URL与@ServerEndpoint注解路径完全一致	复制@ServerEndpoint("/ws/order-notify")中的路径到Postman

终极验证法：当所有配置看似正确但仍失败时，用tcpdump抓包分析：

# Linux抓取8080端口WebSocket流量 sudo tcpdump -i any port 8080 -w websocket.pcap

用Wireshark打开websocket.pcap，过滤http，查看是否有HTTP/1.1 101 Switching Protocols响应。若无，则问题在Nginx或Tomcat；若有，则问题在Spring或前端。

6. 客户催单功能失效的专项修复：从消息推送到底层连接保活

6.1 催单消息推送链路：为什么“连接上了”但“消息收不到”

客户点击“催单”按钮后，前端发送HTTP请求到后端API（如POST /api/order/123456/urge），后端处理完应通过WebSocket向该订单的骑手、商家推送消息。但常出现“连接正常，但催单消息不达”的情况，根源在于：