Go GODEBUG=http2debug 怎样定位 HTTP/2 帧问题

Go 程序遇到 HTTP/2 请求卡住、流被重置或连接提前结束时，可以先用 GODEBUG=http2debug=1 看协议日志；如果还不能确定是哪一个流或哪一种帧触发异常，再升级为 GODEBUG=http2debug=2。后者会进一步输出帧转储。关键是先确认请求真的走了 HTTP/2，否则看到的可能只是 HTTP/1.1 或应用层日志。

官方地址：https://pkg.go.dev/net/http

最稳妥的顺序是：确认协议 → 用 1 观察整体顺序 → 用 2 关联 stream ID 和帧 → 对照客户端、服务端与代理的边界复现。调试结束后要移除 GODEBUG，因为帧日志可能暴露请求头和正文线索。

先确认请求确实是 HTTP/2

如果客户端拿到的响应协议不是 HTTP/2，http2debug 就不会替你把 HTTP/1.1 变成帧级问题。客户端可以记录 Response.Proto，服务端则可观察请求的 Proto 字段：

resp, err := client.Do(req)
if err != nil {
    // 先保留网络错误，避免把没有响应误判成帧错误。
    return err
}
defer resp.Body.Close()

// ProtoMajor=2 才说明本次响应按 HTTP/2 解析。
log.Printf("proto=%s status=%s", resp.Proto, resp.Status)

排查时还要检查是否设置了 GODEBUG=http2client=0 或 GODEBUG=http2server=0，以及自定义 Transport、代理和 TLS 配置是否让 HTTP/2 没有被启用。先把这些条件排除，后面的日志才有意义。

GODEBUG=http2debug 的两档输出怎么选

http2debug=1 适合第一轮定位：它提供更详细的 HTTP/2 调试日志，能帮助你判断连接、请求和响应的大致顺序。命令要放在进程启动前：

# 第一轮只复现一个目标请求，降低日志噪声。
GODEBUG=http2debug=1 go test -run '^TestHTTP2Request$' -v ./...

如果问题表现为某个流突然失败、窗口迟迟不增长或连接在多个请求之间被关闭，再使用 http2debug=2：

# 第二轮打开更详细的帧转储，只在测试环境短时间使用。
GODEBUG=http2debug=2 go test -run '^TestHTTP2Request$' -v ./...

不要一开始就长期打开 2 档。帧级日志量大，且 HEADERS、DATA 等内容可能携带敏感信息；先用 1 档缩小复现窗口，再把 2 档用于一次性深挖，通常更容易读。

按 stream ID 阅读关键帧

帧日志最容易误读的地方，是把不同请求混在一起。先按 stream ID 分组，再按时间顺序串联同一条流。可以用下面的关系作为阅读框架：

例如同一个 stream 7 先出现 HEADERS，随后只有少量 DATA，最后出现 RST_STREAM，说明要继续查流级错误码、服务端处理和代理行为；如果多个流都在同一连接收到 GOAWAY，则应把视线提升到连接、对端重启或优雅关闭边界。

常见误区与收敛清单

• 没有 HTTP/2 日志，不等于 Go 丢帧：先看 Response.Proto，再查 HTTP/2 是否被关闭。
• 看到 DATA 停顿，不要立即断言是网络丢包；同时对照 WINDOW_UPDATE、请求上下文超时和服务端是否仍在读取。
• 看到 GOAWAY，不要把它等同于单个请求失败；它是连接级边界，还要看已有流是否完成。
• 不要在生产长期保留 http2debug=2；复现完成后恢复默认启动配置并清理调试日志。

相关问题

为什么开启 http2debug 却看不到帧？最常见原因是本次请求没有协商为 HTTP/2，或客户端/服务端通过 GODEBUG、Transport、代理配置关闭了 HTTP/2。先记录协议版本。

http2debug=1 和 2 应该怎么取舍？1 用于低噪声地确认连接和请求顺序，2 用于需要对照 stream ID、窗口和帧类型的深度排障；两者都只应在受控复现窗口使用。

事实依据：Go net/http 文档列出了 http2debug=1 和 http2debug=2 的作用；x/net/http2 源码也展示了相应的详细日志与帧读写开关。正文中的图是原创静态说明图，不代表真实运行输出。