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 策略、超时阈值这三块没对齐，接口就随时可能在某个边缘场景下静默失败。