NET::ERR_HTTP2_PROTOCOL_ERROR 全解析:定位、修复与验证(Nginx / 代理 / CDN 实战)
一、NET::ERR_HTTP2_PROTOCOL_ERROR 到底是什么
这是 Chromium 在 HTTP/2 会话层收到不符合 RFC 9113 规范的帧时抛出的通用错误。它不代表「连不上」:DNS 已解析、TCP 已建立、TLS 已握手、ALPN 已协商为 h2,出错点在之后的帧交换阶段——HPACK 头部压缩上下文被破坏、帧长度越界、收到非法 GOAWAY/RST_STREAM,或响应头超过对端声明的 SETTINGS_MAX_HEADER_LIST_SIZE。
所以排查方向不是「网络通不通」,而是「谁在 h2 这一层把数据弄坏了」。三大高发来源:
- 响应头 / 缓冲区超限:Cookie 膨胀、多条 Set-Cookie、Nginx 默认 4k/8k 缓冲装不下后端响应头。
- 中间设备:企业 TLS 检查设备、老旧代理、WAF 只支持 HTTP/1.1,或改写帧后破坏 HPACK 状态。
- 服务端配置:Nginx 旧版 http2 指令、后端 HTTP/1.0 且无 Content-Length、h2c 与 TLS 端口混用。
二、三分钟确认:是不是 HTTP/2 的问题
Chrome 打开 F12 → Network → 右键表头勾选 Protocol 列,观察出问题的请求是 h2 还是 http/1.1。若同一 URL 在 h1.1 下正常、h2 下报错,基本可锁定协议层。
# 1. 确认 ALPN 协商结果,应输出 ALPN protocol: h2
openssl s_client -connect example.com:443 -alpn h2 -servername example.com </dev/null 2>/dev/null | grep -i alpn
# 2. 强制走 h2,看 curl 的具体报错
curl -I --http2 https://example.com/ -v
# 3. 强制走 h1.1 做对照
curl -I --http1.1 https://example.com/
# 4. 针对图片/字体多的具体资源复现
curl -I --http2 https://example.com/assets/app.js
需要更细的帧级信息时,用 chrome://net-export/ 录制日志,再导入 netlog viewer,搜索 HTTP2_SESSION 的 error_code,能直接看到是 HTTP2_ERROR_PROTOCOL 还是 HTTP2_ERROR_COMPRESSION。
三、根因一:响应头 / 缓冲区超限(最常见)
Nginx 作为反向代理时,后端返回的响应头一旦超过 proxy_buffer_size(默认 4k 或 8k),Nginx 会截断或改用 chunked 转发,浏览器侧就会报协议错误。典型日志:
upstream sent too big header while reading response header from upstream
修复配置:
location / {
proxy_pass http://backend;
proxy_http_version 1.1;
proxy_set_header Connection "";
proxy_buffer_size 32k;
proxy_buffers 8 32k;
proxy_busy_buffers_size 64k;
# 大 Cookie、多 Set-Cookie 场景继续放大
large_client_header_buffers 4 32k;
}
PHP-FPM 场景换成 FastCGI 缓冲:
fastcgi_buffer_size 32k;
fastcgi_buffers 16 32k;
fastcgi_busy_buffers_size 64k;
先量一下响应头到底多大,再决定加多少:
curl -sI https://example.com/ | wc -c
curl -sI https://example.com/ | grep -i -E "set-cookie|content-security"
nginx -t && nginx -s reload
注意:真正撑爆缓冲的常常是 Cookie 而不是服务端响应头,登录态下才复现的报错要优先怀疑它。
四、根因二:中间设备(TLS 检查 / 代理 / WAF / CDN)
企业网络中「只有内网报错、手机 4G 正常」的情况,九成属于此类。SSL 解密设备若只支持 HTTP/1.1,或对 h2 帧做了重写却未同步 HPACK 动态表,客户端立即判定协议违规。
- 症状:同一站点换浏览器同样报错;curl 直连正常,走公司代理失败;关掉代理立即恢复。
- 验证:代理链路下分别用 h1.1 与 h2 请求对比。
- 处置:升级网关固件、对该域名关闭 SSL 解密,或短期按网段/UA 分流降级到 h1.1。
curl -I --http2 -x http://proxy.corp:8080 https://example.com/ -v
curl -I --http1.1 -x http://proxy.corp:8080 https://example.com/ -v
CDN 场景同理:先在 CDN 侧关闭 HTTP/2 或改为回源 HTTP/1.1,确认问题消失后再逐段开启,避免同时改动源站和边缘配置。
五、根因三:服务端配置与 h2 规范不匹配
Nginx 1.25.1 起 listen 的 http2 参数已废弃,继续使用会告警,需改为独立指令:
# 旧写法(1.25.1+ 会告警)
listen 443 ssl http2;
# 新写法
listen 443 ssl;
http2 on;
其它高频问题:
- 后端 upstream 使用 HTTP/1.0 且无 Content-Length,Nginx 只能 chunked 转发,部分客户端报协议错误 → 显式配置
proxy_http_version 1.1。 - gRPC / 明文 h2c 混用:h2c 后端需要
grpc_pass或对应的 http2 监听,普通proxy_pass到 h2c 会失败。 - TLS 过旧(仅 TLS 1.0/1.1 或弱套件)在 Chrome 中实际报
ERR_HTTP2_INADEQUATE_TRANSPORT_SECURITY,常被误认为本文错误。 - Server Push 已被 Chrome 移除支持,残留的
http2_push配置无收益,建议删除。
nginx -V 2>&1 | tr ' ' 'n' | grep -i http_v2
curl -sI --http2 https://example.com/ | head -1
六、方案对比表
| 方案 | 适用场景 | 关键操作 | 代价 / 副作用 | 推荐度 |
|---|---|---|---|---|
| 增大 Nginx 缓冲区 | 响应头超限、502 伴随 h2 报错 | proxy_buffer_size 32k;fastcgi_buffers 16 32k | 单连接内存小幅上升 | ★★★★★ |
| 精简响应头与 Cookie | Cookie 膨胀、重复 Set-Cookie | 合并 Cookie、去掉冗余安全头 | 需要改应用代码 | ★★★★★ |
| 升级中间设备 / 关闭解密 | 仅内网或仅代理链路报错 | 升级固件、对该域名绕过 SSL 检查 | 安全策略调整,需审批 | ★★★★ |
| 升级 Nginx 并改 http2 on | 旧版本、废弃指令告警 | listen 443 ssl; http2 on; | 需回归测试 | ★★★★ |
| CDN 终结 HTTP/2、回源 h1.1 | 源站老旧无法改配置 | 边缘开 h2,回源协议设为 HTTP/1.1 | 成本与架构变更 | ★★★ |
| 临时关闭 HTTP/2 | 快速判定是否为协议兼容问题 | listen 443 ssl;(去掉 http2) | 失去多路复用,性能下降 | ★★(仅验证用) |
七、排错实录:真实报错与对应处理
报错 1:curl: (92) HTTP/2 stream 1 was not closed cleanly: PROTOCOL_ERROR (err 1)
多为后端响应头过大或 Nginx 缓冲不足。先调 proxy_buffer_size,再看后端是否返回了畸形头部。
报错 2:upstream sent too big header while reading response header from upstream
直接证据。把 proxy_buffer_size 提到 32k~64k,并检查应用是否在每次请求都重复下发 Set-Cookie。
报错 3:Chrome 仅在登录态报 ERR_HTTP2_PROTOCOL_ERROR,退出登录正常
Cookie 超过 8k 触发头部列表超限。用 large_client_header_buffers 4 32k; 缓解,根治要拆分 Cookie 域。
报错 4:HTTP/2 client preface string missing or corrupt
明文 h2c 打到了 443 端口,或中间设备把 h2 帧按 h1 解析后转发。确认客户端访问的是 https,且代理未做错误的协议降级。
报错 5:Go 客户端 http2: server sent GOAWAY and closed the connection 或 stream error: stream ID 1; PROTOCOL_ERROR
服务端主动 GOAWAY(重启、超载、keepalive 超时)或响应头超限。对照 Nginx error.log 的时间戳与 keepalive_timeout 设置。
报错 6:ERR_HTTP2_INADEQUATE_TRANSPORT_SECURITY
不是同一个错误,但常被混谈。原因是 TLS 版本或套件不满足 h2 要求,配置 ssl_protocols TLSv1.2 TLSv1.3; 并使用现代套件即可。
报错 7:502 / 504 与 h2 报错同时出现
先修后端。上游崩溃返回空响应时,Nginx 转发的空帧在客户端看来就是协议错误。
八、上线前验证清单
- ALPN 协商结果为 h2,且
curl --http2返回 200。 nginx -t通过,error.log 中不再出现 too big header。- 带完整 Cookie 的登录态请求可正常返回。
- 公司内网、4G、海外节点分别验证一遍。
- 做一次关闭 http2 的对照实验,确认问题边界。
nginx -t && nginx -s reload
curl -sI --http2 https://example.com/ | head -1
tail -f /var/log/nginx/error.log | grep -i -E "http2|too big header"
九、FAQ
Q1:为什么只有 Chrome 报错,Safari 却正常?
不同客户端对 h2 帧的容错程度不同。Chrome 对 HPACK 与帧边界更严格,中间设备轻微改写就可能只在 Chrome 复现。
Q2:关掉 HTTP/2 会影响性能或 SEO 吗?
会失去多路复用与头部压缩,但 HTTP/1.1 + keepalive 仍可正常工作。它只应作为定位手段,不应长期停留。
Q3:这到底是用户网络问题还是服务器问题?
用外部节点直连跑 curl --http2 即可判定。直连正常而特定网络报错,问题在中间链路;直连也报错,问题在服务端配置。
Q4:和 ERR_HTTP2_INADEQUATE_TRANSPORT_SECURITY 有什么区别?
前者是帧层违规,后者是 TLS 层不达标。后者改 TLS 版本与套件,前者查缓冲与中间设备。
Q5:用了 CDN 还报错,该从哪查?
先固定回源为 HTTP/1.1 排除源站,再逐段开启边缘 h2。同时确认 CDN 是否对 Cookie 或响应头做了二次改写。
Q6:需要让用户改浏览器设置吗?
不需要。通过 chrome://flags 禁用 HTTP/2 只能用于验证,不能作为面向用户的解决方案。