Nginx代理后Webpack WebSocket持续连接失败问题排查及原因咨询

我近期配置了一套服务器架构（开发环境中dev.com被映射为localhost）：

------   if (dev.com)  ----> localhost:3000
                                      |
dev.com:443 / api.dev.com:443 --- [compute / nginx reverse proxy]
                                      |
                                      ------ if(api.dev.com) ----> localhost:8000 

除开发者控制台定期打印连接失败消息外，我的React应用运行正常。我认为这与Webpack有关，但对其不够熟悉，不清楚具体原因。尝试设置环境变量WDS_SOCKET_PORT=443后，连接仍失败但报错信息变化。

dev.com:443的连接应通过代理路由到与初始站点包下载相同的服务器，我不确定问题所在。

项目依赖如下：

"dependencies": {
    "@testing-library/jest-dom": "^5.16.5",
    "@testing-library/react": "^13.4.0",
    "@testing-library/user-event": "^13.5.0",
    "axios": "^1.4.0",
    "bootstrap": "^5.3.0",
    "jwt-decode": "^3.1.2",
    "nodemon": "^2.0.22",
    "react": "^18.2.0",
    "react-bootstrap": "^2.8.0",
    "react-dom": "^18.2.0",
    "react-router-dom": "^6.14.0",
    "react-scripts": "^5.0.1",
    "web-vitals": "^2.1.4"
  },

将服务器置于Nginx代理后才出现此问题，请问是什么原因？另外，能否解释Webpack为何要维持这种持续连接？

设置DEBUG='express:*'后，看到Webpack开发服务器调试日志，反向代理的/ws请求已被路由，但服务器返回404：

express:router dispatching GET /ws +6s
  express:router query  : /ws +0ms
  express:router expressInit  : /ws +1ms
  express:router handleWebpackInternalMiddleware  : /ws +0ms
  express:router compression  : /ws +0ms
  express:router trim prefix (/ws) from url /ws +0ms
  express:router bound setHeaders /ws : /ws +0ms
  express:router middleware  : /ws +1ms
  express:router serveStatic  : /ws +0ms
  express:router <anonymous>  : /ws +9ms
  express:router middleware  : /ws +1ms
  express:router serveStatic  : /ws +0ms
  express:router middleware  : /ws +7ms
  express:router bound serveMagicHtml  : /ws +6ms
  express:router trim prefix (/ws) from url /ws +0ms
  express:router middleware /ws : /ws +0ms
  express:router redirectServedPathMiddleware  : /ws +1ms
  express:router noopServiceWorkerMiddleware  : /ws +0ms

一、Nginx代理导致连接失败的原因及解决方法 #

你遇到的是Webpack Dev Server（WDS）的WebSocket连接失败问题。从日志可以看到/ws请求返回404，核心原因是Nginx未正确处理WebSocket协议的请求转发，同时WDS的WebSocket配置未与代理规则匹配。

具体原因： #

• WebSocket协议未升级：WebSocket请求初始是HTTP请求，但会触发协议升级，Nginx默认不会自动处理该逻辑，需额外配置。
• 路径转发规则缺失：React Scripts 5.x版本中WDS默认使用/ws作为WebSocket路径，你的Nginx代理未针对该路径做转发配置。
• 环境变量配置不完整：仅设置WDS_SOCKET_PORT=443不够，还需指定WDS_SOCKET_HOST和WDS_SOCKET_PATH，否则前端会向错误地址发起连接。

解决步骤： #

1. 更新Nginx配置，支持WebSocket代理
   在dev.com的server块中添加以下配置，处理协议升级和路径转发：

location /ws {
    proxy_pass http://localhost:3000;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
}

2. 完善WDS环境变量配置
   在启动React应用时，设置完整的WebSocket相关变量：

WDS_SOCKET_HOST=dev.com WDS_SOCKET_PORT=443 WDS_SOCKET_PATH=/ws react-scripts start

或者在项目的.env.development文件中添加：

WDS_SOCKET_HOST=dev.com
WDS_SOCKET_PORT=443
WDS_SOCKET_PATH=/ws

这样前端会向dev.com:443/ws发起WebSocket连接，Nginx会将请求正确转发到localhost:3000/ws并处理协议升级。

二、Webpack维持持续连接的原因 #

Webpack Dev Server维持的持续连接是WebSocket连接，核心作用是实现热模块替换（HMR, Hot Module Replacement）：

• 当你修改代码时，WDS会自动编译更新的模块，通过WebSocket主动通知浏览器，无需刷新页面即可替换更新的模块，保留当前页面状态，大幅提升开发效率。
• 若没有这个连接，WDS无法主动推送更新，你只能手动刷新页面才能看到代码修改效果，开发体验会大幅下降。

此外，该连接还用于实时传递开发日志、错误信息等，让开发者能在控制台即时获取反馈。

内容的提问来源于stack exchange，提问作者sherrellbc