Go net.ParseIP 解析 IPv4 映射 IPv6 后怎么统一比较

如果用 net.ParseIP 解析 192.0.2.1 和 ::ffff:192.0.2.1，再直接比较切片长度或原始字节，很容易把“同一个 IPv4 地址的两种表示”当成两个对象。更稳妥的做法是：只判断地址语义是否相同，就调用 IP.Equal；需要把 IPv4 地址做成统一键或统一文本，就先调用 To4；只有确实要区分地址族时，才保留 IPv6 形态。

ParseIP 为什么会让 IPv4 看起来像 IPv6

net.ParseIP 接受点分十进制 IPv4、普通 IPv6，以及 ::ffff:192.0.2.1 这种 IPv4-mapped IPv6 文本。它返回的地址统一使用 16 字节形式，IPv4 会放进 IPv4-mapped IPv6 的前缀中。也就是说，下面两个变量在语义上都指向 192.0.2.1，但不要把“文本形式”“切片长度”和“地址语义”混为一谈：

package main

import (
	"fmt"
	"net"
)

func main() {
	plain := net.ParseIP("192.0.2.1")
	mapped := net.ParseIP("::ffff:192.0.2.1")

	// ParseIP 失败时返回 nil，先判断再使用结果。
	if plain == nil || mapped == nil {
		fmt.Println("地址格式无效")
		return
	}

	// 两个地址的 String 都会使用适合 IPv4 的点分形式。
	fmt.Println(plain.String(), mapped.String())
	fmt.Println(len(plain), len(mapped))
}

这里的关键不是记住某个内部数组，而是知道 net.IP 是字节切片，长度并不等于“读者想表达的地址族”。官方文档明确说明，IPv4 地址和 IPv4-mapped IPv6 都可能以 16 字节形式存在。

只想判断是不是同一个地址，直接用 IP.Equal

如果业务问题是“这两个地址是不是同一个 IP”，应使用 IP.Equal。它会处理 4 字节 IPv4、16 字节 IPv4-mapped IPv6 以及长度相同的地址比较，官方语义也明确把 IPv4 和相同地址的 IPv6 形式视为相等：

func sameIP(leftText, rightText string) bool {
	left := net.ParseIP(leftText)
	right := net.ParseIP(rightText)
	if left == nil || right == nil {
		// 任意一侧无法解析，都不能把它当成有效地址相等。
		return false
	}

	// Equal 比较地址语义，会识别 IPv4 与 IPv4-mapped IPv6 的对应关系。
	return left.Equal(right)
}

例如，sameIP("192.0.2.1", "::ffff:192.0.2.1") 的结果是 true；而 sameIP("192.0.2.1", "192.0.2.2") 的结果是 false。这种写法也避免了手动判断前 12 个字节是否是 00...00ffff，减少了自己实现协议细节时的偏差。

需要统一成 IPv4 键时，先调用 To4

有些场景不是简单比较，而是要生成 map 键、日志字段或白名单索引，希望所有 IPv4 语义地址都采用同一份 4 字节数据。这时可以把 To4 作为归一化入口：

func ipv4Key(text string) (string, bool) {
	ip := net.ParseIP(text)
	if ip == nil {
		// 解析失败不产生空键，调用方可以记录输入错误。
		return "", false
	}

	ip4 := ip.To4()
	if ip4 == nil {
		// 真正的 IPv6 没有 IPv4 语义，不能硬转成 IPv4 键。
		return "", false
	}

	// To4 返回 4 字节表示，String 再生成稳定的点分十进制键。
	return ip4.String(), true
}

这样，192.0.2.1 和 ::ffff:192.0.2.1 都会得到同一个键 192.0.2.1。注意 To4 不会把任意 IPv6 地址“压缩”为 IPv4；对于真正的 2001:db8::1，返回值是 nil，这个分支应当由业务明确处理。

不要用切片长度或 bytes.Equal 代替地址语义

直接检查 len(ip) == 4 并不能覆盖所有 IPv4 语义地址，因为 ParseIP 返回的 IPv4 可能是 16 字节映射形式。反过来，先把所有地址都转换成 16 字节再用 bytes.Equal，也只适合你已经明确选择了同一种规范表示的场景，不能代替对输入合法性和地址族的判断。

比较前先决定你要保留什么信息

统一比较并不意味着所有信息都应该丢掉。权限判断、连接来源去重等场景通常关心“是不是同一个地址”，使用 Equal 最直接；IPv4 专属的统计、索引或配置键可以使用 To4；如果协议或审计逻辑必须知道输入是否明确写成 IPv6，则应同时保存原始文本或地址族信息，不能只保存归一化后的字符串。

• 解析失败先返回错误或失败状态，不要让 nil 参与后续业务比较。
• IPv4 与映射 IPv6 视为同一地址时，优先调用 Equal，不要维护手写前缀常量。
• 需要 IPv4 键时检查 To4() == nil，真正 IPv6 应进入单独分支。
• 如果要追踪用户输入，原始字符串和规范化地址应分别保存。

常见问题

ParseIP("192.0.2.1") 得到的是 IPv4 还是 IPv6？

从语义上它是 IPv4；从返回切片的存储形式看，通常是 16 字节的 IPv4-mapped IPv6。判断 IPv4 语义应使用 To4，不要只看长度。

为什么不直接比较 ip.String()？

对已经成功解析的 IPv4 与映射 IPv6，String 通常会给出相同的点分文本，但字符串比较表达的是格式化结果；业务要判断地址相等时，IP.Equal 的意图更明确，也不会把格式化策略当成比较协议。

To4 返回的切片需要复制吗？

如果只是立即读取或调用 String，通常不需要复制；如果要长期保存并且底层 net.IP 可能被复用或修改，应复制所需字节，避免把可变切片的生命周期带出当前边界。