NOTE · 2026.10.27

Nginx 反向代理的八个易错点

反向代理看起来只是 proxy_pass 一行,实际排错时,问题常常藏在请求头、超时和路径重写里。下面是我在维护服务时最常遇到的几个点。

Host 与真实 IP

上游应用如果依赖域名生成链接,要显式传递 Host。位于 CDN 后面时,还要确认 Nginx 是否信任 CDN 的转发头,否则日志里全是 CDN 节点地址。

WebSocket 和长连接

升级请求需要 Upgrade 与 Connection 头。对于流式接口,proxy_buffering off 和足够长的读超时通常比盲目调大所有超时更有效。

路径结尾的斜杠

proxy_pass http://backend/ 和 proxy_pass http://backend 在带 URI 的 location 中行为不同。上线前用 curl -v 对照实际请求路径,比事后猜日志快得多。

先做最小配置

每加一个重写规则或缓存策略,都先确认基础代理正常。配置越复杂,越需要分阶段验证。能用一条 location 解决的问题,不要堆三层变量和 map。