跳到主要内容

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 只能用于验证,不能作为面向用户的解决方案。