Go问答：http.Transport 的 TLSClientConfig 未设置 ServerName 为什么握手失败

在 Go 里给 http.Transport 设置了自定义 TLSClientConfig 后，HTTPS 请求出现“握手失败”或证书主机名不匹配，最容易先怀疑 ServerName。但要先分清路径：标准 Transport 通常会根据请求 URL 的主机名参与 TLS 连接；真正容易出问题的是自定义 TLS 拨号、用 IP 访问只签发给域名的证书，或者把 ServerName 写成了代理地址、服务别名而不是证书覆盖的名称。

正确处理方式不是把 InsecureSkipVerify 打开，而是让请求主机名、SNI、证书 SAN 和信任根保持一致。只有在你明确接管证书验证流程时，才考虑自定义验证回调。

官方文档：https://pkg.go.dev/net/http#Transport

TLS 配置文档：https://pkg.go.dev/crypto/tls#Config

先判断：空 ServerName 是否真的是根因

Transport.TLSClientConfig 的作用是把 TLS 配置交给 tls.Client。在普通的 HTTPS 请求中，Go 会结合请求目标建立 TLS 连接；因此“字段为空”并不等于每次都会失败。不要看到空值就直接改成固定域名，先看下面三种路径。

把请求主机名、SNI 和证书 SAN 对齐

tls.Config.ServerName同时影响两件事：客户端在 TLS 握手中发送的 SNI 名称，以及默认证书主机名校验使用的名称。它必须是证书覆盖的 DNS 名称，或者在证书的 IP SAN 中出现的 IP 地址。

例如，服务证书只包含 api.example.com，请求却写成 https://10.0.0.8/。这时 TCP 连接可能完全正常，但证书校验仍然可能因为名称不匹配失败。将 ServerName 填成 10.0.0.8 也不能把 DNS SAN 变成 IP SAN；应该使用证书覆盖的域名，或重新签发包含目标 IP 的证书。

反过来，如果连接通过自定义拨号器送到内部地址，但业务请求仍然使用公开域名，那么可以把“连接到哪里”和“证书验证谁”分开：拨号地址负责网络可达性，ServerName负责 TLS 身份。

用显式配置修复，同时保留证书校验

当程序确实使用了自定义 tls.Config，可以显式设置 ServerName。下面的写法把 TLS 身份固定为证书中的域名，仍然使用系统根证书，不关闭主机名和证书链校验。

package main

import (
    "context"
    "fmt"
    "net/http"
    "time"
    "crypto/tls"
)

func newClient() *http.Client {
    transport := &http.Transport{
        TLSClientConfig: &tls.Config{
            // 该名称用于 SNI 和默认证书主机名校验，必须与证书 SAN 对齐。
            ServerName: "api.example.com",
            // 不设置 InsecureSkipVerify，继续使用正常的证书链校验。
        },
        TLSHandshakeTimeout: 8 * time.Second,
    }

    return &http.Client{
        Transport: transport,
        Timeout:   15 * time.Second,
    }
}

func fetch(ctx context.Context) error {
    client := newClient()
    req, err := http.NewRequestWithContext(ctx, http.MethodGet, "https://api.example.com/health", nil)
    if err != nil {
        return fmt.Errorf("创建请求失败: %w", err)
    }

    resp, err := client.Do(req)
    if err != nil {
        return fmt.Errorf("HTTPS 请求失败: %w", err)
    }
    // 读取完响应后关闭 Body，避免连接复用和资源释放受到影响。
    defer resp.Body.Close()
    return nil
}

如果服务使用内部 CA，还需要把该 CA 加入 RootCAs，而不是用 InsecureSkipVerify 绕过验证。RootCAs为空时，客户端会使用当前系统的根证书集合。

自定义 DialTLSContext 时，TLSClientConfig 不再接管握手

这是最容易误判的边界。官方文档说明：如果设置了 DialTLSContext，返回的连接被视为已经完成 TLS 握手，TLSClientConfig 和 TLSHandshakeTimeout 都不会参与这次 HTTPS 拨号。此时把 ServerName 加到 Transport 上不会修复由自定义拨号器创建的 TLS 连接。

func dialTLS(ctx context.Context, network, addr string) (net.Conn, error) {
    rawConn, err := (&net.Dialer{Timeout: 5 * time.Second}).DialContext(ctx, network, addr)
    if err != nil {
        return nil, fmt.Errorf("建立 TCP 连接失败: %w", err)
    }

    cfg := &tls.Config{
        // 自定义 TLS 拨号时，ServerName 必须在这里设置并参与握手。
        ServerName: "api.example.com",
    }
    tlsConn := tls.Client(rawConn, cfg)
    // 握手失败时主动关闭底层连接，避免留下半开的资源。
    if err := tlsConn.HandshakeContext(ctx); err != nil {
        rawConn.Close()
        return nil, fmt.Errorf("TLS 握手失败: %w", err)
    }
    return tlsConn, nil
}

这个片段只说明责任边界；如果自定义 TLS 拨号返回连接，调用方还应确认它实现了所需的连接状态能力，并按项目需要处理超时、证书池和协议协商。

按错误层次复查，而不是只改一个字段

可以把错误拆成四层。第一层是 DNS 或 TCP 拨号失败，通常还没有开始证书校验；第二层是 TLS 版本、密码套件或 ALPN 协商失败；第三层是证书链不受信任；第四层是证书能被信任，但主机名不匹配。

对第四层，重点看 x509.HostnameError 或错误文本中的证书名称；对第三层，检查系统根证书、内部 CA 和 RootCAs；如果错误来自自定义 DialTLSContext，先确认实际使用的 tls.Config，不要只看 Transport.TLSClientConfig。

var urlErr *url.Error
if errors.As(err, &urlErr) {
    // url.Error 保留了请求阶段信息，先看 Op、URL 和内部错误。
    fmt.Printf("操作=%s 地址=%s 原因=%v\n", urlErr.Op, urlErr.URL, urlErr.Err)
}

var hostErr x509.HostnameError
if errors.As(err, &hostErr) {
    // HostnameError 表示证书身份与待校验名称不一致。
    fmt.Printf("证书主机名不匹配: %s\n", hostErr.Host)
}

一张表记住正确的修复方向

常见追问

ServerName 可以写成服务器 IP 吗？

可以，但前提是证书的 IP SAN 包含该 IP。DNS 名称和 IP 地址的证书匹配规则不同，不能互相替代。

把 ServerName 留空是不是一定不安全？

不是。标准 HTTPS Transport 会结合请求目标处理连接；关键是确认实际 TLS 拨号路径和证书校验名称。空值在自定义拨号或手工创建 tls.Client 时更容易变成问题。

为什么不建议直接设置 InsecureSkipVerify？

它会关闭服务端证书链和主机名的默认验证，无法证明连接的确到达了预期服务。测试环境可临时使用，但生产环境应修复 ServerName、RootCAs 或证书本身。