应调大 proxy_buffer_size，当错误日志出现“upstream sent too big header”时，需实测响应头大小（含\r\n），按余量20%并向上取整至2的幂次（如8k/16k/32k）设置，且值不得超过proxy_buffers单个buffer大小。
直接在 location 或 server 块中设置 proxy_buffer_size，值要略大于实测最大响应头长度（含每行末尾的 \r\n），常见取值为 8k、16k 或 32k，且必须小于 proxy_buffers 中单个 buffer 的大小。
怎么确认要不要调？
别一上来就改配置。先看真实信号：
- 错误日志反复出现
upstream sent too big header - 后端返回含长 JWT、多段
Set-Cookie、复杂Vary头（如Vary: Cookie, User-Agent）或层层注入的调试头（X-Trace-ID等） - SSR 应用（如 Next.js/Nuxt）登录后首屏 HTML 响应头明显变大
- HTTP/2 下仍报 502，可能是
http2_max_field_size截断单字段，需同步检查
怎么测出准确大小？
靠实测，不靠猜：
- 用
curl -v https://your-api/ 2>&1 | grep '^ 抓原始响应头，逐行统计字符数 + 每行末尾的 <code>\r\n（各占 1 字节） - 临时开启 debug 日志：
error_log /var/log/nginx/error.log debug;，复现请求后日志会明确写类似header: 13782 bytes - 实测 5212 字节 → 加 20% 余量 ≈ 6254 → 向上取整到最近的 2 的幂次 → 设
proxy_buffer_size 8k - 实测 28900 字节 → 设
proxy_buffer_size 32k
怎么正确设置？
配置有硬约束，不能随意填：
- 必须放在
location或server块中，且在proxy_pass之前；放在http块里不生效 - 值必须 ≤
proxy_buffers中每个 buffer 的大小（例如proxy_buffers 8 128k，则proxy_buffer_size最大只能设128k，但通常16k就足够） - 仅在
proxy_buffering on时起作用；若关闭缓冲（如 SSE、gRPC-Web），该参数被忽略 - 推荐值：普通 API 用
8k，JWT/SSR 场景用16k，多中间件+动态 Cookie 场景用32k
配套动作不能少
单改 proxy_buffer_size 是半套方案：
- 同步检查并精简后端响应头：关掉未收敛的调试头、合并重复
Set-Cookie、避免中间件链路反复追加 trace 字段 - 若后端也返回大 body，需匹配设置
proxy_buffers（如8 128k）和proxy_busy_buffers_size（建议设为单 buffer 大小的 2 倍，如256k） - HTTP/2 环境下务必核对
http2_max_field_size（默认 4k），它独立限制 HPACK 解码后的单字段长度 - 修改后执行
nginx -s reload，再查 error.log 是否还有相关报错
