Go HTTP/2 为什么被自定义 Transport 意外关闭

Go 客户端换成自定义 http.Transport 后，HTTP/2 突然不再使用，常见原因不是服务端随机关闭连接，而是自定义了 Dial、DialContext、DialTLS 或 TLSClientConfig，触发了 Transport 对 HTTP/2 的保守默认。要保留这些自定义能力，又继续尝试 HTTP/2，需要显式表达协议意图，并确认 TLS 的 ALPN 协商没有被自定义拨号绕开。

先检查 Transport 是否自定义了拨号或 TLS，再决定使用 ForceAttemptHTTP2 还是显式配置 Protocols。如果是自定义 DialTLSContext，还要保证返回的连接已经完成 TLS，并支持 ALPN 状态，否则单独把开关设为 true 也不能保证得到 HTTP/2。

官方资料：https://pkg.go.dev/net/http#Transport

为什么自定义 Transport 会让 HTTP/2 默认关闭

http.DefaultTransport 本身会尝试 HTTP/2，但自定义 Transport 的默认策略更谨慎。只要提供了非零的 Dial、DialTLS、DialContext 或 TLSClientConfig，HTTP/2 默认可能被关闭。这样做的原因是自定义连接建立过程可能没有完成 HTTP/2 所需的 TLS ALPN 协商，Transport 不会替调用方猜测连接能力。

最容易出现问题的写法，是从默认 Transport 复制了部分参数，却加入了自己的 DialContext 或 TLS 配置：

transport := &http.Transport{
    TLSClientConfig: &tls.Config{ // 自定义 TLS 后，HTTP/2 不再按默认路径自动尝试
        MinVersion: tls.VersionTLS13,
    },
    DialContext: (&net.Dialer{
        Timeout: 5 * time.Second, // 给自定义 TCP 拨号设置连接建立上限
    }).DialContext,
}

client := &http.Client{Transport: transport}
_ = client // 这里只展示配置边界，未在本地执行请求

这段配置不代表 TLS 一定失败，也不代表服务器不支持 HTTP/2；它只表示 Transport 不再能安全地沿用默认 HTTP/2 假设。问题的关键是“自定义连接路径是否仍然具备协议协商条件”，而不是简单地把 TLS 版本调高或调低。

先区分协议降级、服务端关闭和客户端主动关闭

“HTTP/2 被关闭”在日志里可能对应三种不同现象：

• 协议降级：请求仍然成功，但协商结果是 HTTP/1.1。此时要重点看 Transport 配置和 TLS ALPN，不要先把问题归为网络断开。
• 连接建立失败：自定义拨号、证书校验、代理或超时导致请求根本没有进入 HTTP/2 协商。
• 连接中途关闭：服务端、代理、客户端取消请求或响应体处理不完整，导致已经建立的连接被关闭。这和“HTTP/2 默认没启用”不是同一个问题。

因此，排查顺序应该先确认请求使用的协议，再看连接是否复用，最后才分析关闭原因。只看到一个 EOF 或“连接被关闭”日志，不能直接推导出是 HTTP/2 开关造成的。

保留自定义拨号时优先检查 ForceAttemptHTTP2

如果自定义的是普通 TCP 拨号或 TLS 配置，并且希望 Transport 继续尝试 HTTP/2，可以设置 ForceAttemptHTTP2: true。它表达的是“即使存在自定义拨号或 TLS 配置，也尝试进行 HTTP/2 升级”，并不等于强制服务器必须使用 HTTP/2。

transport := &http.Transport{
    ForceAttemptHTTP2: true, // 保留自定义拨号时，重新允许 HTTP/2 尝试
    TLSClientConfig: &tls.Config{
        MinVersion: tls.VersionTLS13, // 只示范 TLS 配置，不关闭证书校验
    },
    DialContext: (&net.Dialer{
        Timeout: 5 * time.Second, // 控制 TCP 建连等待时间
    }).DialContext,
}

client := &http.Client{Transport: transport}
req, err := http.NewRequest(http.MethodGet, "https://api.example.com/health", nil)
if err != nil {
    return err // 请求构造失败时不要进入网络层
}

resp, err := client.Do(req)
if err != nil {
    return err
}
defer resp.Body.Close() // 无论协议是什么，都要由调用方关闭响应体
_, err = io.Copy(io.Discard, resp.Body) // 读完 body，为连接复用留下完整边界
return err

ForceAttemptHTTP2 解决的是 Transport 的默认决策，不会替代 TLS 的 ALPN 协商，也不会覆盖服务端的协议能力。若服务端只接受 HTTP/1.1，结果仍可能是 HTTP/1.1；若自定义拨号返回的连接没有正确完成 TLS，设置这个字段也不能修复连接本身。

使用 Protocols 时要明确允许哪些协议

在较新的 Go 版本中，Transport 还可以通过 Protocols 表达支持的协议集合。需要同时允许 HTTP/1 和 HTTPS 上的 HTTP/2 时，可以显式设置这两个能力。这样做比只依赖隐式默认更容易审查，但要注意它改变的是协议能力声明，不会替你配置证书或完成 TLS。

transport := http.DefaultTransport.(*http.Transport).Clone()
transport.Protocols = new(http.Protocols)
transport.Protocols.SetHTTP1(true) // 保留普通 HTTP/1 请求和降级路径
transport.Protocols.SetHTTP2(true) // 明确允许 TLS 连接上的 HTTP/2

client := &http.Client{Transport: transport}
resp, err := client.Get("https://api.example.com/health")
if err != nil {
    return err
}
defer resp.Body.Close() // 读取响应前先登记关闭动作
_, err = io.Copy(io.Discard, resp.Body) // 完整消费响应，便于后续复用
return err

如果项目仍需兼容较旧的 Go 版本，应以该版本对应的 net/http 文档为准，不要把新版本的 Protocols API 直接复制到旧工具链。无论采用哪一种表达方式，都应把它和 Transport 的生命周期放在同一处配置，避免初始化函数之间互相覆盖。

自定义 DialTLSContext 时别破坏 ALPN

DialTLSContext 和 DialContext 的职责不同。前者返回的是已经完成 TLS 握手的连接，Transport 会忽略 TLSClientConfig 和 TLS 握手超时；为了让 HTTPS 连接支持 HTTP/2，返回的连接还应当支持 TLS 的协议协商状态。若在这里返回普通 TCP 连接，或者 TLS 配置没有包含合理的 ALPN 协商路径，HTTP/2 自然无法正常建立。

transport := &http.Transport{
    DialTLSContext: func(ctx context.Context, network, addr string) (net.Conn, error) {
        d := &net.Dialer{Timeout: 5 * time.Second} // 自定义连接建立超时
        rawConn, err := d.DialContext(ctx, network, addr)
        if err != nil {
            return nil, err // TCP 建连失败时直接返回，避免伪造 TLS 连接
        }

        tlsConn := tls.Client(rawConn, &tls.Config{
            ServerName: "api.example.com", // 生产环境应使用请求目标对应的名称
            NextProtos: []string{"h2", "http/1.1"}, // 声明 HTTP/2 与 HTTP/1.1 的 ALPN 能力
        })
        if err := tlsConn.HandshakeContext(ctx); err != nil {
            rawConn.Close() // 握手失败时回收底层连接，避免泄漏
            return nil, err
        }
        return tlsConn, nil // 返回已完成 TLS 的连接给 Transport
    },
    ForceAttemptHTTP2: true, // 明确允许自定义 TLS 拨号路径尝试 HTTP/2
}

_ = transport // 示例只说明 ALPN 与自定义拨号的边界

这段示例只强调配置关系，实际项目还要正确处理证书校验、代理、连接关闭和请求目标的 ServerName。不要为了“让 HTTP/2 生效”把 InsecureSkipVerify 打开；那会降低 TLS 身份校验强度，并没有解决协议协商的根因。

确认连接是否真的复用，而不是只看错误日志

协议选择和连接复用是两个层次。即使请求最终使用 HTTP/2，也不能保证每次都复用同一条连接；同样，某次连接没有复用也不等于 HTTP/2 被关闭。可以使用 httptrace.ClientTrace 记录请求拿到的连接状态，重点看 Reused、WasIdle 和 IdleTime。

trace := &httptrace.ClientTrace{
    GotConn: func(info httptrace.GotConnInfo) {
        log.Printf("reused=%t was_idle=%t idle_time=%s", info.Reused, info.WasIdle, info.IdleTime)
        // Reused=true 只说明连接被复用，不能单独证明协议版本。
    },
}

req = req.WithContext(httptrace.WithClientTrace(req.Context(), trace)) // 把观察点绑定到当前请求
resp, err := client.Do(req)
if err != nil {
    return err
}
defer resp.Body.Close() // trace 不改变响应体的关闭责任
_, err = io.Copy(io.Discard, resp.Body) // 读完响应，避免把资源问题误判成协议问题
return err

如果要记录最终协议，可在请求完成后查看 resp.Proto，把它和 GotConn 信息放在同一条请求日志中。这样可以区分“HTTP/1.1 正常返回”“HTTP/2 正常返回”和“连接建立阶段失败”，避免用一个连接关闭错误覆盖完整上下文。

发布前按这五项复查

1. 确认 Transport 生命周期：同一目标服务的请求是否共享同一个 Transport，而不是每次请求重新创建。
2. 枚举自定义入口：检查 Dial、DialContext、DialTLS、DialTLSContext 和 TLSClientConfig 是否改变了默认路径。
3. 明确协议意图：需要自定义拨号仍尝试 HTTP/2 时，评估 ForceAttemptHTTP2；需要清晰声明能力时，再配置 Protocols。
4. 保护 TLS 协商：自定义 TLS 拨号必须返回已完成握手、可提供 ALPN 状态的连接，并保持正常证书校验。
5. 完整处理响应：每次请求都关闭并按业务读取 Response.Body，再用 resp.Proto 与 httptrace 判断实际结果。

结论是：自定义 Transport 并不会“无条件关闭 HTTP/2”，但它会让 Go 放弃对自定义连接能力的默认猜测。把自定义拨号、TLS、协议能力、连接复用和响应体生命周期放在同一条排查链里，通常比单独增大超时或反复重试更快找到根因。

相关问题

设置 ForceAttemptHTTP2 后一定会使用 HTTP/2 吗？

不会。它只允许 Transport 在存在自定义拨号或 TLS 配置时继续尝试 HTTP/2，最终结果仍取决于 TLS ALPN、服务端能力、代理路径和协议集合。

只配置 TLSClientConfig，为什么请求还能成功但协议变成 HTTP/1.1？

这是可能的正常结果。TLSClientConfig 可能让 HTTP/2 不再按默认路径启用；如果 HTTP/1.1 仍被允许，协商失败后请求可以回退到 HTTP/1.1。应记录 resp.Proto，不要只根据请求成功与否判断协议。

自定义 DialTLSContext 时还需要设置 TLSClientConfig 吗？

该字段会被忽略，因为 DialTLSContext 返回的连接应已经完成 TLS 握手。此时应在自定义 TLS 连接中正确设置 ALPN、证书校验和服务名，并确认返回连接提供协议协商所需的信息。

Response.Body 没有关闭会直接关闭 HTTP/2 吗？

它首先是响应资源生命周期问题，不应直接等同于 HTTP/2 开关。未正确读取或关闭 body 可能影响连接复用，进而让后续请求表现出频繁建连或连接关闭；协议版本仍应通过请求级信息单独判断。