HTTP/2 明文模式连接失败应检查哪些协议设置

Go 的 HTTP/2 明文模式连接失败时，我会先检查四件事：请求是否真的是 http://，客户端是否只启用了 UnencryptedHTTP2，服务端是否接受 UnencryptedHTTP2，双方是否都按 prior knowledge 而不是 Upgrade: h2c 工作。这里最反直觉的一点是，客户端把 HTTP1 和 UnencryptedHTTP2 同时打开，并不会自动“优先尝试 h2c”，而会对 http:// 使用 HTTP/1。

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

Go 1.24 发行说明：https://go.dev/doc/go1.24

我第一次把 h2c 当成普通 HTTP/2 选项时为什么失败

我最初的直觉是：只要给 http.Transport 调用 SetHTTP2(true)，再访问一个 http:// 地址，客户端就会使用 HTTP/2。这个理解把“协议版本”和“传输边界”混在了一起。Go 的 Protocols 把它们明确拆成了三项：HTTP1、TLS 连接上的 HTTP2，以及不安全 TCP 连接上的 UnencryptedHTTP2。

因此，明文 HTTP/2 不是把 HTTPS 地址去掉证书就完成了，也不是 SetHTTP2 的无 TLS 变体。客户端 URL、Transport 的协议集合、服务端的协议集合和中间网络设备必须描述同一种连接。

先把三种协议能力拆开

HTTP1 可用于明文 TCP 或 TLS；HTTP2 专指 TLS 上的 HTTP/2；UnencryptedHTTP2 专指明文 TCP 上的 HTTP/2。排障时先看配置名称，而不是只看日志里的“HTTP/2”三个字，通常能很快发现设置对象错了。

客户端最容易踩的坑是同时打开 HTTP/1

Go 1.24 的官方发行说明写得很直接：当 Transport.Protocols 包含 UnencryptedHTTP2 且不包含 HTTP1 时，Transport 才会对 http:// URL 使用明文 HTTP/2；如果两者同时配置，则使用 HTTP/1。这个选择是配置语义，不是网络质量差导致的降级。

package main

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

func main() {
    tr := &http.Transport{
        // 排障时先绕开环境代理，确认客户端能直连目标服务
        Proxy: nil,
        Protocols: new(http.Protocols),
    }
    // 客户端只启用明文 HTTP/2，不能同时启用 HTTP1
    tr.Protocols.SetUnencryptedHTTP2(true)

    client := &http.Client{Transport: tr}
    resp, err := client.Get("http://127.0.0.1:8080/")
    if err != nil {
        log.Fatal(err)
    }
    defer resp.Body.Close()

    body, err := io.ReadAll(resp.Body)
    if err != nil {
        log.Fatal(err)
    }
    // resp.Proto 应为 HTTP/2.0；正文不把该示例声称为本机实测
    fmt.Printf("protocol=%s body=%s\n", resp.Proto, body)
}

如果这里再加一行 tr.Protocols.SetHTTP1(true)，对 http:// 的选择就会变成 HTTP/1。另一个常见误区是只设置 ForceAttemptHTTP2：这个字段主要处理自定义 Dial、DialTLS、DialContext 或 TLS 配置下是否继续尝试 HTTP/2，它不是 h2c 的开关，不能替代 SetUnencryptedHTTP2(true)。

客户端和服务端的协议集合必须匹配

服务端与客户端的取舍不完全对称。客户端需要一个明确结果，所以只启用 UnencryptedHTTP2；服务端则可以同时接受 HTTP/1 和明文 HTTP/2，让旧客户端与 h2c 客户端共用同一监听端口。Go 官方文档明确说明了这种同端口能力。

package main

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

func main() {
    mux := http.NewServeMux()
    mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
        // 返回服务端实际识别到的请求协议
        fmt.Fprintf(w, "server protocol: %s", r.Proto)
    })

    srv := &http.Server{
        Addr: ":8080",
        Handler: mux,
        Protocols: new(http.Protocols),
    }
    // 服务端可同时兼容普通 HTTP/1 客户端
    srv.Protocols.SetHTTP1(true)
    // 明确允许 prior-knowledge 形式的明文 HTTP/2
    srv.Protocols.SetUnencryptedHTTP2(true)

    log.Fatal(srv.ListenAndServe())
}

这两个示例要求 Go 1.24 或更高版本，因为 Protocols 与 SetUnencryptedHTTP2 从 Go 1.24 加入。若编译时报字段或方法不存在，先检查 go version 和构建环境实际使用的工具链，不要继续在网络层追查。

prior knowledge 与 Upgrade h2c 不是同一条路径

Go 1.24 标准库的明文 HTTP/2 使用 RFC 9113 所描述的“HTTP/2 with Prior Knowledge”：客户端从连接开始就按 HTTP/2 发送，不先发一段 HTTP/1.1 请求。已弃用的 Upgrade: h2c 头部路径不受这里支持。

这会带来一个很实用的判断：如果网关、代理或服务端只认识“先 HTTP/1.1、再 Upgrade”的 h2c，而 Go 客户端直接发送 HTTP/2 连接前言，双方即使都把自己称为支持 h2c，也仍然无法互通。反过来，把一个 prior-knowledge 客户端连到普通 HTTP/1 监听器，也不会自动变成 HTTP/1。

旧项目可能使用 golang.org/x/net/http2/h2c 的 NewHandler。当前官方包文档已经把该包标记为弃用，并建议改用 http.Server.Protocols。新代码优先使用标准库；迁移旧代码时则要把客户端、服务端和中间层一起核对，不能只替换服务器的一行包装器。

四个反例最容易把排查带偏

只设置 SetHTTP2(true)

这启用的是 TLS 上的 HTTP/2。目标是 http:// 时，应检查 SetUnencryptedHTTP2(true)，而不是继续调 ALPN 或证书。

客户端同时启用 HTTP1 与 UnencryptedHTTP2

这不是“支持两种、自动挑更快的一种”。按 Go 的配置规则，http:// 会使用 HTTP/1。如果目标是强制 h2c，就只启用 UnencryptedHTTP2。

服务端只配置了默认 ListenAndServe

默认配置并不等于“自动接受明文 HTTP/2”。应创建 http.Server，设置非空 Protocols，并显式加入 UnencryptedHTTP2。

直连成功，经过代理却失败

此时问题通常已经离开 Go 进程本身。代理可能终止下游 HTTP/2，却用 HTTP/1 连接上游；也可能根本不接受 prior-knowledge h2c。先用 Proxy: nil 隔离直连，再逐层核对负载均衡器、服务网格和反向代理的下游协议与上游协议，不要把所有组件都概括成“支持 HTTP/2”。

采用 h2c 的后果不只是少一张证书

明文 HTTP/2 没有 TLS 提供的加密、服务器身份认证和传输完整性保护。它更适合受控内网、同机进程、TLS 已在可信入口终止且内部威胁模型允许明文的架构。只因为配置简单就把 h2c 暴露到不可信网络，会把性能协议选择误当成安全设计。

另一方面，h2c 采用 prior knowledge 后，客户端无法把“先试 HTTP/2，失败再自动退回 HTTP/1”当作默认容错。这个明确性有利于排障，却要求部署拓扑里的每一跳都知道自己面对的协议。如果环境里有大量不透明中间层，TLS HTTP/2 往往更容易借助现有 ALPN 和代理能力完成协商。

连接失败时按这个顺序检查

1. 确认 Go 工具链至少为 1.24，代码实际引用标准库 net/http 的 Protocols。
2. 确认请求 URL 是 http://；如果是 https://，应检查 TLS HTTP/2 与 ALPN。
3. 确认客户端设置了 SetUnencryptedHTTP2(true)，且没有同时设置 SetHTTP1(true)。
4. 确认服务端 Server.Protocols 包含 UnencryptedHTTP2，并使用 ListenAndServe 监听明文端口。
5. 确认双方都使用 prior knowledge，不依赖 Upgrade: h2c。
6. 先直连服务端；直连成功后，再逐层加入代理、网关和服务网格。
7. 检查响应的 resp.Proto 或服务端收到的 r.Proto，用协议字段判断结果，不只看“请求成功”。

常见问题

SetHTTP2(true) 能开启 h2c 吗？

不能。它表示 TLS 上的 HTTP/2。明文 HTTP/2 要使用 SetUnencryptedHTTP2(true)。

客户端为什么不能同时启用 HTTP1 和 UnencryptedHTTP2？

可以同时启用，但对 http:// URL，Go 会选择 HTTP/1。如果目标是强制 h2c，就只启用 UnencryptedHTTP2。

服务端能同时兼容 HTTP/1 和 h2c 吗？

能。Server.Protocols 可以同时包含 HTTP1 与 UnencryptedHTTP2，两者使用同一个地址和端口。

还需要 golang.org/x/net/http2/h2c 吗？

Go 1.24+ 的新代码通常不需要。官方已经将该 h2c 包标记为弃用，并建议使用标准库的 Server.Protocols 与 Transport.Protocols。

h2c 适合直接暴露到公网吗？

通常不适合。h2c 不提供 TLS 的加密和身份认证，应只在明确的受控网络边界与威胁模型下使用；公网服务优先考虑 HTTPS 上的 HTTP/2。

这类故障的核心不是“HTTP/2 开关有没有打开”，而是客户端、服务端和每个中间层是否对同一种传输模式达成一致。把 HTTP2 与 UnencryptedHTTP2 分开看，把 prior knowledge 与 Upgrade 分开看，再检查客户端不能同时保留 HTTP1 的特殊规则，绝大多数 Go h2c 连接问题都会落到一个可解释的配置边界上。