http-proxy-middleware WebSocket 路径重写怎么配：代理转发与断连排查

WebSocket 断连通常发生在路径重写、Upgrade 握手、上游地址或空闲超时层。先对照客户端路径、重写后路径和上游日志，再按状态码定位。

如何检查客户端路径和 pathRewrite 规则

记录客户端 URL、target、pathRewrite 前后路径和上游实际收到的路径。例如客户端请求 /socket/chat，重写后可能转为上游 /chat；以日志中的真实路径为准。普通 HTTP 路由可达后再测试 WebSocket。

Node.js 客户端代理字段可参考Node.js axios 和 fetch 怎么设置代理 IP。

WebSocket 请求如何完成 Upgrade 握手

确认请求包含 Upgrade: websocket 和 Connection: Upgrade，服务端入口监听 upgrade，中间件启用了 WebSocket 支持。返回 101 只表示协议升级成功；未返回 101 时先查请求头、监听入口和路径。

遇到连接超时或拒绝时，可参考代理 timeout、connection refused 和 TLS 证书错误怎么排查。

用同一客户端比较直连上游与经过中间件的握手结果。状态码和断开时间已能定位故障层时，不要同时修改路径、target 和超时。

下面根据握手现象定位路径、升级入口或上游连接。

确定故障层后只修改一个变量，再用同一客户端复测。

400、404、502 或 101 后断开怎么查

记录客户端请求 URL、重写前后路径、上游收到的路径、Upgrade 请求头、响应状态、首个数据帧时间和关闭时间。400/404 通常先查请求头或路径映射，502 查 target 和上游连通性，101 后立即断开查上游协议与关闭日志，固定空闲时间断开再查心跳和超时。

用路径映射确认上游收到的 URL

下面只展示字段关系，具体 API 按当前 http-proxy-middleware 版本核验：

```js
createProxyMiddleware({
target: "https://upstream.example",
ws: true,
pathRewrite: { "^/socket": "" }
})
```

客户端请求 /socket/chat 时，日志应能对应 target=/chat、upgrade=101、upstream=connected；若返回 404 先查重写后路径，502 查上游连接，101 后立即断开则继续查空闲超时和关闭原因。

如何确认路径重写和 WebSocket 转发正常

先确认普通 HTTP 路由可达，再确认 WebSocket 返回 101，最后观察首个数据帧和持续连接。每次只调整路径、target、upgrade 入口或超时中的一项；配置 API 和字段按当前 http-proxy-middleware 版本核验。

FAQ

普通 HTTP 成功但 WebSocket 不能升级怎么办？

普通路由不代表 upgrade 生效，应检查握手头、ws 选项和服务端 upgrade 监听。

pathRewrite 后如何确认上游实际收到的路径？

查看上游访问日志，对照客户端请求路径、重写规则和上游收到的最终路径。

返回 404 和 502 时分别先查哪里？

404 先查客户端 URL 和路径映射；502 先检查 target、端口和上游服务是否可达。

握手返回 101 后立即断开怎么办？

检查上游协议、心跳、首个数据帧和连接关闭日志。101 表示握手升级完成，不代表长连接已经稳定。