我遇到过一个很容易误判的 TLS 问题：服务端的证书正常，TCP 也能连上，但业务日志里的协商协议始终不是预期的 h2。继续检查后发现，问题不在证书，而在两端没有通过 ALPN 发布并选择同一个协议。
在 Go 中，ALPN 的入口就是 tls.Config.NextProtos。客户端把它当作候选协议列表带进握手，服务端从双方的交集中选出一个结果；握手完成后，可以从 ConnectionState().NegotiatedProtocol 读取最终选择。
官方文档：https://pkg.go.dev/crypto/tls
先看清 ALPN 到底选择了什么
ALPN 不是“服务端强制打开 HTTP/2”的开关，而是一段发生在 TLS 握手期间的协议协商。客户端先发送自己愿意使用的协议，例如 h2 和 http/1.1；服务端检查自己的 NextProtos，从交集里选择一个并返回。
因此排查时要先问三个问题：客户端是否携带候选，服务端是否配置候选，双方候选是否存在交集。只在服务端写了 NextProtos: []string{"h2"}，并不能保证所有客户端都会得到 h2。
在 tls.Config 中配置可交集的候选
最小配置先把协议列表写清楚。下面的列表表示服务端愿意协商 h2 和 http/1.1，客户端也要至少发布其中一个。列表不是业务路由表，名称必须使用协议约定的 ALPN 标识。
package main
import "crypto/tls"
func serverTLSConfig(certFile, keyFile string) (*tls.Config, error) {
// 加载证书和私钥；真实项目中应让密钥文件由部署系统安全提供。
cert, err := tls.LoadX509KeyPair(certFile, keyFile)
if err != nil {
return nil, err
}
return &tls.Config{
// 发布服务端愿意接受的协议，客户端也需要提供其中的候选。
NextProtos: []string{"h2", "http/1.1"},
Certificates: []tls.Certificate{cert},
MinVersion: tls.VersionTLS12,
}, nil
}
这里最重要的不是列表顺序本身，而是两端必须有交集。把列表集中在一个构造函数中，还能避免普通连接和测试连接各自复制一份配置后逐渐漂移。
用最小客户端确认最终选择
配置完成后，不要只看“握手成功”。握手成功只能说明 TLS 层建立了连接，真正的 ALPN 结果要看连接状态。下面的客户端主动发布两个候选，并在握手后打印服务端选择的协议。
package main
import (
"crypto/tls"
"fmt"
)
func dialAndReport(addr, serverName string) error {
conn, err := tls.Dial("tcp", addr, &tls.Config{
// 客户端把候选协议带入 ClientHello，顺序表达客户端偏好。
NextProtos: []string{"h2", "http/1.1"},
ServerName: serverName,
})
if err != nil {
return err
}
defer conn.Close() // 读取状态后关闭连接，避免示例遗留资源。
state := conn.ConnectionState()
fmt.Printf("negotiated protocol: %q\\n", state.NegotiatedProtocol)
return nil
}
如果输出是 h2，说明双方的 ALPN 候选发生了交集并完成选择；如果输出是 http/1.1，通常表示服务端或客户端最终只保留了这个候选。若没有协商协议，空字符串本身就是一个有用的诊断信号。
把服务端监听、握手和结果记录连起来
工程代码里常见的误区是只给监听器套上 TLS，却没有在握手后记录结果。下面的服务端片段用 tls.NewListener 接收连接，并在第一次读写前显式完成握手，便于把协议结果记入日志。
package main
import (
"crypto/tls"
"fmt"
"net"
)
func acceptOnce(addr string, cfg *tls.Config) error {
ln, err := tls.Listen("tcp", addr, cfg)
if err != nil {
return err
}
defer ln.Close() // 示例只接受一次连接，生产服务应交给生命周期管理。
conn, err := ln.Accept()
if err != nil {
return err
}
defer conn.Close() // 无论握手是否成功，都要释放连接。
tlsConn, ok := conn.(*tls.Conn)
if !ok {
return fmt.Errorf("unexpected connection type %T", conn)
}
if err := tlsConn.Handshake(); err != nil {
return fmt.Errorf("TLS handshake failed: %w", err)
}
// 握手结束后读取最终协议，日志才能反映真实协商结果。
state := tlsConn.ConnectionState()
fmt.Printf("peer=%s protocol=%q\\n", conn.RemoteAddr(), state.NegotiatedProtocol)
return nil
}
没有选到协议时按这条时间线排查
- 先查证书，再查 ALPN。证书加载错误、ServerName 不匹配和信任链错误会让握手提前失败，不能把它们当成“没有协议交集”。
- 确认两端的 NextProtos。把客户端和服务端的实际配置打印到启动日志或测试断言中，重点看是否真的包含同一个字符串。
- 确认连接使用了目标配置。如果通过包装器、连接池或 HTTP 客户端发起请求，要检查最终创建连接的那份
tls.Config，不要只看一个未被使用的模板变量。 - 在握手完成后读取状态。从
ConnectionState().NegotiatedProtocol读取结果；不要根据配置列表猜测结果。 - 区分空结果与握手失败。如果双方都参与 ALPN 协商但没有共同协议，Go 的 TLS 连接会在握手阶段失败；只有
NextProtos为空或对端没有使用 ALPN 时，握手成功后NegotiatedProtocol才可能是空字符串。
可复用的配置清单
| 检查点 | 应当看到的结果 | 常见误区 |
|---|---|---|
| 协议命名 | 使用标准 ALPN 标识，如 h2、http/1.1 | 把业务路由名当作协议名 |
| 候选交集 | 客户端和服务端至少有一个相同候选 | 只配置服务端，忽略客户端 |
| 配置复用 | 集中构造并传给真正创建连接的调用方 | 复制配置后修改了另一份 |
| 结果确认 | 握手后读取 NegotiatedProtocol | 只用握手成功代替协议确认 |
| 生命周期 | 关闭 listener 和 connection，记录握手错误 | 示例代码忘记释放资源 |
回到开头那个“总是没有 h2”的问题，修复路径其实很短：把客户端和服务端的 NextProtos 放到同一份约定里，确保真正使用这份配置，再在握手后记录 NegotiatedProtocol。这样就能把“证书问题”“配置没有生效”和“双方没有交集”分开处理。
常见追问
NextProtos 的顺序一定决定服务端选择吗？
不能只靠顺序下结论。顺序可以表达一端的偏好，但最终选择由协议协商规则和具体实现共同决定，应该以握手后的 NegotiatedProtocol 为准。
只设置服务端 NextProtos 能让普通客户端自动使用 h2 吗？
不能。客户端也需要在自己的 TLS 配置中发布支持的候选；如果双方都启用了 ALPN 却没有共同候选，TLS 握手会失败，而不是静默得到一个协议。
ALPN 协商成功就代表 HTTP/2 请求一定能工作吗？
不代表。ALPN 只说明 TLS 层选择了协议，后续还需要对应的 HTTP/2 读写实现、请求格式和服务端处理链路。
