TLS握手失败时应类型断言错误并用%+v打印完整字段，启用GODEBUG日志查看ClientHello和证书详情，在VerifyPeerCertificate中解析证书时间与签名算法，结合OpenSSL抓包比对密码套件兼容性。
查看 TLS 握手失败时的原始错误信息
Go 的 crypto/tls 默认会把底层网络或协议错误包装成 *net.OpError 或 *tls.RecordHeaderError，但关键细节常被吞掉。直接打印 err.Error() 通常只看到 remote error: tls: bad certificate 这类模糊提示，没法定位是证书过期、域名不匹配，还是签名算法不被支持。
正确做法是类型断言并展开底层错误：
if err != nil {
if tlsErr, ok := err.(net.Error); ok && tlsErr.Timeout() {
log.Printf("TLS timeout: %v", err)
}
if recErr, ok := err.(*tls.RecordHeaderError); ok {
log.Printf("TLS record header error: %v, header=%x", recErr, recErr.RecordHeader)
}
if opErr, ok := err.(*net.OpError); ok {
if tlsErr, ok := opErr.Err.(tls.RecordHeaderError); ok {
log.Printf("Record header error inside OpError: %v", tlsErr)
}
}
log.Printf("Full error chain: %+v", err) // 用 %+v 看字段
}
- 必须用
%+v而非%v，否则tls.CertificateError等结构体不显示具体字段（如Subject、Expired） -
*tls.RecordHeaderError出现往往意味着对方根本没发合法 TLS 记录（比如 HTTP 服务误接在 HTTPS 端口上），RecordHeader字节能帮你确认是不是收到了HTTP/1.1响应头 - 某些错误（如证书验证失败）会在
ClientConfig.VerifyPeerCertificate回调里抛出，此时需手动记录cert和chains参数
启用 TLS 底层日志（Go 1.22+）
Go 1.22 起，crypto/tls 支持通过环境变量开启握手过程的详细日志，无需改代码：
GODEBUG=tls13=1,tlshandshake=1 go run main.go
输出包含 ClientHello 内容、密钥交换步骤、证书链解析、Finished 消息校验等。关键看三处：
立即学习“go语言免费学习笔记（深入）”；
- 收到的
Certificate消息中certificates[0].Subject.CommonName和DNSNames是否含目标域名 - 出现
certificate verify failed时，日志会列出验证失败的具体原因（如signature algorithm not supported、not valid after） - 若卡在
ClientKeyExchange后无响应，大概率是服务器不支持客户端提议的密钥交换算法（如客户端只支持 ECDHE-ECDSA，而服务器只配了 RSA 证书）
手动验证证书链与时间有效性
很多“握手失败”本质是证书问题，但 Go 不会默认告诉你哪张证书出问题。可在 ClientConfig.VerifyPeerCertificate 中插入诊断逻辑：
cfg := &tls.Config{
VerifyPeerCertificate: func(rawCerts [][]byte, verifiedChains [][]*x509.Certificate) error {
for i, raw := range rawCerts {
cert, err := x509.ParseCertificate(raw)
if err != nil {
log.Printf("Failed to parse cert[%d]: %v", i, err)
continue
}
log.Printf("Cert[%d] CN=%s, NotAfter=%v, SignatureAlgorithm=%s",
i, cert.Subject.CommonName, cert.NotAfter, cert.SignatureAlgorithm)
}
return nil // 先跳过验证，看是否还有其他错误
},
}
- 注意：返回
nil仅跳过验证逻辑，不影响后续加密通信；若想保留默认验证，应在最后调用cfg.VerifyPeerCertificate = nil并让 Go 自己处理 - 重点检查
NotBefore/NotAfter是否在当前系统时间范围内（本地时间不准会导致x509: certificate has expired or is not yet valid） - 如果
verifiedChains为空但rawCerts非空，说明系统根证书缺失或中间证书未下发——此时需手动指定RootCAs或补全ClientConfig.ClientCAs
对比 OpenSSL 抓包确认服务端行为
当 Go 客户端连不上，但 curl -v https://host 正常，大概率是 Go 和服务端协商参数不兼容。用 OpenSSL 模拟相同配置抓握手过程：
openssl s_client -connect example.com:443 -tls1_2 -cipher 'ECDHE-ECDSA-AES128-GCM-SHA256' -debug -msg
- 用
-tls1_2/-tls1_3显式指定版本，匹配 Go 默认启用的 TLS 版本（Go 1.22 默认禁用 TLS 1.0/1.1） -
-cipher参数填 GoClientHello日志里实际发送的密码套件（如ECDHE-ECDSA-AES256-GCM-SHA384），避免因服务端优先级策略导致差异 - 观察 OpenSSL 输出中
ServerHello的Cipher字段是否和客户端提议一致；若服务端回了handshake failurealert，说明它拒绝了全部密码套件或扩展
真正难搞的是服务端静默丢包或重置连接——这种情况下 Wireshark 抓包看到 TCP RST 或无 TLS 记录，基本可判定是防火墙、代理或服务端 TLS 配置（如 Nginx 的 ssl_protocols）拦截了请求。
