Go net.IP.Equal 为什么 IPv4 地址可能相等：16 字节表示与映射地址边界

同一个客户端地址在日志里一会儿写成 192.0.2.10，一会儿写成 ::ffff:192.0.2.10，用 Go 比较时不必先把字符串格式强行统一。net.IP.Equal 会把 IPv4 的 4 字节表示和对应的 IPv4-mapped IPv6 16 字节表示视为同一个地址；但如果业务要判断“它原本是 IPv4 还是 IPv6”，就不能只看 Equal 的结果。

IP.Equal 适合判断地址语义是否相同；需要区分表示形式时，先用 To4 取得 4 字节结果，再决定后续策略。

IP.Equal 解决的是地址身份，不是字节长度

下面的例子故意使用同一个地址的两种输入。net.ParseIP 返回的结果通常是 16 字节形式，而 net.IPv4 也会构造出 IPv4-mapped IPv6 表示，因此日志里看到的切片长度未必等于你以为的 4。

package main

import (
    "fmt"
    "net"
)

func main() {
    short := net.IPv4(192, 0, 2, 10)
    mapped := net.ParseIP("::ffff:192.0.2.10")

    fmt.Println(short.Equal(mapped))
    fmt.Println(len(short), len(mapped))
}

第一行会打印 true，后面两个长度可以不同。官方文档明确规定，IPv4 地址与同地址的 IPv6 形式相等；这里的“相等”是地址语义，而不是 Go 切片逐字节相同。图中的 4 字节 IPv4 和 16 字节 IPv4-mapped IPv6 都进入 IP.Equal，最后得到同一地址身份。

To4 如何识别 IPv4-mapped IPv6

To4 的返回值是判断入口：长度为 4 时直接返回 IPv4；长度为 16 时，只有前 10 个字节为零、随后两个字节为 0xff，才会返回最后 4 个字节。源码里的 v4InV6Prefix 就是这段映射前缀。本节的逻辑图把这条路径缩成 16 字节 IP 进入 To4，匹配 v4InV6Prefix 后得到 ip[12:]。

因此，下面两种输入都会得到 4 字节结果，而真正的 IPv6 地址会得到 nil：

func classify(ip net.IP) string {
    if ip4 := ip.To4(); ip4 != nil {
        return fmt.Sprintf("IPv4: %v", ip4)
    }
    return "IPv6"
}

这一步还有一个实用含义：后续白名单、IPv4 网段匹配或日志归一化，应该使用 ip4，不要把 16 字节原值继续传给只接受 4 字节掩码的逻辑。

最容易踩坑的三种比较方式

直接比较字符串

"192.0.2.10" 与 "::ffff:192.0.2.10" 在文本上当然不同。字符串适合展示和日志，不适合承担地址身份判断。先解析为 net.IP，再调用 Equal。

用 bytes.Equal 代替 Equal

逐字节比较会把长度和映射前缀也纳入结果，可能得到与网络语义不一致的结论。如果你的需求就是“底层表示必须完全一致”，可以明确写出来；如果需求是“是不是同一 IP”，就使用 Equal。

把 To4 非空误认为输入原本就是 IPv4

IPv4-mapped IPv6 同样会让 To4 返回非空。这个判断表达的是“可按 IPv4 处理”，不是“输入文本一定是 IPv4”。要保留原始输入的地址族，需要在解析或业务边界另存分类信息。

一个可复查的最小验证

验证时同时打印 Equal、To4 和长度，能把“地址相等”和“表示不同”放在同一屏里：

func main() {
    a := net.ParseIP("192.0.2.10")
    b := net.ParseIP("::ffff:192.0.2.10")

    fmt.Println("Equal:", a.Equal(b))
    fmt.Println("a To4:", a.To4())
    fmt.Println("b To4:", b.To4())
    fmt.Println("lengths:", len(a), len(b))
}

预期是 Equal: true，两个 To4 都表示 192.0.2.10，而长度仍可能都是 16。若改用手工构造的 4 字节切片，长度差异会更明显，但比较结论仍由 Equal 的规则决定。

延伸问答

netip.Addr 是否也需要先转成字符串比较？

不需要。新代码可以优先使用类型更明确的 net/netip，按它提供的地址方法比较；只有在兼容已有 net.IP API 时，才需要处理 4 字节与 16 字节表示的边界。

什么时候应该保存 To4 的结果？

当后续流程明确只接受 IPv4 时保存它，例如 CIDR 匹配、IPv4 黑白名单或固定 4 字节协议字段。若仍需要保留原始地址族，则同时保存原始 net.IP 和归一化后的 To4。

记住一个判断顺序就够了：先问业务要的是“同一个地址”，还是“同一种表示”；前者用 IP.Equal，后者再检查长度和 To4 结果。这样既不会误拒绝 IPv4-mapped IPv6，也不会丢掉协议边界需要的地址族信息。