Go TLS 握手为什么提示证书主机名不匹配

Go TLS 握手提示证书主机名不匹配，通常不是“证书没有加密能力”，而是客户端拿来连接的名称没有出现在证书允许的名称集合中。先核对请求 URL、SNI 和证书的 SAN，再决定改证书、改连接名称还是修正代理配置；不要先把 InsecureSkipVerify 打开。

一、先分清“链不可信”和“名称不匹配”

这类错误常见于 x509: certificate is valid for ... not ...。它说明 Go 已经拿到了证书，并在验证证书是否适用于目标主机时失败。若错误是 unknown authority，排查重点才是根证书、私有 CA 或证书链；两者不能用同一个参数修复。

先把错误里的两个名字记下来：valid for 后面是证书声明的名称，not 后面是客户端实际校验的名称。前者可能来自 DNS SAN 或 IP SAN，后者则可能来自 URL、显式的 ServerName，也可能被代理或自定义拨号逻辑间接改变。

二、核对 Go 实际校验的主机名

默认 HTTPS 请求会从 URL 的主机部分推导名称。例如 URL 写成 https://api.example.com/v1，期望证书包含 api.example.com。如果代码把请求拨到 IP，却没有保留服务的域名语义，就可能拿 IP 去匹配一个只包含域名的证书。

自定义 TLS 配置时，ServerName 应该填写证书签发的服务名，而不是随手填成后端 IP。它还会作为 SNI 发给服务端，影响多证书网关返回哪一张证书：

tlsConfig := &tls.Config{
	// 这个名称用于 SNI，也用于服务端证书的主机名校验。
	ServerName: "api.example.com",
}

client := &http.Client{
	// Transport 会复用连接，避免每次请求都重新建立 TLS。
	Transport: &http.Transport{TLSClientConfig: tlsConfig},
}

如果业务必须连接固定 IP，可以让 DNS 解析或自定义拨号负责“连哪个地址”，但仍保留正确的 ServerName。这里解决的是地址路由和身份校验的分离，不是绕过证书检查。

三、查看证书 SAN，注意通配符和 IP 边界

检查证书时重点看 Subject Alternative Name。下面的命令只读取公开服务返回的证书字段，-servername 要写成客户端期望访问的域名，这样多租户网关才会返回相应证书：

# 读取目标站点证书的 SAN，不把输出当作运行截图。
openssl s_client -connect api.example.com:443 -servername api.example.com /null 2>/dev/null \
  | openssl x509 -noout -subject -ext subjectAltName

*.example.com 通常只能覆盖 api.example.com 这一层，不能覆盖 v1.api.example.com；它也不能把域名证书变成 IP 证书。使用 IP 地址连接时，证书需要在 IP SAN 中明确列出该 IP。

Go 的 x509.Certificate.VerifyHostname 会按主机名规则检查证书，旧式 Common Name 不能当作可靠的替代入口。若证书是内部 CA 签发，还要分别确认“链能否被信任”和“名称是否覆盖”，不要把两项混成一个问题。

四、按场景修正配置，而不是关闭验证

只有在自己接管完整校验流程、并明确承担风险时，才会讨论 InsecureSkipVerify 配合自定义验证。对普通客户端来说，它会让主机名校验失效，错误被隐藏后，连接可能确实建立，但身份认证已经失去意义。

五、握手修复后的检查清单

先用真实请求域名测试，再分别覆盖 IP 直连、代理转发和证书轮换。检查日志中最终使用的 URL 主机、ServerName、服务端返回证书的 SAN，以及是否仍存在旧连接复用。若只改了后端证书，却忘记重载网关，客户端看到的仍可能是旧证书。

相关问题

证书包含 api.example.com，为什么访问 IP 仍失败？

因为 IP 需要匹配证书的 IP SAN，DNS SAN 中的域名不会自动等价为这个 IP。应保留域名用于校验，并把网络连接地址单独指向 IP。

修改 ServerName 后能解决所有主机名错误吗？

不能。它只能让客户端选择正确的身份名称；如果证书本身没有该名称，正确做法仍是修证书或修服务端路由。

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

它跳过的是证书链和主机名验证入口，不能证明服务端身份。测试应使用受控测试 CA，生产应修复 SAN、SNI 或拨号配置。