跳到主要内容

NET::ERR_HTTP2_PROTOCOL_ERROR 排查与修复全指南:从 DevTools 到 Nginx 缓冲区

一、net::ERR_HTTP2_PROTOCOL_ERROR 到底是什么错误

Chrome 抛出 net::ERR_HTTP2_PROTOCOL_ERROR 时,TCP 连接和 TLS 握手通常已经成功,失败发生在 HTTP/2 的帧层(framing layer):对端发来了不合规的帧,或者用 RST_STREAM / GOAWAY 直接把流掐断。浏览器拿不到完整响应,只能把整个请求标记为失败。

几个容易混淆的点:

  • 它不是证书、DNS、CORS 错误,改 hosts、换 DNS、清缓存通常都没用。
  • 它多数时候是服务端或中间设备的问题,不是浏览器的问题。你在服务器上用 curl 复现不出来,往往只是因为 curl 默认走 HTTP/1.1。
  • 它有两个高频变体:net::ERR_HTTP2_PROTOCOL_ERROR 200(状态码已经是 200,但响应体长度与 Content-Length 不符,连接中途断开),以及伴随出现的 ERR_HTTP2_PING_FAILED、ERR_HTTP2_SERVER_REFUSED_STREAM。

最常见的四类触发源:响应头体积超限(大 Cookie、多张图片和字体导致的超长头)、代理或安全设备对 HTTP/2 支持不佳、Nginx 缓冲区过小、后端响应长度与声明不一致。

二、第一步:确认问题真的出在 HTTP/2

不要一上来就改配置,先做三件事把问题范围缩到最小。

  1. 浏览器侧看协议列:F12 → Network → 表头右键 → 勾选 Protocol。若失败请求显示 h2,说明它确实走的是 HTTP/2;显示 http/1.1 则说明报错另有来源。
  2. 用 HTTP/1.1 做对照实验:同一路径,1.1 正常、h2 报错,基本可以锁定在 HTTP/2 层。
  3. 抓一次 netlog(可选,用于疑难杂症):访问 chrome://net-export/ 开始记录,复现问题后停止,把文件拖到 netlog viewer 里看 HTTP2_SESSION 事件的错误码。
# 1. 看服务端实际协商出的协议版本(h2 还是 1.1)
curl -sI --http2 https://example.com/ -o /dev/null -w '%{http_version}n'

# 2. 强制 HTTP/1.1 复测同一路径
curl -sI --http1.1 https://example.com/ -o /dev/null -w '%{http_version}n'

# 3. 看 ALPN 协商结果,确认服务端真的宣告了 h2
openssl s_client -connect example.com:443 -servername example.com -alpn h2 </dev/null 2>/dev/null | grep -i 'ALPN protocol'

# 4. 逐帧观察(需安装 nghttp2-client)
nghttp -nv https://example.com/ 2>&1 | head -n 40

Firefox 用户可以打开 about:config,把 network.http.http2.enabled 设为 false 做同样的对照测试,比 Chrome 更方便。

三、成因对照表:先对号入座

成因 典型特征 快速验证 处理方向
响应头过大(大 Cookie、多条 Set-Cookie、超长 Location) 只在登录后或特定页面出现,状态码常常是 200 清空 Cookie 后重试是否恢复 调大 header 缓冲区、精简 Cookie
Nginx 响应缓冲不足 error.log 有 upstream sent too big header 查看 error.log proxy_buffers / fastcgi_buffers
企业代理、TLS 检查设备不支持 h2 只有公司网络报错,切手机热点就正常 换网络、看证书签发者 升级设备或临时降级 1.1
CDN / 负载均衡节点 ALPN 不一致 偶发,刷新几次有时好有时坏 多次请求比对 remote_ip 统一各节点协议配置
Content-Length 与实际响应体不符 报错带 200,响应体被截断 curl 比对声明长度与实收字节 修正后端输出或 gzip 逻辑
服务端 HTTP/2 实现过旧或有 bug 高并发或大响应时偶发 关掉 http2 是否消失 升级 nginx / OpenSSL / 依赖库

四、Nginx 侧修复:缓冲区与头部上限

先看日志,别猜:

tail -n 200 /var/log/nginx/error.log | grep -Ei 'http2|too big header|upstream|GOAWAY'

出现 upstream sent too big header while reading response header from upstream,就是响应头缓冲区不够;出现 client sent too long header line,是请求头缓冲区不够。两者要分别调。

server {
    listen 443 ssl;
    http2 on;              # nginx >= 1.25.1 的新写法;老版本写 listen 443 ssl http2;

    ssl_certificate     /etc/nginx/ssl/example.com.pem;
    ssl_certificate_key /etc/nginx/ssl/example.com.key;
    ssl_protocols       TLSv1.2 TLSv1.3;   # HTTP/2 要求 TLS 1.2 以上

    # 客户端请求头(大 Cookie 场景必调)
    large_client_header_buffers 4 16k;
    http2_max_field_size       16k;
    http2_max_header_size      64k;

    location / {
        proxy_pass         http://backend;
        proxy_http_version 1.1;
        proxy_set_header   Connection "";

        # 响应头缓冲区,默认 4k/8k,最容易爆
        proxy_buffer_size       16k;
        proxy_buffers           8 32k;
        proxy_busy_buffers_size 64k;
    }

    location ~ .php$ {
        fastcgi_pass  unix:/run/php/php8.2-fpm.sock;
        fastcgi_buffer_size       32k;
        fastcgi_buffers           16 32k;
        fastcgi_busy_buffers_size 64k;
    }
}
nginx -t && systemctl reload nginx

如果确认是协议兼容性问题,可以先把 HTTP/2 关掉做验证(注意这是止血手段,不是长期方案):

# 临时验证:让 443 只跑 HTTP/1.1
# listen 443 ssl;
# http2 on;
nginx -t && systemctl reload nginx

curl -sI https://example.com/ -o /dev/null -w '%{http_version}n'   # 期望输出 1.1

关掉后一切正常,说明问题在协议层而不是应用逻辑。此时要么按上面的配置调大缓冲,要么临时维持 HTTP/1.1 恢复业务,同时继续定位根因。

五、应用层与内容层的坑

HTTP/2 对响应完整性比 HTTP/1.1 严格得多。以下几种情况在 1.1 下能勉强显示,在 h2 下会直接变成协议错误:

  • Content-Length 与实际字节数不符:后端少输出或多输出,浏览器等不到结束帧。
  • 204 / 304 响应带了 body:协议不允许。
  • gzip 压缩后未更新 Content-Length:常见于自己实现的压缩中间件。
  • SSE / 长轮询被中间层缓冲:代理把流式响应攒成一整块,导致帧顺序错乱。
# 对比声明的 Content-Length 与实际收到的字节数
curl -sI --http2 https://example.com/big.json | grep -i content-length
curl -s  --http2 https://example.com/big.json | wc -c

另外别忘了 Cookie。单域名下堆积十几条追踪 Cookie、总长度超过 8KB 时,请求头就会顶到服务端的 http2_max_field_size 上限,表现同样是这个错误。精简 Cookie、把静态资源拆到无 Cookie 的子域名,往往比调参数更治本。

六、代理、CDN 与企业 TLS 检查设备

判断方法很简单:换网络。手机热点正常、公司网络报错,问题就出在中间的设备上。再看一眼证书是谁签的:

# 出现公司自签 CA,说明流量被 TLS 检查设备解密了
openssl s_client -connect example.com:443 -servername example.com </dev/null 2>/dev/null | openssl x509 -noout -issuer -subject

如果 issuer 是公司内部 CA,说明流量在中间被 MITM 解密。这类设备如果不支持 HTTP/2,或者对 ALPN 的处理有 bug,浏览器侧就会报协议错误。处理顺序:升级设备固件 → 为该域名加解密例外 → 实在不行在设备上把 h2 降级为 1.1。

用 CDN 时,要确认回源协议和边缘节点的 ALPN 配置一致,并排查是否只有部分节点有问题:

# 连续请求,看是否只有某些节点异常
for i in $(seq 1 10); do
  curl -sI --http2 https://example.com/ -o /dev/null 
    -w '%{remote_ip} %{http_version} %{http_code}n'
done

若某几个 IP 稳定复现,直接把情况提给 CDN 厂商,并临时在 DNS 层摘掉这些节点。

七、真实报错信息速查

报错原文 出现位置 含义与处理
curl: (92) HTTP/2 stream 1 was not closed cleanly: PROTOCOL_ERROR (err 1) curl 客户端 对端发了非法帧或提前关流。用 –http1.1 对照,确认是服务端还是中间设备
curl: (92) … INTERNAL_ERROR (err 2) curl 客户端 服务端内部错误主动重置流,去查应用日志和上游健康状态
curl: (92) … REFUSED_STREAM (err 7) curl 客户端 服务端拒绝该流,通常是并发流上限(http2_max_concurrent_streams)或连接数打满
upstream sent too big header while reading response header from upstream nginx error.log 响应头缓冲区不足,调大 proxy_buffer_size / fastcgi_buffer_size
client sent too long header line nginx error.log 请求头过大,调大 large_client_header_buffers 并精简 Cookie
net::ERR_HTTP2_PROTOCOL_ERROR 200 Chrome Console 状态码已是 200 但响应体被截断,重点查 Content-Length 与 gzip
net::ERR_HTTP2_INADEQUATE_TRANSPORT_SECURITY Chrome Console TLS 版本或加密套件不满足 h2 要求,需 TLS 1.2+ 并禁用 RC4/CBC 老套件
HTTP/2 error code: PROTOCOL_ERROR / Some requests were not processed nghttp 输出 与上面同类,用 nghttp -nv 看具体是哪一帧出的问题

注意区分:431 Request Header Fields Too Large 是请求头超限的明确响应,而 ERR_HTTP2_PROTOCOL_ERROR 是连接被掐断,后者连状态码都可能拿不到。

八、五分钟内先恢复业务

  1. 关 HTTP/2:注释掉 http2 on; 或 listen ... http2,nginx -t && systemctl reload nginx,10 秒内生效,用户立刻能访问。
  2. 调大缓冲区:proxy_buffer_size 16k; + proxy_buffers 8 32k;,覆盖八成头部超限场景。
  3. 绕开可疑中间层:CDN 切回源站、企业网络让用户切热点,用于确认故障域。
  4. 回滚最近变更:升级、改 gzip、改 Cookie 策略,都是高发诱因。

业务恢复后再按第二到第七节的顺序定位根因,不要在故障期间一边救火一边大改配置。

九、FAQ

Q:清浏览器缓存、换浏览器有用吗?
基本没用。这是协议层错误,不是缓存问题。换浏览器有时看着好了,只是恰好命中了不同节点或不同连接。

Q:为什么只有部分用户报错?
HTTP/2 连接是复用的,一条连接出问题只影响走这条连接的请求。不同用户命中的边缘节点、代理设备、网络出口不同,所以表现差异很大。

Q:ERR_HTTP2_PROTOCOL_ERROR 200 和普通的有区别吗?
有。带 200 说明响应头已经收到、状态码是成功的,失败发生在响应体传输阶段,优先怀疑 Content-Length 不符、gzip 处理错误、后端提前关闭输出。

Q:只在登录后出现,是什么原因?
典型的大 Cookie 或大量 Set-Cookie 导致请求/响应头膨胀。清掉 Cookie 再登录一次,如果第一次正常、第二次报错,基本可以确认。

Q:关掉 HTTP/2 会明显变慢吗?
对普通页面影响有限,对图片、字体多的高并发站点会有可感知的差距(少了多路复用和头部压缩)。所以关掉只作止血,根因还是要修。

Q:升级 nginx 能解决吗?
如果根因是旧版本 HTTP/2 实现的 bug,能。但升级前请确认配置写法:1.25.1 之后 listen 443 ssl http2; 已废弃,要改成 listen 443 ssl; 加 http2 on;,否则会告警甚至不生效。

Q:用了 Cloudflare、阿里云 CDN 这类服务怎么排查?
先直连源站(改 hosts 指向源 IP)复测。源站正常、走 CDN 报错,就是 CDN 侧问题,带上 curl -v 输出和复现时间提交工单。

Q:手机 App、小程序也报这个错怎么办?
App 通常直接用系统网络库,报错文案不同但根因一致。抓包看是否被中间设备解密,再按第四、六节处理服务端配置。