Go TLS 握手失败如何判断是证书还是协议版本

Go TLS 握手失败时，不要先把 InsecureSkipVerify 打开。先看错误是否能落到 crypto/x509 的证书校验，再用固定版本的最小对照判断协议协商。证书问题通常围绕信任链、主机名和根证书；协议问题则围绕客户端与服务端没有共同的 TLS 版本。

最实用的判断顺序是：在 HandshakeContext 处拿到原始错误，先用 errors.As 识别证书类型，再核对 ServerName 和 RootCAs，最后才用 MinVersion/MaxVersion 做版本对照。

• 出现 x509.UnknownAuthorityError、x509.HostnameError 等类型，优先查证书链、主机名和信任根。
• 出现 protocol version not supported 或没有共同版本的提示，优先查双方版本范围。
• 只把固定 TLS 版本用于定位；修复时保持默认安全范围，除非服务端兼容性已经明确。

先看错误落在哪一层

tls.Conn 的握手可以由第一次读写自动触发，也可以显式调用 HandshakeContext。把错误集中在这个入口，便于判断失败发生在证书验证还是版本协商，而不是把网络超时、远端主动关闭和证书错误混在一起。

证书类错误常见于以下几种边界：

• x509.UnknownAuthorityError：服务端证书链无法在当前信任根中建立可信路径。
• x509.HostnameError：证书中的名称与 ServerName 不匹配，或客户端没有按正确主机名发起 SNI。
• x509.CertificateInvalidError：证书时间、用途或其他约束不满足。

这些错误的共同点是已经走到了证书验证语义。相反，协议版本错误通常在双方还没有建立可用的版本交集时出现，不能靠补 CA 证书解决。

用 HandshakeContext 做最小对照

定位时可以把地址、主机名和超时保持不变，只改变客户端允许的版本。下面的示例把握手错误保留下来，并用 errors.As 识别证书错误；代码只展示诊断写法，不代表某个具体服务的运行结果。

package main

import (
	"context"
	"crypto/tls"
	"crypto/x509"
	"errors"
	"fmt"
	"net"
	"time"
)

func dialOnce(ctx context.Context, address, serverName string, version uint16) error {
	// 固定上下限只用于诊断版本兼容性，不要直接当成生产修复。
	config := &tls.Config{
		ServerName: serverName, // 用真实主机名参与证书校验和 SNI。
		MinVersion: version,
		MaxVersion: version,
	}
	dialer := &net.Dialer{Timeout: 5 * time.Second}
	conn, err := dialer.DialContext(ctx, "tcp", address)
	if err != nil {
		return fmt.Errorf("建立 TCP 连接失败: %w", err)
	}
	defer conn.Close() // 无论握手成功与否，都释放底层连接。

	tlsConn := tls.Client(conn, config)
	defer tlsConn.Close() // 释放 TLS 包装层，避免诊断代码泄漏资源。
	if err := tlsConn.HandshakeContext(ctx); err != nil {
		var hostnameErr x509.HostnameError
		var authorityErr x509.UnknownAuthorityError
		if errors.As(err, &hostnameErr) || errors.As(err, &authorityErr) {
			return fmt.Errorf("证书校验失败: %w", err)
		}
		return fmt.Errorf("TLS 握手失败: %w", err)
	}
	return nil
}

对同一个目标分别传入 tls.VersionTLS12 和 tls.VersionTLS13 时，如果两次都返回证书类型错误，问题多半不在版本；如果某个版本能进入证书验证而另一个版本直接报协议不支持，则版本范围就是重要线索。诊断结束后要撤掉“固定单一版本”的临时限制。

复核 ServerName、RootCAs 与版本范围

ServerName 同时影响主机名校验和客户端发送的 SNI。使用 IP 直连时，如果证书只签发给域名，连接地址能通并不代表证书能通过。RootCAs 为空时，Go 会使用主机的系统根证书集；只有在私有 CA、测试 CA 或明确的隔离信任场景中，才应该加载自定义 CertPool。

roots, err := x509.SystemCertPool()
if err != nil {
	return fmt.Errorf("读取系统根证书失败: %w", err)
}

config := &tls.Config{
	ServerName: "api.example.com", // 必须与证书名称和服务端 SNI 预期一致。
	RootCAs:    roots,               // 只在需要时替换为包含私有 CA 的 CertPool。
	MinVersion: tls.VersionTLS12,    // 保持现代安全下限，不为绕过错误盲目降级。
}

如果只配置了 MinVersion，MaxVersion 默认跟随当前 Go 支持的最高版本；如果两者都写成固定值，则连接只能使用这一版。当前文档的默认下限是 TLS 1.2、默认上限跟随当前支持版本，但最终仍应以项目所用 Go 版本和服务端能力为准。

按安全边界选择修正

证书错误的修复方向是补齐正确的中间证书、修正 ServerName、更新系统根证书或把受信任的私有 CA 加入 RootCAs。不要用 InsecureSkipVerify: true 作为常规修复；它会跳过服务端证书链和主机名验证，官方文档也明确提示这会暴露中间人攻击风险。

协议版本错误的修复方向则是确认服务端实际支持的版本，并让客户端保留一个合理的版本范围。只有在明确知道对端只支持 TLS 1.2 等兼容性事实时，才考虑设置对应的 MaxVersion 或 MinVersion；不应为了让握手“成功”而退回已不适合的旧版本。

握手完成后才能可靠使用 ConnectionState 查看协商结果，例如 Version、NegotiatedProtocol 和 ServerName。如果握手根本没有完成，就不要把尚未填充的状态当成诊断证据。

一张表记住判断顺序

核心判断可以压缩成一句话：x509 类型错误先查证书和主机名，协议版本提示再查版本交集；两者都没有明确证据时，保留原始错误并继续区分 TCP、TLS 握手和应用层响应。

相关问题

把 InsecureSkipVerify 打开后能连通，说明什么？

只能说明连接可能卡在证书链或主机名校验，不能证明服务端安全可用。生产环境应修正证书、信任根或 ServerName，而不是长期跳过验证。

为什么设置了 ServerName 仍然报证书错误？

ServerName 只解决主机名和 SNI 这一部分，证书链仍要能被 RootCAs 信任，证书有效期和用途也必须满足 x509 校验。

固定 TLS 1.2 能连，TLS 1.3 不能连，应该永久固定吗？

先把它当作版本兼容性证据，再确认服务端、代理或中间设备是否真正支持 TLS 1.3。若没有明确兼容性边界，优先保留合理版本范围，并修复对端配置。