location末尾斜杠决定proxy_pass路径拼接逻辑：带/则剥离前缀，不带则全量追加；需正确配置proxy_set_header传递真实IP和Host；CORS需动态反射可信Origin并处理OPTIONS预检；超时和缓冲区须按业务调优。
location 匹配路径时末尾斜杠影响代理行为
nginx 的 location 块中是否带末尾 /，直接决定 proxy_pass 后的路径拼接逻辑。这是接口转发出错最常见原因。
- 写成
location /api/ { proxy_pass http://backend/; }：请求/api/users会被转发为http://backend/users（/api/被剥离） - 写成
location /api { proxy_pass http://backend; }（无结尾/）：请求/api/users会被转发为http://backend/api/users（原路径全量追加） - 若后端服务根路径就是
/api，却错误配置了proxy_pass http://backend/，会导致 404 —— 因为实际发过去的是/users，后端收不到/api/users
proxy_set_header 必须重写 Host 和 X-Real-IP
不显式设置请求头，后端可能拿不到真实客户端 IP 或误判 Host，尤其当后端做域名白名单、限流或生成绝对 URL 时会出问题。
location /api/ {
proxy_pass http://127.0.0.1:8000/;
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;
}-
Host $host保留原始 Host，避免后端因 Host 变成127.0.0.1:8000而拒绝请求 -
X-Real-IP是最简可用的真实 IP 字段；X-Forwarded-For可能被伪造，生产环境建议配合real_ip_header和set_real_ip_from使用 - 漏掉
X-Forwarded-Proto时，后端用request.scheme拿到的可能是http，即使 nginx 前面是 HTTPS
跨域问题不能只靠 add_header Access-Control-Allow-Origin *
前端调用接口报 CORS 错误，很多人第一反应是加通配符响应头，但这在携带 Cookie 或自定义 Header 时会直接失效。
-
add_header Access-Control-Allow-Origin "*"与withCredentials: true冲突，浏览器会拒绝响应 - 正确做法是动态反射 Origin（需确保可信来源）：
if ($http_origin ~* "^https?://(localhost:3000|myapp\.example\.com)$") { add_header Access-Control-Allow-Origin $http_origin; add_header Access-Control-Allow-Credentials "true"; } - 别忘了预检请求（OPTIONS）要返回成功：
add_header Access-Control-Allow-Methods "GET, POST, OPTIONS";，并用if ($request_method = 'OPTIONS') { return 204; }快速响应
超时和缓冲区配置不当导致接口卡死或截断
后端 API 响应慢、返回大文件或流式数据时，nginx 默认值会中断连接或丢内容。
-
proxy_connect_timeout 60s;：建立 TCP 连接到后端的最长等待时间，后端启动慢或网络抖动时易超时 -
proxy_read_timeout 300s;：两次读操作之间的最大间隔，长轮询、SSE、导出大 Excel 必须调大 -
proxy_buffering off;：对流式响应（如text/event-stream）必须关闭缓冲，否则数据攒满 buffer 才吐给客户端 -
proxy_max_temp_file_size 0;：禁用磁盘临时文件，避免大响应写磁盘失败
真正踩过坑的人知道：转发规则写对只是起点，Header 控制、CORS 策略、超时阈值这三块没对齐，接口就随时可能在某个边缘场景下静默失败。
