Go http.Server.Protocols 怎么只启用 HTTP/2

要让 Go 服务只接受 TLS 上的 HTTP/2，关键不是设置一个字符串，而是给 http.Server.Protocols 传入一个只打开 HTTP/2 的协议集合：创建 http.Protocols 后调用 SetHTTP2(true)，不要调用 SetHTTP1(true)，然后使用 ServeTLS 或等价的 TLS Listener。这个 API 从 Go 1.24 开始提供。

官方文档：https://pkg.go.dev/net/http

一、先确认 Protocols 的启用语义

http.Protocols 是一个协议集合，提供 HTTP1()、HTTP2() 和 UnencryptedHTTP2() 查询方法，以及对应的 Set... 修改方法。对 Server 来说，最容易误判的是“零值为空集合”和“空集合实际只保留 HTTP/1”的差别。

如果 Server.Protocols 仍为 nil，标准库为了兼容旧代码通常把 HTTP/1 和 TLS 上的 HTTP/2 都放进默认集合。若把它指向一个没有任何位的 Protocols，Server 的兼容逻辑会把它当作只启用 HTTP/1；因此空集合不是“拒绝所有协议”，也不是“自动启用 HTTP/2”。

所以“只启用 HTTP/2”的判断标准很明确：配置对象非空、HTTP2() 返回 true、HTTP1() 返回 false，并让 TLS 层保留 h2 协商项。

二、用 SetHTTP2 配置 TLS 服务

下面的最小服务没有设置 HTTP/1 位，只把 HTTP/2 放进集合。示例使用 Go 1.24 及以上版本，并假定证书文件已经准备好：

package main

import (
	"fmt"
	"log"
	"net/http"
)

func main() {
	server := &http.Server{
		Addr: ":8443",
		Handler: http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
			// 用响应头保留本次请求实际协商出的协议，便于联调确认。
			w.Header().Set("X-Request-Protocol", r.Proto)
			fmt.Fprintf(w, "protocol=%s\n", r.Proto)
		}),
	}

	protocols := new(http.Protocols)
	protocols.SetHTTP2(true) // 只加入 TLS 上的 HTTP/2，不加入 HTTP/1。
	server.Protocols = protocols

	// ServeTLS 负责 TLS 握手，标准库会按协议集合调整 ALPN 的 h2 项。
	log.Fatal(server.ListenAndServeTLS("server.crt", "server.key"))
}

这里的关键是 new(http.Protocols) 与 SetHTTP2(true) 的组合。不要再调用 SetHTTP1(true)，否则集合就变成 HTTP/1 + HTTP/2。Handler 中的 r.Proto 只用于回归时观察请求，不能用它替代服务端协议配置。

三、检查 TLS 与 ALPN 边界

SetHTTP2(true) 打开的是 TLS 上的 HTTP/2，不会把普通 TCP 监听器自动变成 h2c。官方实现对 HTTP/2 的启用条件包含 TLS 连接和 NextProtos 中的 h2；因此用 ListenAndServe 启动明文端口，不能证明这段配置已经生效。

如果业务确实需要明文 HTTP/2，需要显式加入 UnencryptedHTTP2，并确认客户端也使用相应的 h2c 连接方式。但这已经不是“只启用 TLS HTTP/2”的同一配置，不能为了让内网测试通过而把两者混写。

protocols := new(http.Protocols)
protocols.SetHTTP2(true) // HTTPS 场景：只允许 HTTP/2。
// protocols.SetUnencryptedHTTP2(true) // 只有明确需要 h2c 时才打开。
server.Protocols = protocols

还要留意自定义 TLSConfig.NextProtos、旧式 TLSNextProto 和代理层的协商行为。若代理在入口终止 TLS，再以 HTTP/1 转发到 Go 服务，Go 服务看到的就是代理到后端的协议；这时需要把“客户端到代理”和“代理到 Go”拆开验证。

四、用请求协议和失败路径回归

发布前至少做三项检查：第一，确认编译器版本支持 http.Protocols；第二，确认客户端通过 HTTPS 发起并支持 HTTP/2；第三，在 Handler 日志或响应头中看到 HTTP/2.0。不要只看服务启动成功，因为 TLS 服务即使协商不到 h2 也可能仍能建立连接。

# 先确认编译环境能识别 Go 1.24 的 Protocols API。
go version

# 用支持 HTTP/2 的 curl 通过 TLS 发起请求，-k 仅用于本地自签证书测试。
curl --http2 -k -i https://127.0.0.1:8443/

回归时重点观察两处：响应体中的 protocol=HTTP/2.0 与响应头中的 X-Request-Protocol: HTTP/2.0。如果客户端只会 HTTP/1，服务端不会因为设置了 HTTP/2 就把它自动升级成 HTTP/2；应把客户端能力、证书和 ALPN 逐项排查。

五、整理上线前的配置清单

迁移旧服务时，先检查是否依赖 nil 的默认行为，再决定是否显式配置。若目标是只启用 HTTP/2，最小改动就是保留 TLS 证书和 Handler，只新增一个协议集合，并用真实 HTTP/2 客户端验证协商结果。

相关问题

把 Protocols 设成空值会禁用 HTTP/1 和 HTTP/2 吗？

不会。对 Server 而言，显式传入空集合时，兼容逻辑会回退到仅 HTTP/1；想只启用 HTTP/2，应调用 SetHTTP2(true)。

只设置 SetHTTP2(true) 能直接支持明文 h2c 吗？

不能。HTTP2 表示 TLS 上的 HTTP/2，明文协议需要另外设置 UnencryptedHTTP2，且客户端和网络入口都要支持 h2c。