Go http.Server 怎么显式控制 HTTP 协议集合

从 Go 1.24 开始，net/http 为 http.Server 增加了 Protocols 字段。它不是一个“是否开启 HTTP/2”的单开关，而是一组可独立选择的协议：HTTP/1、TLS 上的 HTTP/2，以及明文 TCP 上的 HTTP/2。想把服务端支持范围写死在代码里，就先创建 http.Protocols，再把需要的成员设为 true。

最稳妥的做法是显式列出允许的协议，并让监听方式与协议成员匹配：HTTPS 使用 HTTP1 和/或 HTTP2；明文端口使用 HTTP1 和/或 UnencryptedHTTP2。

下面示例面向 Go 1.24 及以上版本。若项目还需要兼容更早的工具链，应先升级编译环境，不能直接引用这些字段和方法。

先分清三个协议成员

这里最容易混淆的是后两个成员。HTTP2 不是所有 HTTP/2 的总开关，它明确指向 TLS 上的 HTTP/2；明文端口要用 UnencryptedHTTP2。两者可以同时存在，但通常属于不同监听入口。

先把协议集合写成独立配置

如果服务有测试、预发和生产三套入口，建议把协议集合放进小函数，避免在不同 Server 初始化处遗漏开关。

package main

import "net/http"

func protocolSet(http1, http2TLS, http2Clear bool) *http.Protocols {
    p := new(http.Protocols)

    // HTTP/1 同时适用于明文与 TLS 监听。
    p.SetHTTP1(http1)

    // HTTP2 只表示 TLS 上的 HTTP/2。
    p.SetHTTP2(http2TLS)

    // UnencryptedHTTP2 表示明文 HTTP/2。
    p.SetUnencryptedHTTP2(http2Clear)
    return p
}

这个函数只组装静态配置，不负责启动服务。调用处仍要根据证书与端口选择 ListenAndServe 或 ListenAndServeTLS。

HTTPS 入口怎么选择 HTTP/1 和 HTTP/2

同时支持 HTTP/1 与 HTTP/2 时，把两个 TLS 相关成员都打开。TLS 握手阶段会通过 ALPN 在服务端允许的集合与客户端能力之间选择协议。

srv := &http.Server{
    Addr:      ":8443",
    Handler:   mux,
    Protocols: protocolSet(true, true, false),
}

// 同一个 HTTPS 端口允许 HTTP/1 和 HTTP/2。
if err := srv.ListenAndServeTLS("cert.pem", "key.pem"); err != nil {
    return err
}

只保留 HTTP/1 时改成 protocolSet(true, false, false)；只允许 TLS HTTP/2 时改成 protocolSet(false, true, false)。纯 HTTP/2 配置会拒绝不能协商 h2 的客户端，因此在切换前应确认反向代理、健康检查和内部 SDK 都支持 HTTP/2。

Protocols 决定“允许哪些协议”，而 Server.HTTP2 用于配置 HTTP/2 连接参数。两者职责不同：前者是集合，后者是协议细节，不能互相替代。

明文 HTTP/2 要使用 prior knowledge

明文 HTTP/2 常被简称为 h2c。Go 标准库这里支持的是 HTTP/2 with Prior Knowledge：客户端一开始就发送 HTTP/2 连接前言，而不是先发 HTTP/1.1 请求，再用 Upgrade: h2c 切换。Go 1.24 发布说明明确指出，已弃用的 Upgrade 方式不在这个能力范围内。

只允许明文 HTTP/2：

srv := &http.Server{
    Addr:      ":8080",
    Handler:   mux,
    Protocols: protocolSet(false, false, true),
}

// 客户端必须直接使用 HTTP/2 prior knowledge。
if err := srv.ListenAndServe(); err != nil {
    return err
}

同一个明文端口同时接受 HTTP/1 与 prior knowledge HTTP/2，则使用 protocolSet(true, false, true)。普通 HTTP/1 客户端仍走 HTTP/1；明确发送 HTTP/2 连接前言的客户端进入明文 HTTP/2。不要把 SetHTTP2(true) 当成 h2c 开关，它只服务 TLS 连接。

nil、空集合和旧开关有什么区别

如果 Server.Protocols 为 nil，官方文档把默认描述为“通常是 HTTP/1 与 HTTP/2”。不过历史兼容项会影响结果：例如非空且没有 h2 条目的 TLSNextProto 会让默认集合只保留 HTTP/1，GODEBUG=http2server=0 也可能关闭自动 HTTP/2。

一旦赋值显式集合，应用意图就更清楚，也不必依赖环境默认。仍要注意，不要用 new(http.Protocols) 的空集合表达“禁用全部”。当前服务端为了兼容历史行为，会把空集合解释成仅 HTTP/1。需要什么就明确调用对应的 Set... 方法；若服务不应监听，应该停止创建监听器，而不是构造一个空协议集。

用 Request.Proto 核对实际协议

协议集合正确不等于每个客户端都会选择最高版本。最小核对方式是在测试 Handler 中返回 r.Proto，然后分别使用受控客户端发起请求。

mux.HandleFunc("/proto", func(w http.ResponseWriter, r *http.Request) {
    // 返回本次请求实际使用的协议版本。
    _, _ = w.Write([]byte(r.Proto))
})

# 核对 HTTPS 上的 HTTP/1.1
curl --http1.1 https://localhost:8443/proto

# 核对 HTTPS 上的 HTTP/2
curl --http2 https://localhost:8443/proto

# 核对明文 HTTP/2 prior knowledge
curl --http2-prior-knowledge http://localhost:8080/proto

命令是否能使用 HTTP/2 还取决于本机 curl 的构建能力。上线前应同时检查直连、反向代理转发和健康检查三条路径；若代理终止 TLS，后端看到的协议可能与用户侧连接不同。

一份可执行的选择清单

• 只要传统明文 HTTP：启用 HTTP1，调用 ListenAndServe。
• 常规 HTTPS 兼容模式：启用 HTTP1 与 HTTP2，调用 ListenAndServeTLS。
• 只要 TLS HTTP/2：仅启用 HTTP2，先确认所有客户端和探针支持 h2。
• 只要明文 HTTP/2：仅启用 UnencryptedHTTP2，客户端使用 prior knowledge。
• 明文端口兼容两种协议：启用 HTTP1 与 UnencryptedHTTP2。
• 不要用 Upgrade: h2c 判断这项能力，也不要用空集合表达停服。

常见问题

设置 HTTP2 后还需要证书吗？

需要。SetHTTP2(true) 表示 TLS 上的 HTTP/2，应配合 ListenAndServeTLS。无证书的明文端口应使用 SetUnencryptedHTTP2(true)。

同时启用 HTTP1 和 UnencryptedHTTP2 会优先哪个？

服务端可以在同一明文端口接受两者；实际协议由客户端发送的连接内容决定。普通客户端通常使用 HTTP/1，只有明确使用 prior knowledge 的客户端才直接进入 HTTP/2。

为什么我设置了 HTTP2，Handler 里仍看到 HTTP/1.1？

常见原因是客户端没有请求 HTTP/2、TLS ALPN 没有协商到 h2，或请求经过了终止 TLS 的代理。应分别检查客户端能力、直连结果与代理到后端的协议。

哪里查看官方定义？

类型与方法文档见 https://pkg.go.dev/net/http，Go 1.24 的新增说明见 https://go.dev/doc/go1.24，服务端默认集合与兼容逻辑可在 https://go.dev/src/net/http/server.go 查看。

显式协议集合的价值不是“强制所有请求都升级”，而是把服务端接受范围从隐式默认变成可审查的代码。先按监听入口选对成员，再用独立客户端验证实际协议，迁移和回退都会更可控。