proxy_buffer_size仅用于缓冲HTTP响应头，必须≤单个proxy_buffers大小且需置于location块中；超限时Nginx直接返回502，常见于长JWT、多Set-Cookie或层层追加的调试头。
proxy_buffer_size 只管响应头，不碰响应体，也不是 TCP 层参数。它唯一作用是给后端返回的 HTTP 响应首部（状态行 + 所有 header 字段 + 每行末尾的 CRLF）预留一块固定大小的内存缓冲区。
防 502 错误的核心防线
当后端返回的响应头总长度超过 proxy_buffer_size 设置值时，Nginx 直接拒绝接收，记录 upstream sent too big header 错误，并向客户端返回 502。这不是性能问题，而是解析失败——Nginx 连状态码都还没完整读完就中断了。
- 典型诱因：JWT Token 过长、多段 Set-Cookie、Vary 头组合（如 Vary: Cookie, User-Agent）、中间件层层追加 X-Trace-ID 等调试头
- 验证方法：用
curl -v http://your-api/抓响应，统计所有以<开头的行（即响应头部分）字节数，含换行符；再加 20% 余量作为安全值 - 常见合理取值：8k（中小业务）、12k–16k（Next.js/Nuxt SSR + JWT）、HTTP/2 环境下还需同步检查
http2_max_field_size
必须满足的硬约束条件
这个值不能随意设大，它受底层机制严格限制：
CPA Update - Secure CLI Proxy API Maintenance
下载
安全更新和维护 CLI Proxy API（CPA）部署与配置。用于 CPA 镜像升级、配置变更、认证目录兼容修复、上线验证与回滚。适用于用户提到“CPA 更新/升级/配置改了/容器重建/回滚”等场景。
- 必须 ≤ 单个
proxy_buffers的大小（例如proxy_buffers 8 128k时，proxy_buffer_size最高只能设为 128k；否则nginx -t启动失败） - 必须放在
location块中，且在proxy_pass指令之前生效；放在http块里全局配置无效 - 即使
proxy_buffering off，它依然生效——因为响应头解析阶段无法跳过，必须先完整读取才能决定是否透传
不是“越大越稳”，而是“刚好够用”
它是 per-request 分配的内存，盲目设为 64k 在万级并发下会额外占用百 MB 内存。真正该调的情况很明确：
- 错误日志反复出现 upstream sent too big header
- 登录态页面返回含长 JWT 或动态增长 Cookie 的 HTML
- 后端启用了复杂 Vary 策略，且请求头本身也变长
- 网关链路多层透传，header 被不断追加
比调参更有效的动作
优先从源头控制 header 体积，比扩大 buffer 更可持续：
- 关闭后端调试开关（如 Express 的
etag: false、Koa 的 trace 中间件） - 合并重复 Cookie，避免同一域名下发多个同名 Cookie
- 精简或删除非必要自定义头（如多层嵌套的 X-Request-ID）
- 确认是否真需要 Vary: User-Agent —— 多数前端应用并不需要按 UA 缓存
