配置 Nginx 的时候proxy_pass 应该是我写得最多的指令。如果你负责后端服务或者独立部署过前后端分离项目大概率也跟它打过照面把一个路径下的请求转给另一台服务Nginx 在中间做搬运工。这篇内容围绕 proxy_pass 的常见用法、两种最容易出问题的写法、以及踩坑后沉淀下来的排障经验展开适合刚接触反向代理配置的开发者也适合已经配过 proxy_pass、但被各种斜杠和路径替换问题绕晕的人。说穿了proxy_pass 的语法非常简单但背后那套路径替换规则才是大多数人真正掉进去的坑。1. 先搞清楚 proxy_pass 到底在做什么1.1 正向代理和反向代理先从概念说起。代理这个词在计算机里早就被用滥了生活中最常见的类比是“中介”。我租房时不直接找房东而是通过中介联系中介知道房东是谁但房东不一定知道我。正向代理就是客户端这一侧的“中介”客户端知道要访问的目标但通过代理去访问目标服务器只知道代理的 IP不知道真实客户端是谁。反向代理正好反过来它站在服务器这一侧。客户端访问的是反向代理反向代理再去找后面的真实服务器把响应带回来。客户端感知不到后端的存在它只认为自己在跟代理对话。Nginx 的 proxy_pass 就是配置这个“反向代理行为”的核心指令。它告诉 Nginx当某个请求进入并被location匹配到时把这个请求转发到 proxy_pass 指定的地址上拿到后端的响应之后再还给发起请求的客户端。整个过程中客户端既不需要知道后端真实 IP也不需要关心后端端口它只认 Nginx 对外暴露的地址。1.2 proxy_pass 在配置文件中的位置proxy_pass 可以出现在 http、server、location 这几个上下文中最常见的用法是放在 location 块里。比如server { listen 80; server_name example.com; location /api/ { proxy_pass http://127.0.0.1:8080; } }这段配置的含义很直白所有以/api/开头的请求都会被转发到本机 8080 端口。上面的listen和server_name负责决定“哪个请求进入这个 server”location负责决定“进入之后交给谁处理”proxy_pass才是真正的动作。整个逻辑像一张路由表URL 进来匹配 location按 proxy_pass 的规则发往后端。为什么要用 Nginx 做反向代理我在实际项目里总结下来无非几个原因。第一后端服务不想直接暴露。比如内网有一堆服务端口各不相同统一从 80/443 入口进来由 Nginx 按路径分发外部只需要知道一个域名。第二前后端分离部署很常见。前端静态文件放在 Nginx 上接口请求统一转发给后端应用同源部署避免跨域问题。第三需要做负载均衡或者灰度发布。多台后端实例Nginx 按权重分发或者一部分流量打到新版本实例上。第四SSL 证书、日志、限流、缓存这些通用能力统一收口在 Nginx 这一层后端应用可以写得更纯粹。1.3 一个最小的转发流程配完上面那段配置之后客户端请求http://example.com/api/user会发生什么Nginx 接收请求发现/api/匹配 location于是根据 proxy_pass 的写法来决定转发的最终 URL。最基本的情况proxy_pass 后面只有一个服务器的地址没有路径那转发到后端的 URI 会和原始请求完全一致也就是后端收到的请求是GET /api/user。后端返回响应Nginx 原样回传给客户端。这个流程看着简单但真正决定“后端收到什么 URL”的是 proxy_pass 写不写路径、写不写斜杠。这是 proxy_pass 最核心、也最容易被忽略的细节下一节专门展开说。2. 最容易翻车的细节路径写不写斜杠2.1 不带 URI 的写法原样转发先看第一种也是我强烈推荐的默认写法location /api/ { proxy_pass http://10.0.0.10:8080; }proxy_pass 的地址只有协议、主机、端口没有任何路径也没有结尾斜杠。这种写法下转发规则是“保留原始请求 URI”。客户端请求/api/user?nameabc后端收到的就是/api/user?nameabc路径和查询参数都原样保留。这种写法适合什么场景后端接口本身的路由前缀和 Nginx 暴露的前缀一致。比如后端服务里就是/api/user那 Nginx 完全不需要动路径直接把这个请求递给后端即可。少做一件事就少错一件事如果业务允许我一般优先用这种写法。2.2 带 URI 的写法前缀替换再看第二种location /api/ { proxy_pass http://10.0.0.10:8080/; }区别只在最后多了一个/。但语义完全不同proxy_pass 带上的/属于 URI 的一部分。此时 Nginx 不会原样保留请求 URI而是执行替换请求 URI 中匹配 location 的部分被 proxy_pass 中的 URI 替换掉。客户端请求/api/userlocation 匹配到/api/这段前缀被替换成/所以后端最终接收到的 URL 是/user。也就是说“把 API 前缀剥掉”这种需求正是靠这个斜杠实现的。再举一个更明显的例子。如果配置写成location /api/ { proxy_pass http://10.0.0.10:8080/v2/; }请求/api/user会变成/v2/user。这里/api/被整体替换成/v2/前半段变了后半段保留。同理也可以替换成/v2不带尾斜杠那请求/api/user会变成/v2user这种诡异结果正是很多人被绕晕的根源。2.3 典型例子逐一对比我把常见的组合列成一张表方便对照location 配置proxy_pass 配置请求原始 URI后端最终收到的 URIlocation /api/http://backend/api/user/api/userlocation /api/http://backend//api/user/userlocation /api/http://backend/v2//api/user/v2/userlocation /apihttp://backend//api/user/userlocation /apihttp://backend/api/user/api/userlocation /api/http://backend/v2/api/user/v2user最后一行值得再强调一遍。proxy_pass http://backend/v2;的 URI 是/v2它会将匹配到的/api/直接替换成/v2如果请求恰好是/api/user拼出来的结果是/v2user。你要是本来想要/v2/user这里就踩坑了。类似这种“少一个斜杠”的问题是代理配置里最常见的一类低级事故。判断方法其实很简单把请求 URI 中被 location 匹配到的那段抹掉再把 proxy_pass 的 URI 填回去剩下的就是后端收到的 URL。我每次写完配置心里都先过一遍这个推演再配合 curl 验证路径问题基本就堵死了。强烈建议你也在本地搭建一个最简单的 echo 后端就是那种不管收到什么请求都把 URL 原样返回的服务用它来验证各种 location 加 proxy_pass 的组合比看文档记规则高效十倍。2.4 查询参数会怎样还有一个容易被忽略的点查询参数。不带 URI 的写法下查询参数当然原样保留。带 URI 的写法下如果 proxy_pass 的 URI 中没有显式写查询参数那么原始请求的查询参数仍然会被追加到转发地址后面。比如配置是proxy_pass http://backend/;请求/api/user?page2后端收到的是/user?page2。但如果你在 proxy_pass 中手动加了查询参数比如proxy_pass http://backend/?page1;那原始请求的查询参数会被丢弃后端收到的是/user?page1。需要透传参数的时候千万不要在 proxy_pass 的 URI 里乱加参数。我见过有人为了“固定某个参数”把所有业务参数都搞丢了排查了很久才发现是这里的原因。实际业务里透传查询参数的场景远多于固定参数所以这条规则值得记牢。3. 真实场景里的 proxy_pass 配置3.1 场景一前后端分离的同源部署现在很多项目前端是打包后的静态文件后端是一套 API 服务。我的习惯是前端放 Nginx 根目录后端接口通过/api/路径转发。配置大概长这样server { listen 80; server_name app.example.com; root /data/www/frontend; index index.html; location /api/ { proxy_pass http://127.0.0.1:8080; } location / { try_files $uri $uri/ /index.html; } }这个配置有个重要细节location /api/的 proxy_pass 后面没有斜杠因为后端接口路径本身也带/api/前缀原样转发就行。而前端页面走 SPA 的路由回退try_files负责把非文件请求引到 index.html。页面资源和接口在同源下浏览器就不会出现跨域报错。很多前端调试时遇到的 CORS 问题用 Nginx 做反向代理往往比在后端疯狂加跨域头更干净。我甚至在本地开发环境也这么配过前端起在 3000 端口后端起在 8080Nginx 监听 80把/api/转发到 8080前端开发服务器就不用单独配置任何代理插件。3.2 场景二API 前缀剥离与路径重写如果后端服务的前缀跟对外暴露的不一样就要用带 URI 的写法。最常见的是对外用/api/后端实际没有这个前缀location /api/ { proxy_pass http://127.0.0.1:8080/; }这样/api/order/123到了后端变成/order/123。我参与维护的一个内部系统就是这么干的前端统一走/api/方便网关层面做鉴权和限流后端服务就不用每个接口都写一遍公共前缀。如果需求更复杂可以配合 rewrite 实现更灵活的路径变化。比如把/old/xxx重写成/new/xxx再转发location /old/ { rewrite ^/old/(.*)$ /new/$1 break; proxy_pass http://127.0.0.1:8080; }rewrite 里的 break 表示重写完成后立即终止后续 rewrite 模块的处理然后用重写后的 URI 继续执行代理转发。这种组合适合反向代理时调整路径结构的场景但要注意 rewrite 和 proxy_pass 叠加后逻辑会变复杂配置前先在草稿纸上推演一遍路径变化别直接上生产去改。尤其要防止 rewrite 和 proxy_pass 的替换规则同时生效导致路径被改了又改最终面目全非。3.3 场景三多后端负载均衡单台后端扛不住流量时proxy_pass 一般配合 upstream 使用。upstream 是 Nginx 中定义一组后端服务器的指令proxy_pass 直接指向上游组名upstream backend_pool { server 10.0.0.11:8080 weight3; server 10.0.0.12:8080 weight1; server 10.0.0.13:8080 max_fails3 fail_timeout30s backup; keepalive 32; } server { listen 80; location /api/ { proxy_pass http://backend_pool; } }weight 表示权重weight3 的机器分到更多流量。max_fails 和 fail_timeout 表示在指定时间内最多失败几次就把该节点标记为不可用backup 表示备用节点正常节点全部不可用时才接管。keepalive 保存空闲连接数减少频繁建连带来的开销。要让 keepalive 生效还需要两行配置配合一是proxy_http_version设置为 1.1二是清掉默认的 Connection 头否则默认走 HTTP/1.0 的话连接复用不了location /api/ { proxy_http_version 1.1; proxy_set_header Connection ; proxy_pass http://backend_pool; }负载均衡场景里还有一点值得提如果你在 upstream 中配置了least_conn或ip_hash等策略proxy_pass 的写法和普通 upstream 完全一致区别只在于节点的选择算法。比如需要保持用户会话固定打到同一台后端时可以用ip_hash但要注意它会带来流量分布不均的问题建议结合业务场景权衡。3.4 场景四WebSocket 与长连接转发现在不少应用用了 WebSocket比如消息推送、协同编辑。Nginx 转 WebSocket 有一个非常经典的配置模板location /ws/ { proxy_pass http://ws_backend; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; proxy_read_timeout 3600s; proxy_send_timeout 3600s; }核心是两行把 Upgrade 请求头透传给后端并把 Connection 强制改成 upgrade。如果不配置这两行Nginx 默认会吞掉 Upgrade 头浏览器和后端的握手就不成立常见表现是 WebSocket 连接建立后立刻断开或者连接里根本没有升级请求。proxy_read_timeout和proxy_send_timeout我都习惯调大因为 WebSocket 是长连接默认 60 秒超时会导致空闲连接被杀客户端只能不断重连体验非常差。具体超时时间可以根据业务心跳间隔来定一般比心跳间隔大一些就可以。曾经有个推送服务客户端每隔 30 秒发一次心跳我刚开始只配了 60 秒超时结果偶尔网络抖动一次连接就被 Nginx 断掉了调整到 120 秒之后基本没再出现过类似问题。4. 必配的头和关键参数4.1 Host 与 X-Forwarded-* 系列只写一行 proxy_pass 能把请求转发出去但后端拿到的请求信息未必正确。最典型的是 Host 头。默认情况下Nginx 转发请求时 Host 会沿用原始请求里的值。如果后端服务是用域名区分虚拟主机的或者根据 Host 生成回调地址那 Host 就必须正确传递。需要自定义时用 proxy_set_header 指令location /api/ { 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_pass http://127.0.0.1:8080; }$host 通常取原始请求的域名适合大多数场景。X-Real-IP 直接记录客户端真实 IP。X-Forwarded-For 会在原有链路上追加本次客户端地址多级代理时能保留全链路信息。X-Forwarded-Proto 告诉后端原始请求是 http 还是 https涉及到后端生成重定向或者判断协议时很关键。有两点要特别注意。第一如果反代到公网后端谨慎伪造 Host因为有的域名服务商会校验来源随便换掉 Host 会被拒绝。第二这些头虽然叫“转发头”但客户端其实自己也能伪造如果后端拿它们做信任判断一定要记住只信来自可信代理的值不能盲目采信客户端传来的任何头部。4.2 超时和重试参数proxy_pass 默认的超时参数经常不够用。我见过一个批量导出接口单个请求要跑几分钟结果 Nginx 在 60 秒就把连接断了后端日志里明明是正常处理客户端却收到 504。排查时第一反应就是看超时配置。常用的三个超时参数proxy_connect_timeout 5s; proxy_send_timeout 60s; proxy_read_timeout 120s;connect_timeout 是建立与上游连接的超时一般不要设太大客户端连不上就快速失败。send_timeout 是向后端发送请求的超时read_timeout 则是等待后端响应的时间。长耗时接口需要调大 read_timeout同时注意后端是同步处理还是异步任务有些接口可以先返回任务 ID再轮询结果这样代理层完全不用调大超时。还有重试机制。Nginx 默认会对 error 和 timeout 这两个情况重新尝试下一个上游节点可以通过 proxy_next_upstream 控制。比如我只希望在连接错误和 5xx 时重试不希望在业务 4xx 时重试proxy_next_upstream error timeout http_502 http_503 http_504; proxy_next_upstream_tries 2;这里要特别提醒如果请求已经发到后端后端也处理了但响应在回传过程中断了此时重试可能会让后端处理两次。不是所有场景都适合无脑重试涉及下单、扣款这类接口重试策略要非常谨慎必要时配合幂等设计才能保证安全。4.3 缓冲区设置Nginx 默认会把后端响应缓冲到内存和临时文件里再发给客户端。好处是后端可以尽快释放连接坏处是如果响应很大会占用磁盘空间。需要关掉缓冲、尽快流式转发时可以用proxy_buffering off;需要精细控制时看这几个参数proxy_buffer_size 4k; proxy_buffers 8 4k; proxy_busy_buffers_size 8k;buffer_size 是每个连接用于读取响应头部的缓冲区默认通常是一个内存页大小响应头特别大时需要调大。proxy_buffers 指定用于缓冲响应体的缓冲区的数量和大小。busy_buffers_size 控制正在发送给客户端时不能被释放的缓冲区上限。多数内部系统保持默认就够用但遇到两种场景可以关注一是 Server-Sent Events 这类流式场景必须关闭缓冲让数据边到边转二是大文件下载如果不想把整个文件读进缓冲再吐给客户端也需要调整缓冲策略。实际调整时我一般用 curl 观察首字节时间结合后端和 Nginx 的 CPU 与内存占用综合判断不要盲目调大缓冲区。4.4 后端错误时的统一处理后端偶尔挂掉Nginx 默认会直接把 502/504 返回给客户端页面很丑用户也不知道发生了什么。通过 proxy_intercept_errors 可以拦截后端返回的错误状态码再交给 error_page 统一处理proxy_intercept_errors on; error_page 502 503 504 /50x.html; location /50x.html { root /data/www/error; internal; }proxy_intercept_errors on 让 Nginx 拦截上游响应中大于等于 300 的状态码然后 error_page 将指定的错误码映射到本地页面。internal 标记这个 location 只能内部跳转访问外部用户不能直接请求避免错误页的真实路径被爆破。这个配置在 Nginx 做统一入口时特别实用尤其是承载多个业务线时错误页风格统一、包含联系方式、带搜索建议都比裸的 502 页面体验好。还要注意error_page 本身并不改变返回状态码如果想返回自定义状态码需要加 code的写法比如error_page 502 200 /50x.html;这个根据业务需求决定多数场景下保留原始错误码更合适。5. 变量、正则与使用限制5.1 正则 location 中的 proxy_pass上面讨论的都是普通前缀匹配 location。如果 location 使用正则proxy_pass 的写法就多了一条限制不能带 URI 部分否则 Nginx 启动时会直接报错并拒绝加载配置。正则 location 通常配合捕获组来动态拼路径例如location ~ ^/api/(.*)$ { proxy_pass http://127.0.0.1:8080/$1; }这里$1是正则捕获到的(.*)请求/api/user/123会转发到http://127.0.0.1:8080/user/123。因为 proxy_pass 用的是“变量拼接的 URI”所以即使它看起来带了一段路径也是允许的。不少初学者会把这个规则搞混记住一个判断标准正则 location 里如果想让 Nginx 正常启动proxy_pass 要么不写 URI要么写带变量的 URI。5.2 使用变量时的 resolverproxy_pass 使用变量时如果变量值里包含域名Nginx 需要在运行时解析这个域名。它和配置阶段静态解析域名不一样运行时解析要依赖 resolver 指令否则会报“no resolver defined to resolve”的错误。例如location /proxy/ { resolver 8.8.8.8; proxy_pass http://$backend_host:8080$request_uri; }这里用公共 DNS 做示意实际使用时应按部署环境配置对应的 DNS 地址。加上 resolver 之后Nginx 才能在请求处理过程中把 $backend_host 解析成实际 IP。带变量的 proxy_pass 灵活性更高但也意味着 Nginx 无法在启动时预检目标地址的合法性出问题时排查链路也会多一环。能用静态 upstream 解决的我一般不会主动引入变量可读性和可维护性都比花哨的写法重要。5.3 if 块中使用 proxy_pass 的坑早期版本的 Nginx 在 if 块中使用 proxy_pass 限制很多新版本宽松了一些但我仍然不建议在 if 里写代理转发逻辑。原因在于 if 指令在 Nginx 里实现得比较特殊容易出现与直觉不符的分支行为尤其在没有 else 语义的情况下逻辑很容易变形。如果确实需要根据条件转发到不同后端更推荐的做法是根据请求特征拆分成多个 location再用 rewrite 或 try_files 做调度。比如按路径前缀拆、按请求参数拆都比一长串 if 嵌套清晰得多。维护过复杂 Nginx 配置的人应该能理解配置文件一旦逻辑复杂调试成本会飞快上涨所以结构上的克制比炫技重要。你会发现真正稳定跑了几年的 Nginx 配置往往都长得很朴素。6. 常见问题排查与速查6.1 一张速查表下面这些是我在实战中遇到频率最高的几个问题直接列成表格方便对照现象常见原因解决方向404 或路径对不上proxy_pass 带 URI 导致前缀被替换对照第 2 节替换规则重新推演确认是否该保留 URI504 Gateway Timeout后端处理太慢超过 read_timeout调大 proxy_read_timeout或改异步处理502 Bad Gateway后端没启动、连接被拒、Nginx 连不上检查后端端口、服务状态和 connect_timeout页面刷新正常但接口 404前端路由或 API 前缀配置与后端不一致用 curl 按真实请求路径访问代理和后端对比登录后反复跳回登录页后端生成回调地址时用错协议或 Host检查 X-Forwarded-Proto 与 Host 配置WebSocket 秒断缺少 Upgrade 头透传补上 proxy_set_header Upgrade 与 Connection看不到真实后端信息access log 没有记录上游地址在 log_format 中加入 $upstream_addr6.2 我常用的三个调试手段排查 proxy_pass 问题时我不太喜欢直接改配置碰运气更习惯先用工具看清楚请求到底变成了什么样子。第一招用 curl 直接请求代理地址并观察响应头。加-v可以看到完整的请求响应头确认请求经过代理后发生了什么。如果怀疑路由不对可以起一个临时 echo 后端让它打印收到的完整 URL用 Nginx 转发过去就能一目了然。第二招在 access log 里加入上游信息。log_format 可以配置成下面这样log_format proxy $remote_addr [$time_local] $request - $upstream_addr status$status upstream_status$upstream_status request_time$request_time;配置到 server 中打开日志就能看到每个请求实际转发到了哪台后端以及后端返回的状态码。多节点负载均衡场景里这个信息特别有用。我见过很多团队根本没有记录 $upstream_addr一旦多节点出问题根本不知道请求打到了哪台机器。第三招如果链路确实诡异直接抓包确认。对特定端口抓包看 SYN、ACK 和数据包是否正常可以快速判断问题是出在 Nginx 到后端的网络还是后端处理本身。不过生产环境抓包要先确认权限范围避免影响正常业务。6.3 一个典型的排障实录之前在一个模拟项目里同事反馈某个接口偶尔返回 502重启后端之后又恢复正常过一会儿又坏。第一反应是后端问题但查看后端日志发现请求根本没有到达。第二反应是 Nginx 配置问题但配置看起来只有简单的 proxy_pass没有可疑点。我打开 access log发现$upstream_addr指向两台后端其中一台失败次数明显偏高。再查代码发现新上线的节点里有一个依赖本地缓存的服务缓存初始化阶段会在启动后几秒内拒绝部分请求而 Nginx 的重试策略只在 error 和 timeout 时才切换节点遇到连接被重置时来不及切走。最后处理方式是在 upstream 中把该节点的 fail_timeout 调短并加上健康检查逻辑让 Nginx 尽快把这个节点摘掉。这个排查过程花了一个多小时问题本身并不复杂但“日志里能看见真实上游”这个习惯帮了大忙。如果 access log 里没有 $upstream_addr我可能还要多绕很多弯路。那次之后我把所有新接手的代理配置都先加好这一列日志算是给自己留一条后路。做 Nginx 配置这些年我跟 proxy_pass 打过太多照面。回头看绝大多数事故都不是高深原理造成的而是对“路径替换规则”这种基础细节掌握不牢加上配置上线前没有用 curl 验证。如果你刚接触 proxy_pass我建议把第 2 节那张表贴在手边每次写配置之前先推演一遍路径变化如果你的生产环境已经跑了很久也不妨打开 access log 里的 $upstream_addr花十分钟看看真实的转发链路说不定能发现很多平时没注意到的隐患。