Nginx WebSocket 通配路径匹配与 location 优先级详解-Golang-PHP中文网

本文详解 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 本身即为“以该字符串开头”，而非“完全相等”。

Nginx Hosting
通过服务器本地nginx实例实现零认证静态游戏托管。作为所有浏览器游戏的主要部署方式，无需登录、无需令牌、无需用户操作。

下载

✅ 正确配置 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 服务容忍了，但不符合规范）。