Go HTTP/2 异常怎样用 GODEBUG 获取线索

Go 的 net/http 已经提供了 HTTP/2 支持，但异常发生时，业务层往往只看到“请求失败”或“连接被关闭”。这时最省事的做法不是马上改连接池或重写 Transport，而是先在复现窗口打开 GODEBUG，让标准库把 HTTP/2 的连接、帧和错误线索写出来。

官方资料入口：https://go.dev/src/net/http/doc.go；GODEBUG 背后的兼容性说明：https://go.dev/doc/godebug。

先用 http2debug=1 看概要，再用 http2debug=2 看帧；如果日志没有出现，先确认请求确实走进了 HTTP/2，并确认你观察的是进程实际输出的标准错误。

先判断问题是否属于 HTTP/2

http2debug 不是万能的网络抓包器。它只对 Go 的 HTTP/2 实现提供线索。如果请求最终走的是 HTTP/1.1，或者在 TLS、代理、DNS 阶段就失败，打开它也不会替你解释全部原因。

标准库文档说明，使用 HTTPS 时，http.Server 和 http.DefaultTransport 会自动尝试启用 HTTP/2；自定义 Transport、Dialer 或 TLS 配置可能改变这个判断。排障第一步应该是把请求 URL、Transport 配置和部署链路记在一起，而不是看到“HTTP”就默认是 h2。

package main

import (
	"context"
	"fmt"
	"net/http"
	"time"
)

func main() {
	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
	defer cancel() // 让超时上下文在请求结束后释放资源

	req, err := http.NewRequestWithContext(ctx, http.MethodGet, "https://example.com/", nil)
	if err != nil {
		panic(err) // 示例只关注协议排障，生产代码应按业务记录错误
	}

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err) // 先保留错误原文，便于与 GODEBUG 日志按时间对应
	}
	defer resp.Body.Close() // 读取或丢弃响应体后关闭连接体
	fmt.Println(resp.Proto) // 只打印协商结果，不把它当成完整诊断结论
}

上面的 resp.Proto 只能帮助确认结果，例如是否显示为 HTTP/2.0。它不是额外的验证系统，也不能替代调试日志；重点是把“协议版本”和“异常发生的阶段”先分开。

选择 GODEBUG 的日志粒度

Go 官方 net/http 文档列出了两个有用的级别：http2debug=1 开启较详细的 HTTP/2 调试日志，http2debug=2 进一步输出帧转储。两者都适合临时复现，不适合长期打开。

# 先看连接与请求的概要线索，减少日志噪声
GODEBUG=http2debug=1 go run ./cmd/client

# 只有概要日志不足以定位时，再打开帧级信息
GODEBUG=http2debug=2 go run ./cmd/client

如果程序通过 systemd、容器或进程管理器启动，应该把同样的环境变量加到实际启动入口，而不是只在当前交互式 Shell 里设置。日志通常写向进程的标准错误，收集器若只接管标准输出，就会造成“开关不生效”的错觉。

按客户端和服务端拆分作用范围

当同一台机器既是 HTTP/2 客户端又是服务端时，完整日志很容易混在一起。http2client=0 和 http2server=0 用于控制相应方向是否启用 HTTP/2；排障时不要为了“多拿一些日志”随手关闭协议，否则你可能改变了原本要观察的行为。

# 只观察客户端方向的 HTTP/2 日志
GODEBUG=http2debug=1,http2server=0 go run ./cmd/client

# 只观察服务端方向的 HTTP/2 日志
GODEBUG=http2debug=1,http2client=0 go run ./cmd/server

这里的组合适合隔离噪声，不代表所有部署都应该这样配置。GODEBUG 是进程级环境变量，设置前要确认进程角色；如果一个进程同时承载客户端调用和 HTTPS 服务，关闭其中一侧会影响真实行为。

用日志建立一条排障判断链

拿到日志后，建议按“连接是否建立—控制帧是否正常—请求数据是否推进—谁先发出错误”四层来读。不要从某一行看起来吓人的文本直接下结论，因为 HTTP/2 的控制帧、请求帧和连接错误需要放回同一条连接里理解。

帧级日志适合回答“哪一类交互先出现异常”，不适合直接替代抓包或服务端业务日志。若涉及代理、网关或另一种语言实现，还要把对端日志加入同一时间线；单看 Go 进程的输出，最多只能缩小范围。

哪些做法容易把线索越查越乱

• 一上来就开 =2：帧很多时，真正的异常会淹没在正常通信中，先用 =1 划定时间段更容易。
• 只看业务返回错误：业务层的超时或 EOF 不一定是根因，要把它和连接、帧、代理日志对齐。
• 把 http2client=0 当成修复：它只是改变行为的诊断手段，可能让请求回退到其他协议，不能证明 HTTP/2 本身已经被修好。
• 忘记关闭调试：GODEBUG 随进程环境生效，复现结束后要从启动配置、服务编排和临时 Shell 中移除。

一份可复用的判断清单

遇到 Go HTTP/2 异常，可以按下面顺序处理：先记录请求方向和进程角色；再确认是否为 HTTPS 以及最终协议；然后用 http2debug=1 重现一次；仍不清楚时仅在短窗口启用 =2；最后把客户端、服务端、代理和业务日志按时间对齐。只有当线索表明是 HTTP/2 实现或配置边界时，才进入 Transport、Server 或 HTTP/2 参数的进一步调整。

这个顺序的价值在于保持诊断变量稳定：先观察，再隔离，再下钻。GODEBUG 负责把标准库内部发生了什么暴露出来，真正的修复仍要回到连接配置、对端行为、超时策略或代理链路本身。

相关问题

http2debug=1 和 =2 有什么区别？

=1 适合先看较概要的调试信息，=2 会进一步输出帧转储。后者信息量明显更大，应当只在需要缩小到帧级时短时使用。

为什么设置了 GODEBUG 却没有日志？

常见原因是请求没有进入 Go 的 HTTP/2 实现、变量没有传给实际进程，或者日志写到标准错误而采集器只收集标准输出。先排这三层。

能不能一直开着 HTTP/2 调试日志？

不建议。它会增加输出噪声和采集成本，也会让正常通信淹没异常。更稳妥的做法是限定复现时间和请求范围，完成定位后立即关闭。