本文详解如何在 nginx 中通过正则匹配（location ~ ^/ws/）精准代理 websocket 子路径（如 /ws/app1、/ws/v2/chat），避免因前缀匹配失效导致握手失败，并确保 upgrade 和 connection 头被正确透传。
本文详解如何在 nginx 中通过正则匹配（location ~ ^/ws/）精准代理 websocket 子路径（如 /ws/app1、/ws/v2/chat），避免因前缀匹配失效导致握手失败，并确保 upgrade 和 connection 头被正确透传。
在生产环境中，WebSocket 服务常需支持多租户或版本化路径（例如 /ws/v1/notifications、/ws/app2/events），但若仅使用 location /ws { ... } 这类前缀匹配（prefix match），Nginx 实际仅匹配以 /ws 开头的 URI，且不自动继承子路径到 proxy_pass 目标——更关键的是，当后端服务期望完整路径（如 /ws/app1）时，proxy_pass http://localhost:8443/ws; 会将请求重写为 /（即截断 /ws 后所有内容），导致后端无法识别路由。
✅ 正确做法是：使用正则表达式 location 块 + 精确路径透传，同时保留 WebSocket 协议升级必需的 HTTP/1.1 头部。
✅ 推荐配置（支持 /ws/** 任意子路径）
server {
listen 443 ssl;
server_name www.mydomain.com mydomain.com;
ssl_certificate /path/to/fullchain.pem;
ssl_certificate_key /path/to/privkey.pem;
ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:...;
ssl_prefer_server_ciphers on;
# WebSocket 通配路径：匹配 /ws/ 开头的所有请求（含多级子路径）
location ~ ^/ws(/.*)?$ {
proxy_pass http://localhost:8443; # 注意：此处不带尾部 /ws → 保持原始 URI
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
# 防止连接过早关闭（WebSocket 需长连接）
proxy_read_timeout 86400; # 24小时，可根据业务调整
proxy_send_timeout 86400;
}
# 普通 HTTPS 请求（非 WebSocket）走主应用
location / {
proxy_pass https://localhost:8443; # 或 http，根据后端实际协议
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
? 关键说明
location ~ ^/ws(/.*)?$：
~ 表示区分大小写的正则匹配；^/ws(/.*)?$ 精确匹配 /ws 或 /ws/xxx（包括多层嵌套），不匹配 /websocket 或 /ws123，语义清晰、无歧义。proxy_pass http://localhost:8443;（结尾无 /ws）：
这是实现路径透传的核心——Nginx 将原始请求 URI（如 /ws/app1/connect）原样转发给后端，后端 Go 服务可基于完整路径做路由分发。-
❌ 错误写法对比：
location /ws { proxy_pass http://localhost:8443/ws; } # ❌ 截断路径，/ws/app1 → 后端收到 /app1 location /ws/ { proxy_pass http://localhost:8443/ws/; } # ❌ 同样截断，且不匹配 /ws（无尾斜杠） ⚠️ 关于“全局设置 Upgrade 头”的风险提示：
虽然将 Upgrade 和 Connection 头放在 location / {} 中看似简化配置，但不符合 HTTP 规范：非 WebSocket 请求携带 Connection: upgrade 可能被中间设备（如某些企业防火墙、CDN）拒绝或静默丢弃；Go 标准库 net/http 也会在非升级请求中忽略这些头，但部分自定义服务可能报错。因此，严格按协议语义，仅在 WebSocket 路径下启用升级头，是健壮性与兼容性的最佳实践。
✅ 验证是否生效
- 使用浏览器开发者工具 → Network 标签页，发起 wss://mydomain.com/ws/app1 连接；
- 查看请求 Headers：确认包含 Upgrade: websocket 和 Connection: Upgrade；
- 查看响应状态码：应为 101 Switching Protocols；
- 终端快速测试：
wscat -c wss://mydomain.com/ws/test # 成功连接即表示 Nginx 透传与握手均正常
? 提示：若后端为 Go（如 gorilla/websocket），请确保其 Upgrader.CheckOrigin 已适配反向代理场景（例如允许 X-Forwarded-Proto: wss 或校验 Origin 头），否则可能因跨域拒绝握手。
通过上述配置，您即可安全、精准地支持任意深度的 WebSocket 子路径，兼顾标准合规性、运维可维护性与生产稳定性。
