Go tls.Config怎样配置 ALPN 并选择协议怎样完成一个可复用的最小示例

我遇到过一个很容易误判的 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
}

没有选到协议时按这条时间线排查

1. 先查证书，再查 ALPN。证书加载错误、ServerName 不匹配和信任链错误会让握手提前失败，不能把它们当成“没有协议交集”。
2. 确认两端的 NextProtos。把客户端和服务端的实际配置打印到启动日志或测试断言中，重点看是否真的包含同一个字符串。
3. 确认连接使用了目标配置。如果通过包装器、连接池或 HTTP 客户端发起请求，要检查最终创建连接的那份 tls.Config，不要只看一个未被使用的模板变量。
4. 在握手完成后读取状态。从 ConnectionState().NegotiatedProtocol 读取结果；不要根据配置列表猜测结果。
5. 区分空结果与握手失败。如果双方都参与 ALPN 协商但没有共同协议，Go 的 TLS 连接会在握手阶段失败；只有 NextProtos 为空或对端没有使用 ALPN 时，握手成功后 NegotiatedProtocol 才可能是空字符串。

可复用的配置清单

回到开头那个“总是没有 h2”的问题，修复路径其实很短：把客户端和服务端的 NextProtos 放到同一份约定里，确保真正使用这份配置，再在握手后记录 NegotiatedProtocol。这样就能把“证书问题”“配置没有生效”和“双方没有交集”分开处理。

常见追问

NextProtos 的顺序一定决定服务端选择吗？

不能只靠顺序下结论。顺序可以表达一端的偏好，但最终选择由协议协商规则和具体实现共同决定，应该以握手后的 NegotiatedProtocol 为准。

只设置服务端 NextProtos 能让普通客户端自动使用 h2 吗？

不能。客户端也需要在自己的 TLS 配置中发布支持的候选；如果双方都启用了 ALPN 却没有共同候选，TLS 握手会失败，而不是静默得到一个协议。

ALPN 协商成功就代表 HTTP/2 请求一定能工作吗？

不代表。ALPN 只说明 TLS 层选择了协议，后续还需要对应的 HTTP/2 读写实现、请求格式和服务端处理链路。