proxy_buffer_size 是 Nginx 专用于缓存响应头的独立缓冲区，需根据实测响应头大小（含\r\n）向上取整至最近 2 的幂次设置，且必须小于 proxy_buffers 单块大小、仅在 proxy_buffering on 时生效，HTTP/2 下还需兼顾 http2_max_field_size。
proxy_buffer_size 是 Nginx 专用于接收后端响应头（status line + 所有 headers）的独立缓冲区，不处理响应体、不参与 TCP 层传输，也不受 proxy_buffers 影响。它的核心作用是防止因响应头过大触发 upstream sent too big header 错误，导致 502 Bad Gateway。
怎么确认该不该调？
别一上来就设 32k 或 64k。先看真实需求：
- 错误日志里反复出现 upstream sent too big header while reading response header from upstream
- 后端返回含长 JWT、多段 Set-Cookie、Vary 字段组合（如 Vary: Cookie, User-Agent）、或层层注入的调试头（X-Trace-ID、X-Request-ID）
- SSR 应用（Next.js/Nuxt）登录后首屏 HTML 响应头体积明显增长
- HTTP/2 环境下，即使 proxy_buffer_size 合理，仍报 502 → 可能是 http2_max_field_size 截断单字段
怎么测出准确大小？
必须基于实测，不是猜：
aperture: the L402 aware reverse proxy
下载
安装并运行 Aperture（Lightning Labs 的 L402 闪电反向代理），用于创建 L402 付费墙、配置付费 API 端点、为其他代理托管付费内容或测试 L402 认证流程。
- 用
curl -v https://your-api/ 2>&1 | grep '^ 抓原始响应头，逐行统计字符数 + 每行末尾\r\n（各占 1 字节） - 临时开启 debug 日志：
error_log /var/log/nginx/error.log debug;，复现请求后日志会明确提示类似 header: 13782 bytes - 实测最大为 5212 字节 → 推荐设
proxy_buffer_size 8k（向上取整到最近的 2 的幂次，留 20% 余量） - 实测 28900 字节 → 设
proxy_buffer_size 32k
设置时必须遵守的硬约束
这个值不是孤立存在的，必须满足底层协同逻辑：
- 必须小于单块
proxy_buffers的大小。例如proxy_buffers 8 128k，则proxy_buffer_size最大只能设128k；通常设16k就足够 - 只在
proxy_buffering on时生效。若关闭缓冲（如 SSE、gRPC-Web 场景），该参数被完全忽略 - 必须放在
location或server块中，且需在proxy_pass之前；放在http块里不会生效
配套动作不能少
单改 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 解码后的单字段长度，和proxy_buffer_size是两道独立校验
