Go TLS SNI 与证书选择不匹配的定位

Go TLS 里“证书不匹配”不一定是证书文件错了。更常见的情况是：客户端没有按预期发送 SNI，服务端因此选了默认链；或者服务端确实收到 SNI，却在 GetCertificate 中返回了另一条证书链。定位时我会把问题拆成三层：客户端发出的 ServerName、服务端实际选择的证书、客户端最终校验的 SAN 和信任链。

官方文档：https://pkg.go.dev/crypto/tls

先看握手中的 SNI，再看服务端选了哪条证书链，最后解释客户端的校验错误。不要用 HTTP 的 Host 头反推 TLS 已经收到的名称，因为证书选择发生在 HTTP 请求之前。

先把 ServerName、SNI 和 Host 分开

在 Go 客户端里，tls.Config.ServerName用于校验证书主机名，同时也会被放入 ClientHello 的 SNI 扩展，以支持虚拟主机。若连接配置使用的是 IP 地址，Go 不会把这个 IP 当作域名自动写成 SNI；此时服务端通常只能走默认证书分支。

package main

import "crypto/tls"

func clientConfig() *tls.Config {
	return &tls.Config{
		ServerName: "api.example.com", // 用证书中的 DNS SAN 做校验，也作为 SNI 名称。
		MinVersion: tls.VersionTLS12, // 只表达协议下限，不参与证书名称选择。
	}
}

这也是排查“浏览器正常、Go 客户端失败”时的第一个分叉：浏览器通常从域名连接，而测试代码可能把域名解析成 IP 后直接把 IP 传给 tls.Dial。如果代码必须连接固定 IP，应保留真实域名作为 ServerName，不要用 InsecureSkipVerify 来掩盖名称不匹配。

确认服务端收到的 SNI，而不是猜 Host

服务端选择证书时看到的是 ClientHelloInfo.ServerName。在自定义 TLS 服务中，可以把它写入握手阶段的诊断日志；在 HTTP 服务中，r.Host出现得更晚，不能证明证书选择阶段拿到了同一个名称。

package main

import (
	"crypto/tls"
	"log"
)

func certificateSelector(cfg *tls.Config) *tls.Config {
	clone := cfg.Clone() // 不直接修改正在服务的共享 Config。
	clone.GetCertificate = func(hello *tls.ClientHelloInfo) (*tls.Certificate, error) {
		log.Printf("tls client_hello server_name=%q", hello.ServerName) // 记录 SNI 原值。
		return selectCertificate(hello.ServerName)
	}
	return clone
}

func selectCertificate(serverName string) (*tls.Certificate, error) {
	// 这里应按明确的名称表查找证书，并在找不到时返回可识别错误。
	return nil, nil
}

真实项目中不要把证书内容或私钥写入日志，只记录名称、证书标识和选择结果即可。若日志中的 server_name为空，先回到客户端配置检查；若名称正确但选中证书仍不对，再检查回调中的通配符匹配、默认分支和证书缓存。

按证书选择入口定位分支

服务端至少要设置 Certificates、GetCertificate 或 GetConfigForClient 之一。没有回调时，Go 会从 Certificates 中选择与客户端能力兼容的链；配置了 GetCertificate 后，客户端提供 SNI 时会进入回调，由应用自己决定返回哪张证书。

因此可以按下面的顺序看配置：第一，是否把多张证书都放进了同一个 Certificates；第二，是否存在一个总是返回默认证书的 GetCertificate；第三，GetConfigForClient 返回的新配置是否覆盖了原来的证书列表。旧代码中还可能看到 NameToCertificate，但当前文档已标记它弃用，排查时不应把它当成新的动态选择方案。

func chooseCertificate(hello *tls.ClientHelloInfo, table map[string]*tls.Certificate) (*tls.Certificate, error) {
	name := hello.ServerName // 只使用握手阶段的 SNI，不读取后续 HTTP Host。
	if cert, ok := table[name]; ok {
		return cert, nil // 精确域名命中后直接返回对应链。
	}
	if cert, ok := table["*.example.com"]; ok {
		return cert, nil // 通配符规则要在代码中明确，不能误当成任意后缀。
	}
	return nil, fmt.Errorf("no certificate for SNI %q", name) // 让握手错误保留名称线索。
}

上面的片段强调的是选择边界，实际代码还需要导入 fmt 并实现完整的通配符规则。关键不是“把所有证书都塞进去”，而是让一个可观察的 SNI 值对应一个可追踪的证书标识；否则证书链越多，默认分支越难发现。

把名称错误、信任链错误和链条缺失分层

客户端错误类型通常能帮助缩小范围。x509.HostnameError指向证书名称与 ServerName不匹配，重点检查 DNS SAN；x509.UnknownAuthorityError更像是客户端不信任签发链；如果服务端发送的中间证书缺失，常见表现则是无法构建完整验证链。不要看到“certificate verify failed”就只替换证书文件。

建议握手日志至少保留四个字段：server_name、选中证书的序列号或内部 ID、证书链长度、最终错误类型。客户端还可以在非生产诊断程序中打印 ConnectionState().PeerCertificates 的主题和 DNS SAN，但不要打印私钥，也不要为了观察结果关闭校验。

我会保留的排查清单

常见追问

HTTP Host 和 TLS SNI 不一致会怎样？

证书已经在 HTTP 请求发送前选定，Host 不能回头改变证书。两者不一致时，即使路由层最终找到了正确服务，也可能早已因为证书校验失败而无法建立连接。

把 InsecureSkipVerify 设为 true 能定位问题吗？

它可以帮助区分“网络和握手能否继续”与“客户端校验是否失败”，但会关闭证书链和主机名校验，不能作为修复方案。诊断结束后应恢复正常校验，再根据具体错误修正 SNI、SAN 或信任链。

这类问题最容易被“证书文件看起来正确”带偏。沿着 ServerName → ClientHelloInfo.ServerName → 选中证书 → SAN/信任链 记录证据，通常能在一次握手日志里判断问题究竟发生在名称传递、服务端选择，还是客户端验证。