Go http.Protocols 怎么限定客户端使用的 HTTP 版本

如果客户端必须固定使用 HTTP/1，或者想明确允许 HTTP/1 与 HTTP/2，Go 1.24 及以上可以直接配置 http.Transport.Protocols。做法是复制默认 Transport，创建 http.Protocols，再用 SetHTTP1、SetHTTP2 勾选允许的协议；不要把 URL 改成某个版本就当成完成了限制。

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

客户端协议限制的关键是“允许集合”，不是一个字符串开关。只勾选 HTTP/1 就不会主动使用 HTTP/2；只勾选 HTTP/2 则要求目标连接满足 HTTP/2 的传输条件，最后还要用 Response.Proto 检查实际结果。

先把 Transport 和 Protocols 的职责分开

http.Client 负责请求入口、超时和重定向策略，真正建立连接的是 Transport，协议白名单也放在 Transport 上。下面的写法保留默认代理、连接池和 TLS 配置，再替换协议集合：

package main

import (
	"fmt"
	"net/http"
)

func newHTTP1Client() *http.Client {
	// Clone 保留默认 Transport 的代理、连接池和基础 TLS 行为。
	tr := http.DefaultTransport.(*http.Transport).Clone()
	tr.Protocols = new(http.Protocols)
	// 只允许 HTTP/1，HTTP/1.0 和 HTTP/1.1 都属于这一组。
	tr.Protocols.SetHTTP1(true)

	return &http.Client{Transport: tr}
}

func main() {
	client := newHTTP1Client()
	resp, err := client.Get("https://example.com")
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close() // 关闭响应体，允许连接按 Transport 策略复用。
	fmt.Println(resp.Proto)
}

这里的零值语义容易误读：new(http.Protocols) 创建的是空集合，必须显式打开至少一种协议。对默认 Transport 而言，直接把 Protocols 留为 nil 才会继续走默认判断；一旦自己创建集合，就应把允许项写完整。

只允许 HTTP/1，或同时开放 HTTP/1 与 HTTP/2

固定 HTTP/1 适合需要兼容旧代理、网关行为可预测，或正在排查 HTTP/2 特有问题的场景。若客户端可以接受两种协议，则把两个位都打开，TLS 连接上仍由客户端和服务端完成协商：

func newHTTP1Or2Client() *http.Client {
	tr := http.DefaultTransport.(*http.Transport).Clone()
	tr.Protocols = new(http.Protocols)
	// 两个开关组成允许集合，不代表每次请求都会同时使用两条连接。
	tr.Protocols.SetHTTP1(true)
	tr.Protocols.SetHTTP2(true)
	return &http.Client{Transport: tr}
}

如果只想禁止 HTTP/2，就不要依赖 ForceAttemptHTTP2 或环境变量的间接效果，直接只设置 SetHTTP1(true)。反过来，HTTP/2-only 的配置可以只设置 SetHTTP2(true)，但它不是“把 HTTP/1 请求头改成 HTTP/2”，而是要求目标连接能够以 TLS 上的 HTTP/2 建立。

明文 HTTP/2 不能和普通 http:// 混为一谈

SetHTTP2(true) 表示 TLS 上的 HTTP/2。若服务端提供的是未加密 HTTP/2（通常称 h2c），客户端还要显式加入 SetUnencryptedHTTP2(true)，并且不要误以为所有普通 http:// 地址都自动具备这个能力：

func newH2CClient() *http.Client {
	tr := http.DefaultTransport.(*http.Transport).Clone()
	tr.Protocols = new(http.Protocols)
	// 明文 HTTP/2 只适用于明确支持 h2c 的服务端。
	tr.Protocols.SetUnencryptedHTTP2(true)
	return &http.Client{Transport: tr}
}

生产环境通常优先使用 HTTPS 上的 HTTP/2，因为 TLS、证书和 ALPN 协商边界更清楚。若只开 UnencryptedHTTP2，又把请求发往只支持 HTTP/1 的明文服务，结果不是“自动退回 HTTP/1”，而是协议集合与服务端能力不匹配。需要兼容两者时，显式同时打开对应选项，并把降级是否允许写进配置说明。

用 Response.Proto 验证实际版本

协议配置只是客户端意图，服务端能力、代理和重定向链路仍会影响最终结果。每次排查先打印 resp.Proto，不要只看请求 URL：

func fetchAndCheck(client *http.Client, url string) error {
	resp, err := client.Get(url)
	if err != nil {
		return err
	}
	defer resp.Body.Close() // 读取协议版本后仍必须关闭响应体。

	fmt.Printf("status=%s protocol=%s\\n", resp.Status, resp.Proto)
	// 这里把“只接受 HTTP/1”作为调用方的最终断言。
	if resp.ProtoMajor != 1 {
		return fmt.Errorf("unexpected protocol: %s", resp.Proto)
	}
	return nil
}

如果看到 HTTP/1，先确认是否只开启了 HTTP1；如果期望 HTTP/2 却拿到错误，检查 URL 是否为 HTTPS、服务端是否支持 ALPN，以及是否在自定义 Dialer 或 TLS 配置后改变了 Transport 行为。还要留意重定向：客户端可能跟随到另一个主机，验证时应记录最终响应和重定向策略，而不是把第一个 URL 当成唯一证据。

一张配置清单记住边界

实际项目里我会把协议集合和验证日志放在同一个 Transport 构造函数旁边，这样升级 Go 或替换代理时不容易悄悄恢复默认协议。最后保留两个小检查：先读 Response.Proto，再确认 resp.Body 已关闭；前者验证协商结果，后者保护连接复用。

常见问题

只写 SetHTTP2(true) 能访问 http:// 地址吗？通常不能把它理解成普通明文 HTTP/2；TLS 上的 HTTP/2 与明文 h2c 是两条不同路径，需要按服务端能力选择。

为什么已经配置 Protocols，结果还是和预期不同？优先检查是否复用了另一个 Client/Transport、是否发生重定向，以及最终响应的 Proto。配置对象只对实际使用它的 Transport 生效。