Go TLS ALPN 协商结果为空时怎样排查协议选择

Go TLS 握手成功后，如果 ConnectionState().NegotiatedProtocol 仍是空字符串，先不要把它当成证书错误或网络不通。这个字段只表示 ALPN 最终没有得到应用层协议名称：可能是两端都没有配置 NextProtos，可能是客户端广告列表与服务端支持列表没有交集，也可能是在握手完成前就读取了连接状态。排查时要把“TLS 已建立”和“应用协议已选定”分开看。

最短判断路径是：先确认握手已完成，再分别打印客户端与服务端的 NextProtos，最后核对协议字符串是否完全相同。只有存在共同协议并完成选择时，NegotiatedProtocol 才会出现如 h2 或 http/1.1 的值；如果业务必须依赖某个协议，就应在空值时停止按该协议发送数据。

• 空值的含义：Go 文档允许未配置 ALPN 的 TLS 连接成功，此时结果字段为空。
• 优先检查：客户端和服务端的 NextProtos 是否至少有一个完全一致的标识。
• 读取时机：显式调用 Handshake 或确认上层请求已经完成握手后，再读取 ConnectionState。

先把空结果和 TLS 握手失败分开

NegotiatedProtocol 不是“TLS 是否安全”的总开关，它只记录 ALPN 的应用层协议结果。Go 的 tls.Config.NextProtos 文档明确区分了两种情况：当双方都支持 ALPN 时，选择结果应来自共同列表；如果 NextProtos 为空，或对端不支持 ALPN，连接可以成功，但 NegotiatedProtocol 会保持空值。因此，证书校验成功、密码套件已经选出，并不意味着 h2 已经被选中。

先看两端到底有没有共同协议

ALPN 的输入不是“协议类型的模糊名称”，而是协议标识列表。例如客户端写了 h2，服务端写了 http2，人眼看起来接近，TLS 协商却不会把它们当成同一个值。服务端会从自己的支持列表和客户端广告列表中寻找交集；常见 HTTP 配置会同时放入 h2 与 http/1.1，但最终仍应以实际的上层实现为准。

建议把列表当成配置证据保存，而不是只记录“支持 HTTP/2”这样的自然语言。重点核对大小写、斜杠、点号和协议顺序；服务端偏好顺序会影响共同协议的选择，但不会把没有交集的两个字符串强行合并。

// 只保留与 ALPN 相关的配置片段，证书字段省略。
clientConfig := &tls.Config{
    ServerName: "api.example.com",
    // 客户端把可接受的应用协议按偏好顺序发送给服务端。
    NextProtos: []string{"h2", "http/1.1"},
}

serverConfig := &tls.Config{
    // 服务端只从这份支持列表中选择客户端也声明过的协议。
    NextProtos: []string{"h2", "http/1.1"},
}

_, _ = clientConfig, serverConfig // 示例只展示协议边界，证书和监听代码未展开。

状态必须在握手完成后读取

如果代码在 tls.Client 或 tls.Server 返回后立即读取状态，看到空值并不能说明 ALPN 真正没有选中，因为握手可能还没有执行。把判断放到显式握手成功之后，才能把“尚未产生结果”和“结果确实为空”区分开。

// 在握手完成后读取 ALPN，并阻止上层误用未确认的协议。
func requireALPN(conn *tls.Conn, want string) error {
    // 显式握手，把状态读取边界固定在成功结果之后。
    if err := conn.Handshake(); err != nil {
        return fmt.Errorf("TLS 握手失败: %w", err)
    }

    state := conn.ConnectionState()
    // 空值表示没有得到 ALPN 选择，不能继续假定是 want。
    if state.NegotiatedProtocol == "" {
        return fmt.Errorf("ALPN 为空，期望协议 %q", want)
    }
    // 选择结果必须与上层处理器的期望一致。
    if state.NegotiatedProtocol != want {
        return fmt.Errorf("ALPN=%q，不是期望的 %q", state.NegotiatedProtocol, want)
    }
    return nil
}

这段检查只负责协议边界，调用方仍要负责关闭连接和处理业务读写。NegotiatedProtocolIsMutual 不应再作为新的诊断依据：当前 Go 文档将它标记为已弃用，并说明该值始终为 true。

无交集时该修配置还是让握手失败

如果应用可以回退到明文的 HTTP/1.1 语义或自定义默认协议，那么空值可能是一个明确的兼容分支：记录原因，选择安全的默认处理器，并确保对端也理解这个约定。相反，如果服务端只接受 h2，就不能在空值时继续写 HTTP/2 帧；应让握手失败或在应用层立即拒绝连接。

RFC 7301 的基本规则是服务端从客户端广告的协议中选择；没有共同协议时，严格实现可以返回 no_application_protocol。Go 标准库的普通 TLS 配置也保留了“未配置 ALPN 时连接成功且结果为空”的兼容行为，所以排查时要同时看配置意图和实际错误，而不是只凭一个空字符串下结论。

Go TLS ALPN 常见问题 FAQ

只给客户端设置 NextProtos 可以吗？

通常不能得到想要的协商结果。服务端也需要声明自己支持的协议；如果服务端没有配置，普通 TLS 连接仍可能成功，但 NegotiatedProtocol 为空。

NextProtos 顺序会影响结果吗？

会影响偏好选择，但前提是两端存在共同协议。顺序不能修复拼写不同、列表为空或完全没有交集的问题。

NegotiatedProtocol 为空就一定是配置错误吗？

不一定。对端不使用 ALPN、双方有意允许无协议标识的 TLS 连接，或者代码尚未完成握手，都可能出现空值。只有当上层明确要求某个协议时，空值才应被视为需要阻断的错误。

排查这类问题可以固定成一条清单：记录握手错误或成功状态，打印两端 NextProtos，比较协议字面值，确认 Handshake 完成后再读 ConnectionState，最后让上层根据实际协商结果选择处理器。这样既不会把 ALPN 空值误判成 TLS 全部失败，也不会在协议没有确认时继续发送错误格式的数据。