Go crypto/x509.Certificate.VerifyHostname 怎样检查证书是否匹配主机名

排查 Go HTTPS 客户端的证书错误时，我最容易先入为主地把“证书不可信”和“证书名字不匹配”当成一件事。实际上，crypto/x509.Certificate.VerifyHostname 只负责检查一张已经解析出来的证书，是否覆盖给定的 DNS 主机名或 IP 地址；它不会替你建立信任链，也不负责判断证书是否被吊销。

官方文档：https://pkg.go.dev/crypto/x509#Certificate.VerifyHostname

最短结论：DNS 主机名对照证书的 DNSNames，IP 地址对照 IPAddresses；通配符只能是完整的最左侧标签，旧式 Common Name 不参与这个判断。

先分清“名字匹配”和“证书可信”

如果只想回答“这张证书能不能用于 api.example.com”，调用 cert.VerifyHostname("api.example.com") 就够了。返回 nil 表示名称匹配，返回错误表示名称不匹配。

但这并不等于证书可以安全用于生产连接。证书链是否能追溯到信任根、是否过期、用途是否合适，属于 Certificate.Verify 和 x509.VerifyOptions 的职责。把两个 API 混在一起，常见结果就是：链验证通过了，却拿着错误的主机名继续连接；或者名字匹配了，却没有验证签发者。

VerifyHostname 实际检查哪些字段

官方规则可以压缩成两条。传入值是 IP 地址时，检查证书的 IPAddresses；传入值是普通主机名时，大小写不敏感地检查 DNSNames。IP 地址允许写成方括号包围的形式，例如 [2001:db8::10]。

主机名匹配支持完整的左侧通配符，例如证书包含 *.example.com 时，可以匹配 api.example.com，但不能把它理解成任意层级的通配符。deep.api.example.com 多了一层，不能因为字符串后缀相同就直接判定匹配。

还有一个兼容边界：旧式证书的 Common Name 会被忽略。只在 Subject.CommonName 里写入域名，不能替代现代证书的 DNSNames 或 IPAddresses。

用一个小函数把匹配结果说清楚

实际业务里通常不应该把底层错误原样散落在各处。可以把证书和目标主机交给一个小函数，明确返回“匹配”“名称不匹配”或“证书对象为空”三种结果。下面的代码只依赖已经解析好的证书，不创建网络连接。

package main

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

// matchCertificateName 只判断证书身份字段是否覆盖目标主机。
func matchCertificateName(cert *x509.Certificate, host string) error {
    // 解析失败或证书没有装载时，先返回调用方可识别的错误。
    if cert == nil {
        return errors.New("证书对象为空")
    }

    // VerifyHostname 负责 DNS/IP 名称匹配，不负责信任链验证。
    if err := cert.VerifyHostname(host); err != nil {
        var hostnameErr x509.HostnameError
        if errors.As(err, &hostnameErr) {
            return fmt.Errorf("主机名 %q 与证书不匹配: %w", host, err)
        }
        return fmt.Errorf("检查主机名 %q 失败: %w", host, err)
    }
    return nil
}

这里用 errors.As 区分 x509.HostnameError，是为了让上层日志知道这是名称字段问题，而不是把所有 x509 错误都归到同一个提示里。代码没有调用 Verify，因此不能把返回 nil 解释为“证书链可信”。

DNS 名称和 IP 地址不要用同一套字段

我在迁移内部服务域名时见过一个很隐蔽的误判：配置里把服务写成了 IP，但证书只在 DNSNames 中列出一个名字。即使这两个地址最终指向同一台机器，VerifyHostname 也不会替业务做 DNS 解析或反向推断，IP 输入必须在 IPAddresses 中有对应值。

package main

import (
    "crypto/x509"
    "fmt"
)

func printMatch(cert *x509.Certificate, targets []string) {
    for _, target := range targets {
        // 目标是 IP 时，库会按 IPAddresses 语义检查，而不是按 DNSNames 查找。
        err := cert.VerifyHostname(target)
        if err != nil {
            // 保留目标值，便于定位配置到底使用了域名还是字面量 IP。
            fmt.Printf("%s: 不匹配（%v）\n", target, err)
            continue
        }
        fmt.Printf("%s: 匹配\n", target)
    }
}

如果你的服务配置允许域名和 IP 两种写法，应在签发证书时分别写入 SAN，而不是在客户端把 IP 转成某个猜测的域名。代码层面也不需要先调用 net.LookupHost 再拼接结果，因为那会把“证书身份匹配”和“当前 DNS 解析结果”混成两个不同问题。

通配符只覆盖完整的最左侧标签

*.example.com 的语义不是“只要以 example.com 结尾都算”。它代表一个左侧标签，所以 www.example.com 这类单层名称可以匹配，而 a.b.example.com 不应当被当作同一层。相应地，通配符也不能替代 IP 地址匹配。

这也是不建议手写 strings.HasSuffix 判断证书域名的原因。后缀比较无法表达标签边界、大小写规则和 IP 字段差异，最终容易放宽证书覆盖范围。把规则交给 VerifyHostname，业务代码只处理成功与错误分类即可。

Common Name 为什么不能继续当作兜底字段

有些旧证书看起来在主题字段里写了正确域名，但 VerifyHostname 仍然返回不匹配。原因不是 Go 忘了读取字段，而是现代规则明确忽略 legacy Common Name。证书应该把可用于主机名验证的值放到 SAN 对应的 DNS 或 IP 字段中。

如果只能接入一张历史证书，建议把问题记录为证书签发或替换事项，而不是在业务侧重新实现一套“Common Name 也算”的宽松匹配。自行放宽会让不同客户端的验证行为不一致，也会掩盖真正的证书配置问题。

什么时候应该改用 Certificate.Verify

当需求从“名称是否匹配”升级为“这张证书是否能被当前信任环境接受”，就应该使用 Certificate.Verify。它可以配合 x509.VerifyOptions 提供 DNSName、根证书池和中间证书池，并返回证书链；而 VerifyHostname 更适合单独测试 SAN、在自定义握手流程中做名称边界判断，或把底层名称错误转换成业务诊断。

落地时记住这五件事

1. 调用前确认 *x509.Certificate 已经成功解析，不要把空指针当成主机名错误。
2. DNS 输入看 DNSNames，IP 输入看 IPAddresses，不要自行做字段转换。
3. 通配符只能覆盖完整的最左侧标签，不能用字符串后缀比较代替库规则。
4. Common Name 被忽略时，优先修复证书 SAN，不要在客户端偷偷放宽规则。
5. 需要信任链、根证书或有效性判断时，改用 Certificate.Verify，并记录两类检查的结果。

常见问题

VerifyHostname 会检查证书是否过期吗？

不会。它的返回值只说明名称是否匹配。证书有效期、信任根和用途等问题应由完整的证书验证流程处理。

证书写了 *.example.com，可以匹配 a.b.example.com 吗？

不能按通配符的常见语义直接这样推断。通配符是完整的最左侧标签，不能覆盖任意深度的子域层级。

为什么 Common Name 写对了仍然失败？

因为现代 Go x509 主机名匹配忽略 legacy Common Name。请检查证书的 DNS SAN 或 IP SAN 是否包含真正使用的目标值。

传入 IPv6 地址时能带方括号吗？

官方文档允许 IP 地址可选地放在方括号中。无论使用哪种形式，都应保证它表达的是 IP 地址，而不是 DNS 名称字符串。

总结

Certificate.VerifyHostname 解决的是一个很窄但很关键的问题：证书身份字段是否覆盖当前主机名。把 DNS、IP、通配符和 Common Name 的边界交给标准库，再把名称匹配与信任链验证分开，HTTPS 证书排查就不会陷入“看起来域名一样却不知道错在哪”的循环。