Nginx 反向代理实现 API 中转的实战要点

在微服务和前后端分离架构普及的今天，Nginx 作为反向代理来实现 API 中转几乎成了标配。本文结合实际项目经验，总结几个最容易踩坑的实战要点。

一、基础配置：location 与 proxy_pass 的斜杠陷阱

最常见的配置如下：location /api/ { proxy_pass http://127.0.0.1:8080/; }

注意 proxy_pass 末尾的斜杠：带斜杠时，/api/user 会被转发为 /user；不带斜杠时则保留完整路径 /api/user。这个细节决定了后端收到的路径，配置前务必用 curl 验证实际转发路径。

二、透传真实客户端信息

反向代理后，后端拿到的 remote_addr 会变成 Nginx 本机 IP。务必加上：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; 否则日志、限流、风控都会拿到错误的 IP。

三、超时与缓冲要按接口类型调

默认的 proxy_read_timeout 是 60 秒。对于普通查询接口够用，但文件上传、报表导出这类长耗时接口需要单独调大，例如 proxy_read_timeout 300s。流式接口（如 SSE）建议关闭 proxy_buffering 避免延迟。

四、WebSocket 中转别忘了升级头

如果 API 中包含 WebSocket，需要显式透传升级头，否则握手会失败：proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade";

五、CORS 统一在网关层处理

多个后端服务各自处理跨域容易遗漏，建议在 Nginx 层统一处理 OPTIONS 预检请求，减少后端重复代码，也便于统一收紧策略。

六、上线前的检查清单

1. 用 curl 确认转发路径、请求头、状态码符合预期；2. 压测验证超时、缓冲配置在高并发下不丢请求；3. 确认 access_log 记录了 X-Forwarded-For，便于事后排查；4. 配置变更后执行 nginx -t 再 reload，避免语法错误导致服务中断。

把这几个要点落实，Nginx 反向代理这层基本就稳了。