Go HTTP Server 如何只启用 HTTP/1 与 HTTP/2

在 Go 1.24 及以上版本中，要让 http.Server 只接受 HTTP/1 与 TLS 上的 HTTP/2，可以创建一个 http.Protocols，显式打开 HTTP1 和 HTTP2，再赋给 Server.Protocols。不要调用 SetUnencryptedHTTP2(true)，这样就不会开启明文 HTTP/2。

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

protocols := new(http.Protocols)
protocols.SetHTTP1(true) // 允许 HTTP/1.0 与 HTTP/1.1
protocols.SetHTTP2(true) // 允许 TLS 连接上的 HTTP/2

srv := &http.Server{
    Addr:      ":8443",
    Protocols: protocols, // 未启用 UnencryptedHTTP2
}

上面这段就是最小配置。它比依赖默认值更清楚，也比通过修改 TLSNextProto 间接关闭 HTTP/2 更适合表达“允许哪些协议”。

旧写法的问题不在功能，而在配置意图不够直观

在 Server.Protocols 出现之前，服务端通常依赖 net/http 的默认协商行为：HTTPS 自动支持 HTTP/2，需要禁用时再利用 TLSNextProto 或环境开关做特殊处理。这些方式仍有兼容意义，但它们表达的是“改写默认行为”，读代码时不容易立即看出最终允许的协议集合。

Go 1.24 引入 Protocols 后，配置可以从“如何关闭某个默认能力”变成“明确声明允许 HTTP/1 与 HTTP/2”。对生产服务而言，这会让代码审查、配置排查和升级回归都更直接。

三个开关分别控制什么

http.Protocols 的零值是空集合，但在 http.Server 的兼容逻辑中，不建议依赖空集合推断实际服务行为。最稳妥的做法是把需要的协议逐个打开。

这里最容易混淆的是后两个开关：HTTP2 指 TLS 上的 HTTP/2；UnencryptedHTTP2 才是明文连接上的 HTTP/2。Go 的明文 HTTP/2 支持采用 Prior Knowledge，不支持旧式 Upgrade: h2c 升级头。

完整服务代码：只接受 HTTP/1 与 TLS HTTP/2

下面的服务把实际请求协议写入响应，方便客户端检查协商结果。代码还设置了基本超时，并对正常关停错误单独处理。

package main

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

func main() {
    mux := http.NewServeMux()
    mux.HandleFunc("/protocol", func(w http.ResponseWriter, r *http.Request) {
        // r.Proto 反映当前请求实际使用的协议版本
        w.Header().Set("Content-Type", "text/plain; charset=utf-8")
        _, _ = fmt.Fprintf(w, "protocol=%s\n", r.Proto)
    })

    protocols := new(http.Protocols)
    protocols.SetHTTP1(true) // 同时允许 HTTP/1.0 与 HTTP/1.1
    protocols.SetHTTP2(true) // 仅允许 TLS 上的 HTTP/2
    // 不设置 UnencryptedHTTP2，避免开放明文 HTTP/2

    srv := &http.Server{
        Addr:              ":8443",
        Handler:           mux,
        Protocols:         protocols,
        ReadHeaderTimeout: 5 * time.Second,  // 限制请求头读取时间
        IdleTimeout:       60 * time.Second, // 控制空闲连接占用
    }

    // cert.pem 与 key.pem 应替换为部署环境中的 TLS 证书文件
    err := srv.ListenAndServeTLS("cert.pem", "key.pem")
    if err != nil && !errors.Is(err, http.ErrServerClosed) {
        log.Fatal(err)
    }
}

这段代码没有为 UnencryptedHTTP2 设置 true，因此协议集合只包含 HTTP/1 和加密 HTTP/2。ListenAndServeTLS 会建立 TLS 监听，支持 HTTP/2 的客户端可通过 ALPN 协商 h2，否则可回落到 HTTP/1.1。

分别约束客户端，检查实际协议

服务启动后，可以让客户端分别限定 HTTP/1.1 与 HTTP/2。响应中的 r.Proto 是应用层可读取的实际请求协议，不要只根据客户端命令行选项猜测结果。

# 强制使用 HTTP/1.1，预期响应包含 protocol=HTTP/1.1
curl --http1.1 --insecure https://localhost:8443/protocol

# 强制使用 HTTP/2，预期响应包含 protocol=HTTP/2.0
curl --http2 --insecure https://localhost:8443/protocol

--insecure 只适合本地使用自签名证书的演示环境。生产环境应使用受信任证书，并去掉该参数。如果本机的 curl 没有编译 HTTP/2 支持，第二条命令会在客户端侧失败，这不代表 Go Server 的配置无效。

兼容边界与常见误区

Go 1.24 之前没有 Server.Protocols

http.Protocols、Server.Protocols 以及对应的设置方法从 Go 1.24 开始提供。旧版本需要继续使用当时的 net/http 默认行为或 TLSNextProto 等兼容方式，不能直接复制本文字段。

HTTP/2 不等于明文 h2c

只调用 SetHTTP2(true)，表示允许 TLS 上的 HTTP/2。若业务确实需要明文 HTTP/2 Prior Knowledge，必须额外调用 SetUnencryptedHTTP2(true)。本文的目标是排除它，所以不打开该开关。

反向代理可能改变你看到的协议

如果 Go Server 位于 Nginx、Envoy、云负载均衡或网关之后，浏览器到代理可以是 HTTP/2，而代理到 Go 服务仍可能是 HTTP/1.1。此时 r.Proto 反映的是代理到 Go Server 这一跳，不代表终端用户到代理的协议。

不要同时保留互相冲突的旧配置

迁移到 Server.Protocols 后，应检查是否还存在用于禁用 HTTP/2 的 TLSNextProto 自定义值、GODEBUG=http2server=0 或外部代理限制。显式协议集合解决的是 Go Server 自身的允许范围，外部配置仍可能让 HTTP/2 无法协商。

采用建议

新项目或已升级到 Go 1.24 以上的服务，建议把协议集合写进 http.Server 配置：启用 HTTP1 与 HTTP2，仅在确实需要明文 HTTP/2 时再单独启用 UnencryptedHTTP2。部署后分别用限定 HTTP/1.1 和 HTTP/2 的客户端请求，并在服务端读取 r.Proto，就能把“配置意图”和“实际协商结果”对应起来。

相关问题

只启用 HTTP/2，可以不启用 HTTP/1 吗？

可以，只调用 SetHTTP2(true) 即可，但不支持 HTTP/2 的客户端将无法回落。生产环境是否这样做，应根据客户端覆盖范围决定。

HTTP1 是否只代表 HTTP/1.1？

不是。Go 文档把 HTTP1 定义为 HTTP/1.0 与 HTTP/1.1 两种协议。

为什么开启 HTTP2 后仍看到 HTTP/1.1？

常见原因包括客户端未请求 HTTP/2、curl 未编译 HTTP/2、TLS ALPN 没有协商到 h2、前置代理回源使用 HTTP/1.1，或旧环境配置关闭了 HTTP/2。应按连接的每一跳分别检查。