Go net/http Protocols.SetUnencryptedHTTP2 怎样启用明文 HTTP/2

如果客户端和服务端都在受控网络里，想直接使用不带 TLS 的 HTTP/2，Go 1.24 起可以用 net/http.Protocols.SetUnencryptedHTTP2 声明协议集合。真正容易写错的地方不在方法名，而在于它要配置到 Transport.Protocols 或 Server.Protocols，以及是否同时保留 HTTP/1。

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

只想让客户端对 http:// 地址使用明文 HTTP/2 时，通常要打开 UnencryptedHTTP2 并关闭 HTTP1；服务端则在 Server.Protocols 中声明自己接受的协议。明文 HTTP/2 没有 TLS 加密和证书身份校验，适合受控链路，不等同于安全传输。

先把“明文 HTTP/2”与 HTTPS 分开

HTTP2 表示 TLS 连接上的 HTTP/2，UnencryptedHTTP2 表示未加密 TCP 连接上的 HTTP/2。两者都属于 http.Protocols 的协议集合，但配置含义完全不同。文章讨论的是后者，地址通常是 http://，不是 https://。

Protocols 的零值是空集合。通过 SetHTTP1、SetHTTP2 和 SetUnencryptedHTTP2 可以明确增删协议。这样写的好处是把“允许什么”放进配置对象，而不是依赖 Transport 或 Server 的默认推断。

客户端：Transport 里到底要打开什么

客户端配置的中心是 http.Transport，不是 http.Client 本身。先克隆一个 Transport，再创建 Protocols，最后把协议集合挂回 Transport。若希望明文 HTTP/2 成为 http:// 请求的唯一选择，就不要同时启用 HTTP/1。

package main

import (
	"fmt"
	"net/http"
)

func newH2CClient() *http.Client {
	// 克隆默认 Transport，保留连接复用等基础配置。
	transport := http.DefaultTransport.(*http.Transport).Clone()
	transport.Protocols = new(http.Protocols)

	// 关闭 HTTP/1，避免 http:// 请求优先落到 HTTP/1.1。
	transport.Protocols.SetHTTP1(false)
	// 只允许未加密 HTTP/2，服务端也必须接受同一种协议。
	transport.Protocols.SetUnencryptedHTTP2(true)

	return &http.Client{Transport: transport}
}

func main() {
	client := newH2CClient()
	// 示例只说明配置入口；真实地址应由受控服务端提供。
	request, err := http.NewRequest(http.MethodGet, "http://internal.example/health", nil)
	if err != nil {
		panic(err)
	}
	response, err := client.Do(request)
	if err != nil {
		panic(err)
	}
	defer response.Body.Close() // 及时释放响应体，避免连接无法复用。
	fmt.Println(response.Status)
}

这里的关键不是 SetUnencryptedHTTP2(true) 单独出现，而是它与 SetHTTP1(false) 的组合。若两者都为 true，Transport 可以同时支持两类协议，但对明文 URL 的选择会受协议集合和对端协商影响；若只保留明文 HTTP/2，配置意图更清楚。

服务端：Server 的协议集合怎么声明

服务端把同样的协议集合放到 http.Server.Protocols。Handler 负责业务路由，Protocols 负责连接层允许的协议，两者不要混在路由逻辑里。只启用明文 HTTP/2 时，服务端仍然使用普通监听入口，但连接必须来自支持该协议的客户端。

package main

import (
	"net/http"
)

func newH2CServer(handler http.Handler) *http.Server {
	server := &http.Server{
		Addr:    ":8080",
		Handler: handler,
	}
	server.Protocols = new(http.Protocols)

	// 关闭 HTTP/1，只在受控监听端口接收明文 HTTP/2。
	server.Protocols.SetHTTP1(false)
	// 允许未加密 HTTP/2；生产网络仍需另行规划加密与身份认证。
	server.Protocols.SetUnencryptedHTTP2(true)
	return server
}

如果要兼容旧客户端，可以同时设置 SetHTTP1(true) 和 SetUnencryptedHTTP2(true)。这代表“服务端接受两种协议”，不是“所有客户端都会自动升级”。协议兼容范围应由调用方、监听网络和部署边界共同决定。

按场景选择 HTTP/1 与明文 HTTP/2

可以把协议集合看成接口契约：客户端 Transport 决定自己愿意使用什么，服务端 Server 决定自己接受什么，双方交集为空时请求不会因为 Handler 写得正确就自动成功。

版本与安全边界要提前写进方案

Protocols 及其设置方法从 Go 1.24 起提供。项目如果仍需兼容更早工具链，应先确认版本策略，不要只把新方法复制进旧分支。标准库直接支持明文 HTTP/2 后，第三方 h2c 适配层的选择也可能改变，但迁移时仍要核对请求路径、代理、连接复用和对端实现。

更重要的是，明文 HTTP/2 只改变 HTTP 的承载协议，不替代 TLS。它不会给消息加密，也不会证明对端身份；在公网、跨租户或不可信网络上，应该使用 HTTPS 并按证书和身份体系设计。不要把“协议版本更高”写成“链路已经安全”。

常见问题

为什么打开了 UnencryptedHTTP2 仍然像 HTTP/1？先检查客户端是否仍启用了 HTTP/1、请求是否为 http://，再确认服务端也声明了明文 HTTP/2。两端配置不匹配时，单改一侧没有意义。

能不能只在 Server 上设置？可以让服务端具备接收能力，但客户端仍要选择能够发起明文 HTTP/2 的 Transport。服务端配置不会替调用方改变协议集合。

明文 HTTP/2 能替代 HTTPS 吗？不能。它适合受控链路或明确隔离的内部网络；需要保密、完整性和身份认证时，应回到 TLS。

技术依据：https://pkg.go.dev/net/http#Protocols、https://pkg.go.dev/net/http#Transport、https://pkg.go.dev/net/http#Server。本文只解释标准库协议配置关系，不提供未经测量的性能结论。