本文详解 Nginx 中如何正确配置支持 WebSocket 的通配路径（如 /ws/ 及其子路径），阐明 location 匹配机制、修饰符优先级及代理头设置要点，避免因匹配失效导致 WebSocket 升级失败。
本文详解 nginx 中如何正确配置支持 websocket 的通配路径（如 `/ws/` 及其子路径），阐明 `location` 匹配机制、修饰符优先级及代理头设置要点，避免因匹配失效导致 websocket 升级失败。
在反向代理 WebSocket 服务时，常见误区是误以为 location /ws 能匹配 /ws/app1、/ws/v2/health 等所有以 /ws 开头的路径——实际上它确实可以，但前提是该 location 块必须被正确选中，且不被更高优先级的 location（如更长前缀或正则）覆盖。
? 为什么 location /ws 看似“不生效”？
Nginx 的 location 匹配遵循严格优先级规则，并非按配置顺序执行。根据 NGINX 官方文档 与 DigitalOcean 权威解析：
- location /ws 是 prefix match（前缀匹配），等价于 location ^~ /ws；
- 它会匹配所有以 /ws 开头的 URI，例如 /ws、/ws/、/ws/chat、/ws/api/v1；
- ✅ 但它仅在无更精确匹配时生效：若同时存在 location = /ws（精确匹配）或 location ^~ /ws/chat（更长前缀），则后者优先；
- ❌ 更关键的是：若存在 location /（根前缀）且位于 location /ws 之后，它仍可能因“最长前缀”规则被选中——但实际中 location / 是最短前缀，不会覆盖 /ws；真正的问题常出在配置顺序与匹配逻辑混淆，或遗漏 WebSocket 必需的代理头。
⚠️ 注意：location /ws 后面不加斜杠 / 并不影响匹配 /ws/xxx ——因为 prefix match 本身即为“以该字符串开头”，而非“完全相等”。
✅ 正确配置 WebSocket 通配路径（推荐方案）
为确保 /ws/* 所有子路径均走 WebSocket 代理，同时 / 及其他路径走普通 HTTP 代理，应显式分离并利用匹配优先级：
server {
listen 443 ssl;
server_name www.mydomain.com mydomain.com;
add_header Strict-Transport-Security "max-age=31536000";
# ✅ 高优先级：精确匹配 /ws/（可选） + 前缀匹配 /ws，覆盖所有子路径
location ^~ /ws/ {
proxy_pass http://localhost:8443/ws/;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header Upgrade $http_upgrade; # 关键：透传 Upgrade 头
proxy_set_header Connection "upgrade"; # 关键：强制升级连接
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;
# 可选：防止超时中断长连接
proxy_read_timeout 86400;
proxy_send_timeout 86400;
}
# ✅ 次优先级：通用前缀匹配，处理其余所有路径（/、/api、/static 等）
location / {
proxy_pass http://localhost:8443/;
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;
proxy_redirect off;
}
}✅ 关键说明：
- ^~ /ws/ 明确声明为非正则前缀匹配，且因 /ws/ 比 / 更长，Nginx 会优先选择它处理 /ws/xxx 请求；
- proxy_pass 末尾的 / 至关重要：proxy_pass http://localhost:8443/ws/; 会将 /ws/chat 重写为 http://localhost:8443/ws/chat；若写成 .../ws（无尾斜杠），则 /ws/chat 会被错误映射为 /wschat；
- Upgrade 和 Connection 头必须在匹配到 WebSocket 路径时才设置，否则普通 HTTP 请求携带这些头可能被后端拒绝（尽管你的 Go 服务容忍了，但不符合规范）。
? 不推荐的“偷懒方案”（为何应避免）
如问题中 EDIT 部分所示，将所有头（包括 Upgrade/Connection）统一放在 location / 中虽能“临时跑通”，但存在严重隐患：
- ❌ 违反 HTTP/1.1 协议语义：非 WebSocket 请求不应发送 Upgrade: websocket；
- ❌ 可能触发后端中间件异常日志或安全策略拦截；
- ❌ 丧失路径语义隔离，难以调试与审计；
- ❌ 无法独立配置 WebSocket 特定参数（如超时、缓冲区大小）。
? 总结：WebSocket location 配置三原则
- 用 ^~ 显式声明前缀匹配，避免歧义（如 location ^~ /ws/）；
- 保证路径长度优先级：/ws/ > /ws > /，合理组织 location 顺序；
- 仅在匹配 WebSocket 路径时设置 Upgrade/Connection，保持协议合规性与可维护性。
通过精准运用 location 修饰符与匹配逻辑，你无需正则即可稳健支撑全量 WebSocket 子路径代理——既符合 Nginx 设计哲学，也利于长期运维与安全加固。
