Nginx 报错 "upstream sent too big header" 怎么解决

Nginx 上游响应头过大时，先查长 Set-Cookie、重定向等来源，再按实际大小评估 proxy_buffer_size 等缓冲参数。FastCGI 使用不同指令，修改须校验。

观测云编辑部 2026-09-29 3 分钟阅读更新于 2026-09-29

直接回答：该错误通常表示上游响应头超过对应模块的响应头缓冲区。 先检查异常大的 Set-Cookie 或其他头字段，再按实际大小调整 proxy_buffer_size 等参数并校验配置；FastCGI 使用 fastcgi_buffer_size 等不同指令，不能直接照搬。

报错长什么样

upstream sent too big header while reading response header from upstream,
client: 10.0.0.8, server: api.example.com, request: "GET /login HTTP/1.1",
upstream: "http://127.0.0.1:8080/login", host: "api.example.com"

用户侧表现为 502 Bad Gateway。

解决方案：调大代理缓冲区

在报错的 server 或 location 块中：

location / {
    proxy_pass http://127.0.0.1:8080;

    proxy_buffer_size   16k;
    proxy_buffers       8 16k;
    proxy_busy_buffers_size 32k;
}

参数含义：

参数	作用
`proxy_buffer_size`	读取响应头部（含状态行）用的缓冲区，报错直接相关的就是它
`proxy_buffers`	读取响应主体用的缓冲区数量与单块大小
`proxy_busy_buffers_size`	响应未读完时允许对外发送的缓冲上限

proxy_buffer_size 必须大于上游实际返回的头部总大小。16k 仅为说明配置关系的示例，实际大小根据受影响请求的响应头和并发内存预算决定。

修改后 nginx -t 验证并重载：systemctl reload nginx。

FastCGI（PHP-FPM）场景

FastCGI 走的是另一组参数，报错文案相同但要改这里：

location ~ \.php$ {
    # 仅为缓冲配置片段；完整配置还需正确的 SCRIPT_FILENAME、参数和脚本访问限制
    fastcgi_pass unix:/run/php/php-fpm.sock;
    fastcgi_buffer_size  16k;
    fastcgi_buffers      8 16k;
}

根因排查：为什么响应头这么大

调缓冲区是治标，建议同步查根因：

超长 Cookie：应用每次响应都 Set-Cookie 一大串（常见于把大量数据塞进 Cookie 的会话机制），应改用服务端会话存储
冗余自定义头：框架或中间件输出了大量调试头
重定向 URL 过长：Location 头塞了超长回跳地址

可以用 curl 直接看上游响应头大小：

curl -s -D - -o /dev/null http://127.0.0.1:8080/login | wc -c

修改缓冲区配置后，除了重试原请求，还应检查该错误是否继续出现。已用观测云采集 Nginx 错误日志时，按上游地址和变更时间筛选 upstream sent too big header，再核对响应头大小；单看 502 数量无法区分响应头过大与其他回源故障。

常见问题（FAQ）

Q：把 proxy_buffer_size 调得特别大（如 128k）有副作用吗？
A：该缓冲区按连接分配，过大的值会放大并发连接下的内存占用。建议按上游实际头部大小留出经验证的合理余量，不要无脑拉满。

Q：调大缓冲区后依然 502？
A：确认修改落在了正确的 server/location 块（可能被更具体的 location 覆盖），并用上述 curl 命令测量受影响请求的实际响应头大小（需一致的 Host/认证上下文，不要泄露 Cookie）。若上游头确实超过你的设置，继续上调或从应用侧压缩头部。

Q：负载均衡器后面多台上游只有一台报这个错？
A：很可能那台机器上的应用版本或会话数据不同（比如只有它有累积超长 Cookie 的请求）。单独 curl 该上游对比响应头大小即可确认。

参考资料

本文依据官方资料核对，未进行现场运行测试；代码与配置示例需结合实际版本、权限和环境验证。