Nginx 反向代理配置要点：路径、请求头与 WebSocket 三处最容易踩坑

新手第一次配 Nginx，往往从“把域名指向一台内网服务”开始。反向代理本身不复杂：用户访问 Nginx，Nginx 按规则把请求转发给身后的应用，再把响应带回。但几个细节一旦写错，就会出现 502、接口 404、实时数据断连这类问题。下面是最常见的要点。

一、proxy_pass 末尾的斜杠，决定路径怎么拼

location 是 /api/、请求是 /api/user 时：

- proxy_pass http://127.0.0.1:3000;（无斜杠）：后端收到完整路径 /api/user。

- proxy_pass http://127.0.0.1:3000/;（有斜杠）：location 匹配部分被替换，后端收到 /user。

两种写法都没错，但必须和后端的路由预期对上。接口莫名 404 时，先看这一行，而不是怀疑后端挂了。

二、四个转发头，别漏

默认情况下 Nginx 不会把客户端信息带给后端，需要手动补：

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;

漏了 Host，后端可能认不出域名；漏了 X-Real-IP，后端日志里所有请求都来自 127.0.0.1，没法定位问题；漏了 X-Forwarded-Proto，后端可能误判协议，把 https 跳回 http，造成重定向循环。

三、WebSocket 要单独加三行

带实时通信的应用（在线终端、聊天、数据看板），普通 HTTP 转发会让 WebSocket 握手失败：

proxy_http_version 1.1;

proxy_set_header Upgrade $http_upgrade;

proxy_set_header Connection "upgrade";

症状很典型：页面能打开，但实时数据就是不更新，十有八九是这里漏了。

四、超时按后端脾气调

默认代理超时一般是 60 秒，上传大文件、导出报表这类长任务很容易中途断开。可以按 location 单独放宽：proxy_read_timeout 300s; 等。但超时不是越大越好，过长会让慢请求长期占着连接。

五、上线前必做的事

改完配置先 nginx -t 测语法，通过后再 nginx -s reload。直接重载一个语法错误的配置，会让整个服务起不来。等规则变多时，把上游抽成 upstream 块做负载均衡，结构依然清晰。

一套可直接套用的模板：

server {

    listen 80;

    server_name example.com;

    location / {

        proxy_pass http://127.0.0.1:3000;

        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_http_version 1.1;

        proxy_set_header Upgrade $http_upgrade;

        proxy_set_header Connection "upgrade";

    }

}

把端口和域名换成自己的，检查通过后重载即可。排查时按“路径、请求头、协议升级、超时”这个顺序，大多数故障十分钟内就能定位。