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
不要一上来就改配置,先做三件事把问题范围缩到最小。
- 浏览器侧看协议列:F12 → Network → 表头右键 → 勾选
Protocol。若失败请求显示h2,说明它确实走的是 HTTP/2;显示http/1.1则说明报错另有来源。 - 用 HTTP/1.1 做对照实验:同一路径,1.1 正常、h2 报错,基本可以锁定在 HTTP/2 层。
- 抓一次 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 是连接被掐断,后者连状态码都可能拿不到。
八、五分钟内先恢复业务
- 关 HTTP/2:注释掉
http2 on;或listen ... http2,nginx -t && systemctl reload nginx,10 秒内生效,用户立刻能访问。 - 调大缓冲区:
proxy_buffer_size 16k;+proxy_buffers 8 32k;,覆盖八成头部超限场景。 - 绕开可疑中间层:CDN 切回源站、企业网络让用户切热点,用于确认故障域。
- 回滚最近变更:升级、改 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 通常直接用系统网络库,报错文案不同但根因一致。抓包看是否被中间设备解密,再按第四、六节处理服务端配置。