Nginx请求转发实战：从location匹配到故障排查全解析-AI智能范式网

Nginx 的请求转发，说白了一句话：让 Nginx 帮我们把请求按规则送到正确的后端服务上。但就是这么个"送快递"的活，我在生产环境里踩过的坑，比很多人写的博客加起来都多。比如 location 写了个 /api，结果 /api/v1 和 /api2 都被拦了；比如后端接口明明通着，前端却报 404；再比如转发之后拿不到用户真实 IP，登录态全乱套。这篇内容没有教科书式的长篇大论，全是基于真实业务场景的配置思路和可复制的配置片段。无论你是刚入门的运维，还是被前后端联调折磨的开发，这篇内容能帮你少走很多弯路。

1. 请求转发的本质：Nginx 到底在转发什么

1.1 从"快递分拣"理解 Nginx 的定位

我在跟团队里新人讲 Nginx 的时候，喜欢拿快递分拣中心来打比方。你的应用服务器（比如 Java 的 Tomcat、Node 的 Express）就像一个个具体的收货地址，而 Nginx 就是那个巨大的分拣中心。用户发起的 HTTP 请求就像一个个快递包裹，包裹上面写着"我要去哪个地址"，也就是 URL 和请求头。Nginx 要做的，就是根据包裹上的信息，把它准确无误地扔到对应的传送带上，送到正确的收货点去。

但这里有个关键点：Nginx 不只是简单地按地址配送，它还能改地址。它可以在转发过程中修改请求的路径、添加或删除请求头，甚至可以决定这个包裹是发给 A 仓库还是 B 仓库，这就涉及负载均衡了。所以，请求转发的本质，是 Nginx 在七层（应用层）对 HTTP 协议进行的"解析—改写—分发"过程。

我见过不少刚接触 Nginx 的开发者，以为配置转发就是把 proxy_pass 一写就完事。实际上，Nginx 处理一个转发请求，内部是有完整的流程的：

解析请求行，拿到请求方法、URI、HTTP 版本。
匹配 server 块中的 listen 端口和 server_name。
在选定的 server 块内，按规则匹配 location。
在命中的 location 中执行 proxy_pass 等指令，构造上游请求。
连接上游服务器，转发请求，接收响应，再返回给客户端。

任何一个环节出问题，表现在用户端就是各种奇怪的报错。理解了这一点，排查问题时你才知道该从哪里下手。

1.2 为什么业务系统离不开反向代理

可能有人会问，我后端服务直接监听 80 端口不行吗？为什么要多一层 Nginx？这个问题我每次都会被问到。我的回答通常是：行，但前提是你只有一个后端服务、不需要 HTTPS、不需要动静分离、不担心流量波动——现实里几乎没有这种场景。

Nginx 做请求转发带来的核心价值，归纳下来其实就四点：

统一入口：多个后端服务（比如订单服务、用户服务、支付服务）可以对外暴露同一个域名、同一个端口，由 Nginx 根据路径或域名来分发。Nginx 在中间可以做一层接口隔离，不直接把内部服务地址暴露出去。
负载均衡：当单台后端压力大的时候，upstream 可以配置多台后端，Nginx 按照权重、IP 哈希或者最少连接数等策略分发请求，帮后端扛住大流量。
解耦与扩展：前端是静态页面、后端是接口服务，用 Nginx 把两者分开部署、分开扩容。前端挂了不影响后端，后端升级也不用动前端配置。
安全与统一控制：可以在 Nginx 层统一做 HTTPS 证书卸载、基础访问认证、限流、IP 黑白名单，让后端服务专注于业务逻辑。

每次有朋友问我"我的系统要不要加个 Nginx"，我的建议是：只要你的系统需要对外提供服务，且不止一个独立模块，就直接上 Nginx，别犹豫。它替后端挡掉的事远比带来的配置成本多得多。

需要模型API调用？免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。

2. 配置前的关键选择：方案与核心参数定调

2.1 先想清楚四大选型问题

很多教程上来就贴配置，但我建议你先坐下来，花两分钟回答下面四个问题。方案没定，配出来的转发大概率是空中楼阁。

第一，转发的目标是什么形态？ 是转发到固定的 IP+端口？还是转发到一组后端服务器做负载均衡？前者用一条 proxy_pass 就够了，后者需要定义 upstream。这是两个完全不同的配置结构。

第二，路径要不要重写？ 前端请求的 URL 路径和后端实际接口路径是否一致？比如前端请求 /api/user/list，后端接口是 /user/list，那 location 和 proxy_pass 怎么组合才能把 /api 这部分去掉？这一块是最容易出错的，后面我会单独讲。

第三，请求头需要怎么处理？ 后段接口是否需要真实的客户端 IP？是否需要原始 Host？WebSocket 场景要不要升级协议头？这直接关系到要不要配 proxy_set_header，以及配哪些字段。

第四，超时和缓冲的容忍度是多少？ 后端接口是秒回还是可能有长耗时的文件导出任务？Nginx 默认的超时时间能不能满足？如果上游响应慢，Nginx 默认 60 秒就断开了，得提前调。

我之前接手过一个电商项目，搜索接口偶尔会超过 60 秒才返回，结果 Nginx 先断开了连接，前端拿到的是 504。后来调了 proxy_read_timeout 才解决。这种问题不提前想，上线后就是事故。

2.2 工具准备与基础环境检查

在动手改配置之前，我强烈建议先确认基础环境是正常的。别一上来就改 Nginx，结果最后发现问题出在其他地方。

你至少需要确认这么几件事：

Nginx 已正确安装。Linux 上用 nginx -v 查看版本，Windows 上到安装目录执行同样的命令。如果没装，各系统的安装方式不一样，这里不展开，但务必定好版本，尽量用主线版本。
后端服务地址可达。在服务器上直接用 curl http://127.0.0.1:8080/health 看看能不能通，确认后端本身没毛病。
配置文件语法改完后能用。Nginx 改了配置，一定要先 nginx -t 做语法检查，不要直接 reload。
防火墙和端口策略。如果 Nginx 和后端不在同一台机器，要确保 Nginx 服务器能访问后端的端口，安全组和本机防火墙都要放通。

我给过一个结论：排查请求转发问题，90% 的时间不是在 Nginx 本身，而是在它前面的 DNS、后面的后端服务，以及中间的防火墙。基础环境不稳，配置再花哨也没用。

2.3 配置文件结构：你要改的是哪个文件

拿到一台新服务器，很多人会习惯性打开 nginx.conf 从头看起。但我建议你先搞清楚配置文件的结构，避免在不该改的地方乱加配置。

Nginx 的主配置文件通常长这样：

nginx复制# 主配置 nginx.conf
user  nginx;
worker_processes  auto;

events {
    worker_connections  1024;
}

http {
    include       /etc/nginx/mime.types;
    default_type  application/octet-stream;

    # 核心：http 块内的 server 才是虚拟主机配置
    server {
        listen       80;
        server_name  example.com;

        location / {
            proxy_pass http://127.0.0.1:8080;
        }
    }
}

比较常见的做法是：在主配置文件的 http 块里用 include /etc/nginx/conf.d/*.conf; 引入子配置。每个业务域名的反向代理配置，就单独放在 conf.d/ 下一个 .conf 文件里，互不干扰，也方便回滚。

这里我特别想提醒一句：修改配置之前，先把原文件备份一份，命令也很简单：

bash复制cp /etc/nginx/nginx.conf /etc/nginx/nginx.conf.bak
cp /etc/nginx/conf.d/myapp.conf /etc/nginx/conf.d/myapp.conf.bak

改挂了随时能还原，这是我一贯的底线。没有备份的习惯，早晚要吃大亏。

3. 核心配置实操：不同类型转发的完整写法

3.1 最基础的单点转发配置

先看一个最基础但完整度足够高的配置。假设你有一个 Java 后端跑在 127.0.0.1:8080，前端页面跑在 127.0.0.1:3000，你想让所有请求都从 80 端口进来，按路径分流。

nginx复制server {
    listen 80;
    server_name _;   # 匹配任意域名，适合 IP 直连的场景

    # 前端静态页面
    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    # 后端接口
    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 /api/ 和 proxy_pass http://127.0.0.1:8080; 搭配时，URI 的传递规则。Nginx 规则很简单：如果 proxy_pass 后面不带 URI（也就是没有路径部分），那么转发时会把原始请求的完整 URI 原样传给后端。所以 /api/user/list 会被转发为 http://127.0.0.1:8080/api/user/list。前面我们提到的路径重写（去掉 /api）就要靠另一种写法，后面 3.3 节单独讲。

第二个是 proxy_set_header Host $host。默认情况下，Nginx 转发请求时会带上原始的 Host 头。但有些后端框架（比如 Spring Boot 内部跳转、多租户系统）对 Host 非常敏感，你不显式设置，后端拿到的主机名可能是内网 IP，脚本拼接出的外链就乱了。所以这个配置我建议每次转发都写上，等于是告诉后端"客户端访问的域名是哪个"。

第三个是 proxy_set_header X-Real-IP $remote_addr 和 X-Forwarded-For。不加这两个头，后端的应用日志里记录的所有访问 IP 都成了 Nginx 服务器的内网 IP，做审计、做风控、做地区统计的时候全瞎了。X-Real-IP 是 Nginx 的变量，代表直接跟 Nginx 建立 TCP 连接的客户端 IP；X-Forwarded-For 是每一级代理追加记录的标准头，$proxy_add_x_forwarded_for 会自动把已有的 XFF 值和当前连接 IP 拼接起来。

3.2 反向代理到 upstream 负载均衡集群

如果后端服务不止一台，那 proxy_pass 后面直接写 IP 就不合适了。你需要先定义一个上游服务器组，然后在 location 里引用它。这是 Nginx 做负载均衡的标准姿势。

nginx复制upstream backend_servers {
    # 默认是轮询策略
    server 192.168.1.10:8080 weight=3;
    server 192.168.1.11:8080 weight=1;
    server 192.168.1.12:8080 backup;  # 备用节点，平时不参与，前两台挂了才启用
}

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

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

这里 weight=3 的意思是权重分配，3 台能分到的流量比例大概是 3:1:0（备用不参与）。从实际使用来说，upstream 里常用的策略有几种：

轮询（默认）：请求依次分发到每一台上游服务器，适合所有后端机器配置差不多的情况。
weight 权重：在轮询基础上加上权重，适合机器配置高低不一的集群。
ip_hash：按客户端 IP 的哈希结果固定分配后端，解决需要保持会话（session 未集中管理）的场景。
least_conn：把请求分发给当前活跃连接数最少的那台上游，适合后端请求处理时间差异较大的情况。

给个小建议：如果后端是无状态服务，优先用默认轮询或 least_conn；如果后端用了本地 Session、没有抽离登录态，就用 ip_hash，否则用户刷新一下就掉登录，这个锅最后还是会甩给前端。

3.3 路径重写：proxy_pass 带不带斜杠的天壤之别

这个坑我必须要单独拎出来说，因为几乎每个用过 Nginx 转发的人都被它坑过。核心就一句话：location 后面带的路径和 proxy_pass 后是否带 URI，决定了转发后的最终 URL 长什么样。

我用一个例子来说。假设客户端请求的是 http://example.com/api/user/list：

配置一：location /api/ { proxy_pass http://127.0.0.1:8080; }
转发后：http://127.0.0.1:8080/api/user/list（路径原样传递，/api 保留）
配置二：location /api/ { proxy_pass http://127.0.0.1:8080/; }
转发后：http://127.0.0.1:8080/user/list（proxy_pass 里的 / 替换掉了 location 匹配到的 /api/，注意这里不是简单删除前缀，而是用 URI 中的 / 整体替换了 location 匹配的部分）
配置三：location /api { proxy_pass http://127.0.0.1:8080; }
转发后：http://127.0.0.1:8080/api/user/list（如果 location 不带尾部斜杠，匹配到的片段是 /api，后面 location 也用到了正则，原样保留后面的路径）
配置四：location /api { proxy_pass http://127.0.0.1:8080/; }
转发后：http://127.0.0.1:8080/user/list（同样，proxy_pass 的 / 替换了 location 匹配的 /api 部分）

这里我通常跟团队说：proxy_pass 带不带末尾斜杠，是重写路径最简单粗暴的手段。如果你想让后端接口路径和前端请求路径完全一致，就用不带 URI 的写法；如果想去掉某个前缀，就在 proxy_pass 末尾加上斜杠。

但要注意，这里有个隐蔽的坑：当 location 用正则表达式匹配时，proxy_pass 中不能包含 URI 部分，否则 Nginx 根本不会加载配置直接报错。比如：

nginx复制# 这种写法会报错
location ~ ^/api/ {
    proxy_pass http://127.0.0.1:8080/v1/;
}

# 只能这样写，URI 只能在 location 内通过 rewrite 完成
location ~ ^/api/ {
    rewrite ^/api/(.*)$ /v1/$1 break;
    proxy_pass http://127.0.0.1:8080;
}

我在给一家公司做技术咨询时就碰到过这种配置，对方一脸懵：为什么 nginx -t 报错？其实不是语法错，是 Nginx 的设计约束。你只要记住：正则 location 里的 proxy_pass 不带路径，想重写就配 rewrite，逻辑会更清晰。

3.4 location 匹配规则与优先级

想配置好 Nginx 转发，不搞懂 location 的匹配规则是不行的。我见过太多人栽在"为什么这个请求没走我预期的 location"上。其实 Nginx 的匹配优先级就五句话：

先做精确匹配（location = /path），命中就直接用，后面的规则不再看。
再做前缀匹配，找最长的匹配前缀。
如果最长的前缀匹配是 ^~ 开头的，直接用这个 location，不再检查正则。
然后按顺序检查正则匹配（location ~ 区分大小写，location ~* 不区分大小写），只要命中就停止。
如果正则都没有命中，才使用前面记录的最长前缀匹配。

直接上个例子：

nginx复制location = /api {
    return 200 "exact match";
}

location ^~ /api/ {
    proxy_pass http://127.0.0.1:8080;
}

location ~ \.(php|jsp)$ {
    proxy_pass http://127.0.0.1:9000;
}

在上面配置里，请求 /api/user 会因为 ^~ 前缀匹配命中第二个；请求 /index.php 会被正则命中第三个；请求 /api（注意没有尾斜杠）会命中第一个精确匹配。

很多人会忽略的细节是：前缀匹配没有 ^~ 符号时，优先级反而低于正则。我遇到过一个问题，静态目录 location /static/ 命中了，但里面嵌套了个正则 location ~* \.jpg$，结果所有 .jpg 请求都被正则规则截走了，静态资源加载不出来。排查了不少时间，原因就是规则优先级没理清。所以配置 location 之前，先把少数特殊路径用 = 精确匹配掉，再把常规转发按前缀写，正则能不用就不用，这是最不容易出错的套路。

3.5 关键转发参数与调优经验

请求转发不是"能通就行"，在高并发或特殊场景下，下面这些参数的敏感度非常高。我整理了一张表，是我在多个项目中沉淀下来的推荐起始值，具体可以按实际情况调整：

参数	作用	我的常用起始值	备注
`proxy_connect_timeout`	与后端建立连接的超时时间	5s	内网后端这个值可以更小，跨公网转发放大一点
`proxy_read_timeout`	读完后端响应的超时时间	60s	有导出、批量任务需加大到 300s 或更高
`proxy_send_timeout`	把请求发给后端的超时时间	60s	通常不用动，除非后端接收很慢
`proxy_buffer_size`	后端响应头缓冲区大小	8k	后端 Set-Cookie 或响应头特别大时要调大
`proxy_buffers`	响应体缓冲区	8 4k	调整过大可能吃内存，小流量保持默认即可
`proxy_set_header`	设置转发请求的头信息	按需	Host、X-Real-IP、X-Forwarded-For 必配

举个例子，我之前做过一个报表系统，前端点一下"导出 Excel"，后端要跑两三分钟才返回文件。默认 proxy_read_timeout=60s，结果每次导出超过 60 秒就 504，用户疯狂提工单。后来在 location 里单独给这个接口加了一条配置：

nginx复制location /export/report {
    proxy_pass http://127.0.0.1:8080;
    proxy_read_timeout 300s;
    proxy_buffering off;   # 流式输出，边生成边下载
}

proxy_buffering off 是好东西，对实时性要求高的接口（比如 SSE、大文件流式下载）特别有用。它让 Nginx 不做缓冲，后端一有响应数据就直接发给客户端。代价是性能稍有降低，但在长连接场景里，体验提升远大于那点损耗。

再一个容易被忽略的是 proxy_http_version。默认 Nginx 转发用的 HTTP 协议版本是 1.0，而 HTTP 1.0 不支持 keep-alive 连接复用，每次转发都重新建立 TCP 连接，高并发下握手开销非常明显。我建议在 upstream 场景下显式设置：

nginx复制proxy_http_version 1.1;
proxy_set_header Connection "";

这行配置让 Nginx 用 HTTP 1.1 协议转发，并清空 Connection 头，使上游连接可以复用。我实测在一个日活几十万的网关层加了这个配置后，后端连接数下降非常明显，性能提升肉眼可见。

4. 进阶场景：多项目部署与常见架构设计

4.1 方案一：同端口不同路径部署多个 Web 项目

这是很常见的需求，一台服务器只有一个公网 IP 和 80 端口，但想同时部署三个项目：用户端、管理后台、API 服务。我的推荐方案是按照路径去区分：

nginx复制server {
    listen 80;
    server_name example.com;

    # 用户端 H5（Vue 或 React 构建的静态文件）
    location / {
        root /var/www/h5;
        index index.html;
        try_files $uri $uri/ /index.html;
    }

    # 管理后台
    location /admin/ {
        alias /var/www/admin/;
        index index.html;
        try_files $uri $uri/ /admin/index.html;
    }

    # API 服务
    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;
    }
}

这配置里最值得注意的就是前端框架的 history 路由问题。Vue 3、React 这些前端项目，如果不使用 hash 路由（URL 里有 #），而是用 history 模式（URL 是 /user/123 这样的干净路径），刷新页面时浏览器会请求 example.com/user/123，而服务器上并没有这个文件。如果没有 try_files $uri $uri/ /index.html; 这条兜底规则，刷新就是 404。这个坑几乎每个前后端分离项目都会遇到，在热词里也出现了"nignx部署vue3项目"的搜索，说明确实有大量新人卡在这。

有个细节：上面配置中用户端用 root，管理后台用 alias。这两个的区别是：root 会把完整的 URI 拼在路径后面，比如请求 /admin/ 会找 /var/www/admin/；但如果用 root 来配 /admin/，它会找 /var/www/admin/admin/，这就错了。所以子路径映射到不同的目录必须用 alias，这又是一个坑中坑。

4.2 方案二：同 IP 不同端口部署多个 Web 项目

有时候不想在路径上做文章，希望每个服务都有自己独立的访问入口，比如 http://ip:8081 是用户端、http://ip:8082 是管理后台。那么可以直接用多个 server 块，分别监听不同端口：

nginx复制server {
    listen 8081;
    server_name _;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
    }
}

server {
    listen 8082;
    server_name _;

    location / {
        proxy_pass http://127.0.0.1:3001;
        proxy_set_header Host $host;
    }
}

这种方式配置最简单，但真的不太推荐。原因是端口一多，防火墙规则要开一堆，用户记起来也痛苦，而且端口暴露越多，被扫描攻击的面就越大。除非是内网测试环境，生产环境我更推荐用统一 80/443 入口，配合路径或域名区分。

4.3 方案三：同端口不同域名部署多个 Web 项目

这算是我最推荐的生产方案：同一个 80 端口，通过 server_name 来区分不同域名。只要你有一个域名，并能解析多个子域名，比如 h5.example.com 和 admin.example.com，配置就非常清晰：

nginx复制server {
    listen 80;
    server_name h5.example.com;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
    }
}

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

    location / {
        proxy_pass http://127.0.0.1:3001;
        proxy_set_header Host $host;
    }
}

在 Nginx 收到请求后，会根据请求的 Host 头匹配 server_name。如果匹配不到，就用默认 server（一般是配置文件里第一个，或指定 default_server）。这种方案的好处是逻辑独立，各项目互不影响，证书也能按域名单独配，后续扩展也很自然。我在帮客户设计多项目部署时，只要条件允许，基本都是这个套路。

4.4 前后端分离项目：为什么前端能访问，接口却不通

前后端分离项目的 Nginx 配置，最常见的组合是前端静态文件直接由 Nginx 托管，后端接口走反向代理。整体框架可以这样想：location / 处理静态资源，location /api/ 处理动态请求，两者互不干扰。上面 4.1 节的配置就是这个思路。

但这类项目最经典的报错是：前端页面打开正常，调用接口却 404 或者 CORS 报错。排查顺序一般是：

看请求路径。浏览器 F12 看 Network，确认请求的 URL 是不是 /api/...。如果是 /user/list 这种没有前缀的，后端大概率会 404，因为你没有对应的 location 转发规则。
看转发方式。确认 proxy_pass 是原样转发还是带路径替换。用 / 结尾的 proxy_pass 会去掉 /api，后端接口设计时如果没有考虑到这一点，就会 404。
看返回头和 CORS。如果是跨域请求（前端在 h5.example.com，接口在 api.example.com），需要在 Nginx 或后端配置 CORS 头。很多人在后端配了 CORS，但 Nginx 转发时把 OPTIONS 预检请求给拦截了，也会导致失败。

我通常建议，如果后端支持，就把 API 统一挂在一个 /api 前缀下，前端只配一种路径规则，这样心智负担最小。前端请求 /api/xxx，Nginx 原样转发到后端 /api/xxx，最直白，也最好排查。

4.5 静态资源与动态请求的动静分离

除了转发，Nginx 还有一个大杀器叫动静分离。简单理解就是：图片、JS、CSS、字体这类静态资源，由 Nginx 直接读磁盘返回，不经过后端应用；只有真正的数据接口请求才转发给后端。这样静态请求不再占用后端线程，后端只管业务逻辑，压力会小一大截。

静态资源用 location + alias 或者 root 就能搞定：

nginx复制server {
    listen 80;
    server_name example.com;

    # 静态资源直接由 Nginx 服务
    location /static/ {
        alias /data/www/static/;
        expires 7d;           # 给浏览器缓存 7 天
        access_log off;        # 静态资源没必要记日志，省磁盘
    }

    # 图片资源可以单独设置缓存
    location ~* \.(png|jpg|jpeg|gif|ico)$ {
        root /data/www/static;
        expires 30d;
    }

    # 动态请求走反向代理
    location /api/ {
        proxy_pass http://127.0.0.1:8080;
    }
}

expires 指令就是顺手帮静态资源加了 Cache-Control 和 Expires 响应头，浏览器在有效期内直接用本地缓存，不再发起请求。这对首屏速度和带宽成本的控制非常有效。

不过有个点要特别提示：前端项目用打包工具（如 Vite、Webpack）构建后，文件名通常会带上 hash 值（例如 app.8f3k2d.js），这种文件变了名字就变，非常适合长缓存。但 index.html 本身不能长缓存，否则你发版后用户永远看到旧页面。所以 index.html 的缓存时间应该设成 no-cache，或者 expires -1。

5. 常见故障与排查技巧实录

5.1 经典故障 1：502 Bad Gateway

502 是转发场景中出现频率最高的问题，几乎每个用 Nginx 转发的人都见过。它的含义是：Nginx 作为网关，向后的上游服务器发请求，但上游没给出有效响应。常见原因和排查方向有这么几类：

后端服务没启动，或启动后崩了。先 ps aux | grep java（或对应进程）确认进程在不在；再看后端日志有没有报错。
端口配置错了。proxy_pass 写的端口跟后端实际监听端口不一致。用 ss -lntp | grep 8080 看看到底哪个端口在监听。
防火墙挡了。Nginx 跟后端之间有防火墙，从 Nginx 机器上 curl http://127.0.0.1:8080 和 curl http://<后端IP>:8080 分别测试，后者不通大概率就是防火墙或安全组的问题。
后端处理不过来，连接被拒或超时。如果后端并发能力有限，连接队列满，也会 502。这种要看后端日志有没有大量连接超时，往往需要同步调后端的线程池和 Nginx 的 proxy_connect_timeout。

顺便说一句：如果 Nginx 返回的 502 来得特别快，通常是连接被拒；如果等了很久才 502，说明是连接超时。时间快慢本身也是重要的排查线索。

5.2 经典故障 2：504 Gateway Timeout

504 跟 502 的区别在于：后端确实响应了，但太慢了，Nginx 等不及就断了。排查方向很明确：

确认是不是某个接口本身就慢。比如报表导出、批量处理，先看后端接口实际耗时。
确认 Nginx 的超时参数是不是太小。重点看 proxy_read_timeout 和 proxy_send_timeout。
如果后端是长事务操作，除了调大超时，也可以评估是否需要改造成异步任务 + 轮询查询结果的模式，避免长时间占用 HTTP 连接。

我经常跟后端同学说：504 不一定是 Nginx 的问题，别一上来就甩给运维改超时。先量一下接口本身耗时，如果接口偶发响应 70 秒，你调大超时只能缓解表象，真正要做的是优化接口性能。

5.3 经典故障 3：代理后登录失效、Session 不同步

后端登录状态依赖 Cookie 和 Session 的时候，Nginx 转发配置不对就会导致登录后一刷新又变成未登录，或者 A 机器登录了、B 机器没登录。这类问题的根源有两类：

Nginx 没有透传 Cookie。proxy_set_header Cookie $http_cookie; 这条指令会显式透传客户端请求里的 Cookie 头。但默认情况下 Nginx 本身就会透传 Cookie，所以如果你的配置里手动覆盖了请求头，要注意别把 Cookie 丢了。
负载均衡策略导致 Session 漂移。如果配置了 upstream 且用了默认轮询，同一个用户两次请求可能打到不同的后端机器上，而每台机器本地 Session 是独立的，于是登录态就丢了。解决方案有两个：一是后端用 Redis 集中存储 Session，告别本地 Session；二是 Nginx 用 ip_hash 保证同一个 IP 固定打到同一台后端。

生产项目我还是建议把 Session 集中到 Redis/数据库中，不然集群扩容、缩容、某台后端宕机，都会强制踢用户下线，体验很糟糕。ip_hash 只是权宜之计，不是长久之策。

5.4 经典故障 4：WebSocket 转发失败

HTTP 转发是 Nginx 的看家本领，WebSocket 转发也需要配，但很多人按普通转发配完发现连不上，调试了半天才发现少了关键的升级头。配置其实就三行核心：

nginx复制location /ws/ {
    proxy_pass http://127.0.0.1:8080;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_read_timeout 3600s;
    proxy_send_timeout 3600s;
}

WebSocket 连接建立前，客户端会发一个带 Upgrade: websocket 的 HTTP 请求，服务端确认后协议才升级为 WebSocket。Nginx 默认转发时会丢掉 Upgrade 头，所以必须用 proxy_set_header Upgrade $http_upgrade; 显式保留。Connection "upgrade" 同理，用来告诉上游这段连接要升级协议。

另外一点，WebSocket 是长连接，默认的 60 秒超时会导致空闲连接被 Nginx 断开，客户端莫名掉线。所以 WebSocket 转发一般要把 proxy_read_timeout 调大，甚至可以到几小时。具体看你的业务，心跳机制做得好的话，60 秒内肯定有数据包，也可以不用调太长。

5.5 排查利器：用好日志、curl 与 tcpdump

遇到转发问题，我推荐的排查顺序是"看日志 → 手动复现 → 抓包"。而不是一上来就怀疑配置。

第一步，看 Nginx 的 error.log。默认路径在 /var/log/nginx/error.log，里面会有上游连接失败的详细原因，比如 connect() failed (111: Connection refused) 或 upstream timed out。这一条信息基本就能定位 80% 的问题。

第二步，看 access.log 的响应码和耗时。access.log 的默认格式里最后几项是响应状态码和请求耗时。如果你发现某个接口的耗时始终很高，再结合后端日志确认瓶颈。

第三步，用 curl 模拟请求。这是我最常用的手段，可以精确控制路径和头信息，快速验证 Nginx 的转发行为：

bash复制# 直接请求 Nginx，观察响应
curl -I http://example.com/api/user/list

# 带上 Host 头测试不同域名
curl -H "Host: admin.example.com" http://127.0.0.1/api/user/list

# 带上请求头测 WebSocket 升级
curl -i -N -H "Connection: Upgrade" -H "Upgrade: websocket" -H "Host: example.com" http://127.0.0.1/ws/

第四步，如果怀疑是协议层问题或者需要确认请求是否真的到了后端，在后端服务器上用 tcpdump 抓包：

bash复制tcpdump -i eth0 port 8080 -nn -A | grep "GET /"

不过 tcpdump 不是每台机器都有，也没有权限装的话，更简单的方案是临时在后端服务里打一行访问日志，看请求到底来没来、路径是什么、带了什么 Header。很多时候，真相就藏在这几行日志里。

5.6 配置变更安全操作：先检查、再重载、留回退

Nginx 不同于其他服务，它的重载（reload）可以做到平滑：旧 worker 进程继续处理已有连接，新 worker 用新配置。但前提是你改了配置以后不要直接强制重启，而是按下面这套流程走：

bash复制# 1. 检查语法
nginx -t

# 2. 语法通过的提示是 syntax is ok / test is successful
# 3. 平滑重载配置
nginx -s reload

# 4. 如果 reload 后出现问题，快速回退
cp /etc/nginx/conf.d/myapp.conf.bak /etc/nginx/conf.d/myapp.conf
nginx -s reload

这里要重点说一句：nginx -t 只检查语法，不检查逻辑。它不知道你的 proxy_pass 后端是否可达，也不知道你的 location 规则有没有覆盖到想要的路径。所以即使 nginx -t 通过了，也要在 reload 后用 curl 实际验证一下。

我见过太多次这种场景：半夜上线，改了配置，nginx -t 通过，reload，结果第二天业务方报接口不通。一查，路径少了个斜杠，整个转发规则没生效。所以，无论多简单的配置修改，reload 后务必用真实请求验证一遍。这里说的"验证"，不是打开浏览器看个首页就行，而是要把关键接口、静态资源、登录流程各走一遍。

5.7 故障排查速查表

这些年带团队排查 Nginx 转发问题，我积累了一个"从现象到根因"的速查表。写在这里，方便大家直接收藏使用：

现象	可能原因	排查命令/位置	解决思路
502 Bad Gateway	后端服务未启动、端口不对、防火墙拦截	`ps aux \| grep 进程`、`ss -lntp`、`curl http://127.0.0.1:8080`	启动后端、修正 proxy_pass 端口、放通防火墙
504 Gateway Timeout	后端响应慢、Nginx 超时参数过小	后端日志接口耗时、`error.log` 定位	调大 `proxy_read_timeout`，优化后端性能
404 Not Found	路径重写规则错误、前端 history 路由无兜底	`curl` 直接请求后端口径对比	调整 `proxy_pass` 斜杠写法、加 `try_files`
403 Forbidden	静态资源目录权限不足、IP 白名单拦截	检查 Nginx worker 用户对目录的读权限	`chmod` 调整权限，检查 allow/deny 规则
登录态丢失	Cookie 透传问题、Session 漂移	浏览器 DevTools 看 Cookie、后端 Session 存储方式	确认 `proxy_set_header` 不覆盖 Cookie、Session 集中存储
WebSocket 连不上	缺少 Upgrade 头	`curl -i -N` 带 Upgrade 头测试	加 `proxy_set_header Upgrade` 和 `Connection "upgrade"`
客户端拿不到真实 IP	未配置 X-Real-IP / X-Forwarded-For	后端日志打印的头信息	配 `proxy_set_header X-Real-IP $remote_addr`

这张表不可能覆盖所有场景，但最常见的 90% 转发问题基本都在这几条里面了。排查的时候先对应现象，再按表格里的方法逐个验证，通常很快就能定位。

6. 一些额外的实战心得

前面把配置和排障讲得差不多了，最后再分享几条我在具体项目中沉淀下来的经验，偏向方法论，但每一条都是真金白银换来的。

第一条，给每个项目的转发配置写注释。 Nginx 配置文件本身不支持太复杂的逻辑，但注释是完全可以写清楚的。我在每个 server 块开头都会写一段注释，说明这个虚拟主机是哪个项目、后端地址是谁、谁负责维护、最近改了什么。不然半年后你自己回来看这堆配置都会发懵，更别说接手的同事了。

第二条，把通用配置抽出来复用。 多个 server 块里重复的 proxy_set_header、超时配置等，可以放到 http 块里做成默认配置。比如全局默认加上：

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_connect_timeout 5s;
proxy_read_timeout 60s;

这样后面每个 location 里的 proxy_pass 都能自动带上这些头，配置简洁不少。除非某个接口需要特殊覆盖，否则不用每个 server 都重复写一堆。

第三条，先小范围验证，再全量发布。 如果是线上环境，改完配置不要直接对全量用户生效。可以用一个测试子域名或者一个特殊 upstream 节点先验证，确认没问题再 reload 全量。虽然 Nginx reload 本身平滑，但配置逻辑错误是 reload 救不了的，谨慎一点永远没错。

第四条，监控不能省。 Nginx 的 stub_status 模块可以暴露基本的连接数、请求数指标。我自己常用的是通过 Prometheus 的 nginx-prometheus-exporter 采集这些指标做监控，遇到连接数暴涨、5xx 比例升高，能第一时间告警。一个没有监控的 Nginx 转发层，就像蒙着眼睛开车，出事之前毫无预兆。

第五条，哪一天你觉得 Nginx 转发的规则太复杂了，也许不是配置该调了，而是架构该重新想了。 当一个配置文件里塞了几百行 if 判断、rewrite 规则堆积如山的时候，就该考虑引入 API 网关（比如 Kong、APISIX）或者直接用云上负载均衡产品来分担了。Nginx 是优秀的底层引擎，但把所有业务规则都堆在它身上，最后维护成本会高到你想哭。

这些年我用 Nginx 做过不少事情：多项目部署、负载均衡、灰度发布、缓存加速、限流熔断……每次遇到问题，翻来覆去排查，最后发现大部分坑都集中在 proxy_pass 的路径拼接、location 的优先级、请求头透传这三件小事上。这篇内容把这三个核心点掰开揉碎讲清楚，再加上一套系统的排障方法论，剩下的就是在实践中多踩几个坑、多总结几条笔记了。配置这种东西，没有捷径，多练，多看 error.log，慢慢就形成肌肉记忆了。

Nginx请求转发实战：从location匹配到故障排查全解析