Go TLS 证书主机名不匹配的核对步骤

Go TLS 报“证书主机名不匹配”时，最常见的原因不是证书链完全不可信，而是程序拿来核对的名称与证书允许的名称不是同一个。先把 TCP 连接地址、SNI 中的 ServerName、证书的 SAN（Subject Alternative Name）和业务希望访问的域名分开，再按下面顺序核对，通常不需要关闭证书校验。

先确认程序实际核对的主机名，再看证书的 DNSNames 或 IPAddresses 是否覆盖它。若只是通过 IP 连接而证书签给域名，应修正访问入口或明确设置正确的 ServerName，不要用 InsecureSkipVerify 把问题隐藏起来。

先把连接地址、SNI 和证书名称分开

一次 TLS 访问里至少有三类“名称”：TCP 层连接到的地址，例如 10.0.0.8:443；TLS 配置里的 ServerName，它参与服务端虚拟主机选择和证书主机名核对；证书 SAN 中列出的 DNS 名称或 IP 地址。三者可以相关，但不是同一个字段。

先记录以下四项，不要直接从错误字符串猜原因：

• URL 或拨号参数中的主机和端口；
• tls.Config.ServerName 是否显式设置；
• 连接是否经过反向代理、服务发现或 IP 直连；
• 证书 SAN 中究竟是域名、IP，还是二者都有。

例如，访问 https://10.0.0.8/ 时，默认按 IP 做名称核对；如果证书只包含 api.example.com，链可能可信，但名称仍然不匹配。此时应确认业务允许的入口是否本来就应该是 api.example.com，而不是把错误改成“跳过验证”。

查看证书的 SAN 与地址类型

crypto/x509 中，Certificate.DNSNames 用于 DNS 名称，Certificate.IPAddresses 用于 IP 地址。Go 的主机名核对会忽略旧式 Common Name，不能只打开证书详情看 Common Name 就下结论。下面的辅助函数只负责打印证书已经声明的名称，输入可以来自 PEM 文件或其他受信任的证书来源。

package main

import (
    "crypto/x509"
    "fmt"
    "net"
)

func printCertificateNames(cert *x509.Certificate) {
    // DNSNames 和 IPAddresses 是两种不同的匹配集合，排障时分别记录。
    fmt.Println("DNSNames:", cert.DNSNames)
    fmt.Println("IPAddresses:", cert.IPAddresses)
}

func classifyTarget(host string) string {
    // IP 目标应与证书的 IPAddresses 对照，不能拿它去匹配 DNSNames。
    if net.ParseIP(host) != nil {
        return "ip"
    }
    return "dns"
}

核对时特别注意端口不要传给名称匹配函数：api.example.com:443 是地址，api.example.com 才是主机名。IPv6 地址可能带方括号，先用 net.SplitHostPort 拆出主机部分。

用 VerifyHostname 做最小化复核

如果完整握手日志太长，可以对已经解析出的叶子证书调用 VerifyHostname。它会返回主机名不匹配的错误；普通 DNS 名称按大小写不敏感规则比较，IP 地址按证书的 IP 字段比较，通配符只能作为完整的最左侧标签。

package main

import (
    "crypto/x509"
    "errors"
    "fmt"
)

func checkHostname(cert *x509.Certificate, host string) error {
    // 这里的 host 只传主机名，不包含端口和 URL scheme。
    if err := cert.VerifyHostname(host); err != nil {
        var hostnameErr x509.HostnameError
        if errors.As(err, &hostnameErr) {
            // HostnameError 携带实际核对的 Host，可用于结构化日志。
            return fmt.Errorf("证书未覆盖主机名 %q: %w", hostnameErr.Host, err)
        }
        return fmt.Errorf("主机名核对失败: %w", err)
    }
    return nil
}

例如证书包含 *.example.com 时，api.example.com 可以匹配，但 a.b.example.com 不应被当作同一层级的匹配。证书包含 IP 时，程序也必须使用同一个 IP 作为核对目标；把 IP 写成字符串放入 DNS 名称列表并不能改变它的类型。

在 tls.Config 中修正 ServerName

客户端配置里的 ServerName 会用于返回证书的主机名验证，也会作为客户端握手中的 SNI（当它不是 IP 时）。如果 TCP 需要连接固定 IP，但服务端证书和虚拟主机使用域名，可以把网络连接地址与 TLS 名称分开：

package main

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

func dialByIPWithDNSName() error {
    // TCP 连接走固定地址，TLS 名称仍使用证书覆盖的 DNS 名称。
    raw, err := net.DialTimeout("tcp", "10.0.0.8:443", 5*time.Second)
    if err != nil {
        return err
    }
    // 握手失败时关闭底层连接，避免排障代码留下资源。
    defer raw.Close()

    conn := tls.Client(raw, &tls.Config{
        ServerName: "api.example.com",
        MinVersion: tls.VersionTLS12,
    })
    if err := conn.Handshake(); err != nil {
        return fmt.Errorf("TLS 握手失败: %w", err)
    }
    defer conn.Close()
    return nil
}

如果使用 net/http，同样把 http.Transport.TLSClientConfig 中的 ServerName 与证书名称对应起来，并确认重定向、服务发现或代理没有把原本的域名替换成 IP。修正名称后仍然要保留根证书、有效期和链验证。

按通配符、代理和自定义校验收尾

如果 SAN 已覆盖预期名称，仍出现错误，就继续检查实际发送的 SNI、代理终止 TLS 的位置和连接是否复用旧配置。代理前端拿到的证书可能与后端服务证书不同，客户端应该核对它真正建立 TLS 的那一跳。

InsecureSkipVerify 会同时跳过服务端证书链和主机名的默认核验，官方文档明确把它限定在测试或配合自定义校验的场景。确实需要自定义校验时，应在 VerifyConnection 中明确构造 x509.VerifyOptions，把 DNSName、根证书和中间证书处理写清楚，并保留错误返回；不要只设置一个布尔值。

一张表判断下一步

常见追问

证书的 Common Name 对了，为什么 Go 仍然报错？

Go 的主机名核对以 SAN 为准，旧式 Common Name 不再作为足够的匹配依据。应检查证书的 DNSNames 或 IPAddresses。

ServerName 能不能随便填成证书里的域名？

不能。它既影响名称核对，也可能影响服务端按 SNI 选择证书。只有在该名称确实是业务允许的入口，并且网络连接路径支持它时才应设置。

开发环境能否直接设置 InsecureSkipVerify？

只适合明确隔离的测试，且不应成为生产配置或排障结论。更稳妥的做法是补齐本地根证书、使用正确的 ServerName，或实现可审查的自定义验证。

官方资料入口：https://pkg.go.dev/crypto/tls、https://pkg.go.dev/crypto/x509。