Go TLS 握手因 ALPN 不匹配失败的定位方案

如果 Go TLS 连接已经通过 DNS 和 TCP，却在握手阶段出现 no_application_protocol、tls: client requested unsupported application protocols 一类错误，优先检查客户端与服务端的 tls.Config.NextProtos。ALPN 要求双方至少有一个完全相同的协议标识；大小写、斜杠和版本字符都属于标识内容，不能靠“意思相近”匹配。

定位时不要先改证书或降低 TLS 版本。最短路径是：确认错误阶段，打印双方 NextProtos，求交集，修正标识与服务端偏好顺序，最后从 ConnectionState.NegotiatedProtocol 读取实际结果。空列表与无交集是两种不同状态，处理方式也不同。

确认故障发生在 ALPN 选择阶段

一次线上联调里，客户端固定提议 grpc-exp，服务端模板却配置为 grpc-prod。TCP 三次握手成功、证书也有效，但应用层始终收不到第一帧。真正的失败点位于 TLS ClientHello 与 ServerHello 之间：服务端看到客户端的 ALPN 列表后找不到共同协议，发送致命的 no_application_protocol 告警。

ALPN 在 TLS 握手内协商应用层协议。客户端通过 ClientHello 发送支持列表，服务端从共同协议中选择一个。如果双方都提供列表却没有交集，RFC 7301 要求服务端用致命的 no_application_protocol 告警终止握手。Go 的服务端握手实现也在 ALPN 选择失败时发送该告警。

先按层次排除干扰项：

并排打印双方 NextProtos

排查时只看客户端配置不够。服务端列表代表它支持的协议及偏好顺序，客户端列表代表它愿意使用的协议。协议字符串必须逐字节相等，例如 h2 与 http/2 不是同一个 ALPN 标识，http/1.1 也不能简写成 http1。

clientConfig := &tls.Config{
    ServerName: "api.example.test",
    // 客户端按自身偏好发送 ALPN 提议列表
    NextProtos: []string{"h2", "http/1.1"},
}

serverConfig := &tls.Config{
    Certificates: []tls.Certificate{serverCert},
    // 服务端列表既声明支持范围，也表达选择偏好
    NextProtos: []string{"h2", "http/1.1"},
}

log.Printf("client ALPN=%q", clientConfig.NextProtos)
log.Printf("server ALPN=%q", serverConfig.NextProtos)

日志要记录列表而不是只记录数量，同时避免把证书私钥、会话票据或其他敏感数据写入日志。对于配置中心下发的值，还应检查空格、大小写、逗号拆分和环境覆盖。"h2 " 与 "h2" 同样不会匹配。

理解未配置与无交集的差别

Go 的 tls.Config.NextProtos 文档区分了两种情况：如果两端都支持 ALPN，选择值必须来自共同协议，无共同值时连接失败；如果本端列表为空，或者对端不支持 ALPN，普通 TLS 连接可以成功，但 NegotiatedProtocol 为空。这意味着“握手成功”不等于“已经选出应用协议”。

诊断时可以把状态归为三类：

• 双方列表都有值且存在交集：握手应选出一个共同协议。
• 一方没有配置 ALPN：普通 TLS 可能成功，协商结果为空，应用必须有明确的无 ALPN 策略。
• 双方列表都有值但没有交集：典型结果是握手失败并返回 no_application_protocol。

Go 服务端实现对 h2 服务端与仅提议 http/1.1 的客户端保留了一个兼容性特殊处理，可能让连接以空协商结果继续。这不是通用回退规则，也不应拿来掩盖配置差异。QUIC 的 ALPN 要求更严格，不能照搬普通 TCP 上的空值策略。

修正配置并验证选择结果

修复不是简单地给两边追加大量字符串，而是明确服务实际能处理哪些协议。双方至少共享一个标识，服务端按自己的列表顺序选择共同协议中优先级最高的项。上层处理器也必须与选择结果一致，不能协商出 h2 后仍把字节交给 HTTP/1.1 解析器。

conn, err := tls.Dial("tcp", addr, clientConfig)
if err != nil {
    // 握手错误保留原始错误链，便于识别 ALPN 告警
    return fmt.Errorf("TLS 握手失败: %w", err)
}
defer conn.Close() // 无论后续路由是否成功都释放连接

state := conn.ConnectionState()
switch state.NegotiatedProtocol {
case "h2":
    // 只把 h2 连接交给 HTTP/2 处理器
    return serveHTTP2(conn)
case "http/1.1":
    // 明确处理 HTTP/1.1 协商结果
    return serveHTTP11(conn)
case "":
    // 空值必须符合产品约定，不能静默猜测协议
    return errors.New("TLS 成功但未协商应用协议")
default:
    return fmt.Errorf("未识别的 ALPN 结果 %q", state.NegotiatedProtocol)
}

服务端也可以在 Handshake 成功后读取连接状态。记录协议结果时，建议同时带上服务实例、监听端口和配置版本，但不要打印私钥或完整证书。这样能分清“客户端没有提议”“双方无交集”和“协商成功但路由错误”。

用最小用例复现不匹配

为了把网络、DNS 和负载均衡器排除在外，可以用 net.Pipe 在内存中连接一对 TLS 客户端与服务端。两边分别配置不相交的 NextProtos，预期服务端或客户端握手返回错误；再把列表改成有交集，确认 NegotiatedProtocol 等于预期值。

func handshakePair(clientCfg, serverCfg *tls.Config) (string, error) {
    rawClient, rawServer := net.Pipe()
    defer rawClient.Close() // 测试结束时释放内存连接
    defer rawServer.Close()

    client := tls.Client(rawClient, clientCfg)
    server := tls.Server(rawServer, serverCfg)

    serverErr := make(chan error, 1)
    go func() {
        // 服务端与客户端必须并发握手，避免 net.Pipe 相互等待
        serverErr 

匹配用例可让两边都包含 h2，不匹配用例则让客户端仅包含 proto-a、服务端仅包含 proto-b。证书生成或测试证书加载属于测试准备，不应混入 ALPN 断言本身。测试失败时同时输出双方列表，能比单独保留握手错误更快定位。

防止配置再次漂移

这类故障的根因往往不是 crypto/tls 本身，而是配置契约没有被共同维护。客户端 SDK 新增协议名、入口代理覆盖 NextProtos、服务端模板漏掉 http/1.1，都会让原本可用的交集消失。

• 在配置加载阶段拒绝空字符串、重复值和带空白字符的协议名。
• 为每个公开入口维护允许的 ALPN 集合，而不是由多个组件各自猜测。
• 集成测试至少覆盖首选协议、备用协议、空列表和无交集四种状态。
• 握手成功后统计 NegotiatedProtocol，发现空值或未知值时告警。
• 代理、网关和服务升级时，把 ALPN 列表纳入变更评审。

常见问题

NextProtos 的顺序由谁决定最终选择？

Go 服务端从共同协议中按服务端列表的偏好顺序选择。客户端顺序表达提议偏好，但最终选择权在服务端。

把 NextProtos 设为 nil 能绕过不匹配吗？

普通 TLS 连接可能因此不再执行 ALPN 选择并返回空 NegotiatedProtocol，但这只是取消应用协议协商，不是修复。若业务依赖 HTTP/2、gRPC、自定义复用协议或 QUIC，空结果通常不可接受。

证书正确为什么仍会握手失败？

证书验证和 ALPN 是握手中的不同检查。证书链与主机名正确，只能说明身份验证通过；双方应用协议列表没有交集时，握手仍会终止。

如何确认服务端实际选择了什么？

在 Handshake 成功后读取 tls.Conn.ConnectionState().NegotiatedProtocol。不要仅从配置列表推断结果，因为配置可能被回调、代理层或环境模板替换。

官方资料

Go TLS 配置与连接状态文档：https://pkg.go.dev/crypto/tls；服务端 ALPN 选择源码：https://go.dev/src/crypto/tls/handshake_server.go；ALPN 标准：https://www.rfc-editor.org/rfc/rfc7301.html。

复盘这类故障时，最关键的不是不断放宽 TLS 配置，而是把双方协议列表当作一个可验证的接口契约。先确认错误发生在 ALPN，随后比较精确字符串和交集，最后用 NegotiatedProtocol 证明修复结果，定位过程就能从猜测变成可重复的检查。