Go netip.ParseAddr 对 IPv4 映射地址的表示为什么不一致

这个现象不是 netip.ParseAddr 解析错了，而是它保留了输入地址的身份：::ffff:192.0.2.1 会被当作 IPv4 映射的 IPv6 地址。于是 Is4() 返回 false，Is4In6() 返回 true，String() 仍然带着 ::ffff: 前缀。需要按 IPv4 处理时，显式调用 Unmap() 即可。

判断地址类别看 Is4In6，需要统一成 IPv4 再调用 Unmap；不要用 String() 的外观代替类型判断。

先看地址内部的两种身份

netip.Addr 同时记录地址的数值和它属于 IPv4 还是 IPv6 表示。IPv4 映射地址落在 ::ffff:0:0/96 范围内，因此它在语义上包着一个 IPv4，但在地址类型上仍是 IPv6。

package main

import (
    "fmt"
    "net/netip"
)

func main() {
    // 这个输入是 IPv4-in-IPv6，不是普通的四段式 IPv4。
    addr, err := netip.ParseAddr("::ffff:192.0.2.1")
    if err != nil {
        // 解析失败时不要继续使用零值 Addr。
        panic(err)
    }

    // 四个判断分别观察类型身份、映射关系和地址宽度。
    fmt.Println(addr.Is4(), addr.Is4In6(), addr.Is6(), addr.BitLen())
    fmt.Println(addr.String(), len(addr.AsSlice()))
}

这里最容易误判的是 Is6()。文档明确说明 IPv4 映射地址也算 IPv6，所以这几个结果并不互相矛盾：Is4=false、Is4In6=true、Is6=true，位宽为 128，AsSlice() 也返回十六字节表示。

String 为什么保留 ::ffff: 前缀

netip.Addr.String() 的职责是格式化当前 Addr，不是替调用方做地址规范化。官方文档特别区分了 netip 与 net.IP.String：映射地址在 netip 中会格式化为 ::ffff:1.2.3.4，因此输出前缀是有意保留的信息。

所以不要写“字符串以点分十进制结尾，就一定是 IPv4”。如果日志、缓存键或协议字段要求保留来源形态，直接使用 String()；如果业务只关心终端 IPv4，则先统一地址再格式化。

需要统一比较结果时调用 Unmap

Unmap() 只在地址确实是 IPv4 映射 IPv6 时移除映射前缀，返回真正的 IPv4 Addr；对普通 IPv4 或普通 IPv6，它保持原值不变。这个转换是显式的，因此适合放在边界层，而不是散落在每个比较点。

func canonicalIPv4(addr netip.Addr) (netip.Addr, bool) {
    // 先识别映射地址，避免把普通 IPv6 误当成 IPv4。
    if addr.Is4In6() {
        addr = addr.Unmap()
    }
    // 映射地址经过 Unmap 后才会满足 Is4。
    return addr, addr.Is4()
}

func sameIPv4(a, b netip.Addr) bool {
    // 只在调用方明确要求 IPv4 等价时做统一比较。
    aa, aOK := canonicalIPv4(a)
    bb, bOK := canonicalIPv4(b)
    return aOK && bOK && aa == bb
}

如果业务允许 IPv4 和 IPv4-in-IPv6 视为同一终端地址，可以在接收请求、读取代理头或加载配置时统一一次，再把规范化后的 Addr 传入后续逻辑。若业务需要区分两种网络层表示，则不要调用 Unmap，而应保留原值并使用 Is4In6() 做分支。

As4、AsSlice 和 map key 怎么选

还有一个细节：As4() 对 IPv4 映射地址可以取出包裹的四字节，但它不会改变原来的 Addr。如果后续还要调用 String()、BitLen() 或把地址作为 map key，应该保存 Unmap() 的返回值，而不是只保存 As4() 的数组。

常见误区与快速结论

• 误区一：看到末尾是 192.0.2.1 就认为 Is4() 为真。应先判断 Is4In6()。
• 误区二：为了让字符串“好看”直接截掉 ::ffff:。应使用 Unmap().String()，避免破坏地址语义。
• 误区三：把 AsSlice() 的长度当成地址类别的唯一判断。映射地址是十六字节，类型判断仍应使用方法。

如果只是记录和展示，保留 ParseAddr 的原始身份；如果要做 IPv4 白名单、统一缓存键或 IPv4 计数，先在边界处 Unmap，再比较、序列化或统计。这样就不会把“IPv4 数值相同”和“网络层表示相同”混为一谈。

相关问题

为什么 netip.AddrFrom16 没有自动变成 IPv4？ 因为它按十六字节输入构造 IPv6 表示，文档要求映射地址保持 IPv6 身份；需要转换时调用 Unmap。

普通 IPv6 调用 Unmap 会不会被改写？ 不会。只有命中 IPv4 映射范围时才移除前缀，其他地址原样返回。

比较两个地址前一定要 Unmap 吗？ 不一定。是否统一取决于业务语义：要比较终端 IPv4 就统一，要区分 IPv4-in-IPv6 与 IPv4 就保留原始 Addr。