Go TLS 证书校验失败但浏览器正常怎么办

Go 里遇到 TLS 证书校验失败，但同一个地址在浏览器里能打开，最常见的原因不是“Go 不支持这张证书”，而是两边拿来校验的主机名不同：浏览器通常把 URL 中的域名同时用于连接、SNI 和证书主机名校验；Go 程序却可能为了访问内网服务而直接拨号到 IP，结果证书颁发给 api.example.com，程序却拿 IP 或另一个别名去核对。

先把拨号地址、SNI/ServerName 和证书 SAN 分开核对。需要直连 IP 时，让 ServerName 保持为证书中的域名，并继续保留默认证书校验；如果错误是根证书不受信任，单独设置 ServerName 也不能解决。

• 证书名称不匹配：检查 tls.Config.ServerName 与证书的 DNS SAN 或 IP SAN。
• 根证书不受信任：检查系统根证书、企业 CA 或中间证书链。
• 虚拟主机选错：检查 SNI 是否让服务端返回了另一张证书。
• 端口或协议不对：确认拨号端口确实提供 TLS，而不是明文 HTTP。

先分清浏览器和 Go 到底校验了什么

一条 HTTPS 请求里至少有三类名称或地址：网络连接要去的 host:port，TLS 握手里的 SNI/ServerName，以及服务端证书允许的主机名。它们在常见公网访问中往往恰好相同，所以问题不明显；在内网代理、负载均衡、服务发现或测试环境里，拨号地址经常变成 IP，而证书身份仍然是域名。

直连 IP 时把 ServerName 设为证书域名

tls.Config.ServerName 在客户端连接中承担两个关键职责：作为客户端握手的 SNI（当它不是 IP 地址时），以及作为返回证书的主机名校验目标。因此，程序可以把连接路由到固定 IP，同时把证书身份保留为域名。

下面的 DialContext 只改网络连接的落点，HTTP 请求 URL 仍然使用服务证书对应的域名。示例地址是文档中的保留地址，不代表真实服务；实际项目应替换成自己的解析结果和证书名称。

package main

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

func main() {
    // 连接落到固定 IP，但证书身份仍使用域名。
    endpoint := "203.0.113.10:443"
    serverName := "api.example.com"

    transport := &http.Transport{
        // ServerName 用于 SNI 和服务端证书的主机名校验。
        TLSClientConfig: &tls.Config{
            ServerName: serverName,
            MinVersion: tls.VersionTLS12,
        },
        // 只替换拨号地址，不关闭 TLS 默认校验。
        DialContext: func(ctx context.Context, network, _ string) (net.Conn, error) {
            dialer := &net.Dialer{Timeout: 5 * time.Second}
            return dialer.DialContext(ctx, network, endpoint)
        },
    }

    client := &http.Client{Transport: transport, Timeout: 10 * time.Second}
    resp, err := client.Get("https://api.example.com/health")
    if err != nil {
        panic(err)
    }
    // 请求完成后关闭并读尽响应体，避免连接资源长期占用。
    defer resp.Body.Close()
    _, _ = io.Copy(io.Discard, resp.Body)
}

这个组合成立的前提是：证书确实包含 api.example.com，对应根证书在客户端信任范围内，而且该 IP 上的 TLS 服务会根据 SNI 返回正确的证书。如果证书只包含某个 IP，那么才应按 IP 的证书规则核对；不要为了迁就错误名称而随意填写一个域名。

用错误类型判断是名称问题还是信任链问题

只看错误字符串容易把不同问题混在一起。Go 的 crypto/x509 提供了可判断的错误类型：x509.HostnameError 通常表示证书名称与目标主机不匹配，x509.UnknownAuthorityError 表示无法找到受信任的签发链。两者的修复动作完全不同。

package main

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

func explainTLSError(err error) {
    if err == nil {
        return
    }

    var hostnameErr x509.HostnameError
    if errors.As(err, &hostnameErr) {
        // 名称不匹配时，检查 ServerName 与证书 DNSNames/IPAddresses。
        fmt.Println("证书主机名不匹配，请核对 ServerName 和 SAN")
        return
    }

    var authorityErr x509.UnknownAuthorityError
    if errors.As(err, &authorityErr) {
        // 信任链问题应补齐正确 CA，而不是关闭证书校验。
        fmt.Println("证书签发者不受信任，请核对根证书或中间证书")
        return
    }

    // 其他错误还可能指向端口、协议、时间或握手参数。
    fmt.Printf("TLS 连接失败：%v\n", err)
}

HTTP URL、DialContext 和 ServerName 要各司其职

自定义 Transport 时，建议把三件事分别写清楚：

• 请求 URL：表达业务要访问的主机名，通常也会成为 HTTP 的 Host 语义。
• DialContext：决定实际网络连接落到哪个地址，可用于固定 IP、服务发现或代理转发。
• TLSClientConfig.ServerName：决定 SNI 和证书主机名校验使用的身份。

如果三者应该相同，就不要过度定制，直接让默认的 http.Transport 根据 URL 工作。如果三者必须不同，就在代码旁边记录原因，并把证书名称写进配置或服务发现契约。这样排查时可以迅速回答“连接到了谁”“SNI 请求了谁”“证书证明了谁”。

不要用 InsecureSkipVerify 掩盖名称错误

InsecureSkipVerify: true 会跳过客户端对服务端证书链和主机名的默认校验。它可能让请求暂时“连通”，却无法证明连接到了正确的服务，也不能替代正确的 SNI、证书 SAN 或 CA 配置。生产代码应优先修正 ServerName、证书签发范围和信任链。

只有在确实需要自定义验证流程时，才应设计完整的 VerifyConnection 或等价校验逻辑，并明确验证根证书、用途和主机名；不要只设置一个回调就把默认安全检查全部删掉。

排查清单

1. 确认 Go 实际拨号的地址和端口是否提供 TLS。
2. 从服务端证书查看 DNS SAN 与 IP SAN，不把 Common Name 当成唯一依据。
3. 检查 ServerName 是否是证书中的合法名称，并确认 SNI 没有被 IP 替代。
4. 区分 HostnameError 与 UnknownAuthorityError，分别处理名称和信任链。
5. 保留默认证书校验，修复配置后再做一次应用层请求。

常见问题

把 ServerName 设置成 IP 就一定正确吗？

不一定。只有证书的 IP SAN 包含该 IP 时，IP 才能通过主机名校验；许多内网服务的证书只签给域名，此时应使用证书域名作为 ServerName。

浏览器能打开，是否说明 Go 的根证书一定有问题？

不说明。浏览器正常只能证明浏览器使用的连接、SNI、证书链和校验输入能够匹配；Go 还可能是拨号 IP、ServerName 或运行环境根证书不同。

ServerName 正确但仍然报 UnknownAuthorityError 怎么办？

继续检查客户端信任的根 CA、服务端是否发送完整中间证书，以及测试环境是否使用了企业私有 CA。ServerName 只解决身份名称，不会自动增加信任根。

资料参考：https://pkg.go.dev/crypto/tls#Config、https://pkg.go.dev/crypto/tls#ConnectionState、https://pkg.go.dev/crypto/x509#Certificate.VerifyHostname。