Nginx 反向代理上手：location 匹配与 proxy_pass 的四个常见坑

反向代理是 Nginx 最高频的用法：把请求转发给后端应用，自己只负责接入层。但很多人照着网上的配置抄一遍，遇到 404 或者后端拿不到真实 IP 就没了头绪。问题大多出在 location 的匹配优先级和 proxy_pass 的末尾斜杠上，本文用一个最小配置把这两件事讲清楚。

先看一段最小可用配置：

server {
    listen 80;
    server_name app.example.com;

    location /api/ {
        proxy_pass http://127.0.0.1:8080/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }

    location / {
        root /var/www/html;
        try_files $uri $uri/ =404;
    }
}

坑一：location 不是“谁写在前面谁生效”。 精确匹配 = 优先级最高，其次是 ^~ 前缀匹配，然后是正则 ~/~*，最后才是普通前缀匹配。想让某个路径固定走后端，用 location ^~ /api/ 更可控，避免被后面的正则规则截胡。

坑二：proxy_pass 末尾带不带斜杠，转发路径不一样。 proxy_pass http://127.0.0.1:8080/; 会把 /api/user 转成 /user；写成 proxy_pass http://127.0.0.1:8080;（无斜杠）则原样转发 /api/user。后端路由对不上时，多半就是这里差了一个斜杠。

坑三：后端拿不到客户端真实 IP。 默认情况下后端看到的是 Nginx 的地址，必须用 proxy_set_header 把 X-Real-IP、X-Forwarded-For 传下去，后端框架也要开启“信任反向代理”的配置，否则访问日志里全是 127.0.0.1。

坑四：WebSocket 或长连接接口直接转发会断。 需要额外加 Upgrade、Connection 头并放大读超时：

proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_read_timeout 300s;

改完配置先用 nginx -t 校验，再 nginx -s reload 平滑生效。排查时用 curl -H "Host: app.example.com" http://127.0.0.1/api/user -v 直接打本机，可以快速区分是 Nginx 转发问题还是后端问题。

反向代理的配置本身不复杂，复杂的是路径改写和请求头传递的细节。把上面四个坑记住，能省掉大半天的排障时间。