Go IPv4-mapped IPv6 地址为什么没有命中白名单

我在处理一段网络白名单时遇到过一个很像“地址完全一样却查不到”的问题：配置里写的是 192.0.2.10，请求侧拿到的却是 ::ffff:192.0.2.10，直接用 map[netip.Addr]bool 查找会返回未命中。原因不是 map 失效，而是这两个值在 netip.Addr 中仍是不同的地址形态。

netip.Addr 里三种地址身份并不相同

Go 官方的 netip 把地址做成可比较的值类型，因此它可以直接作为 map 的键。但“内容代表同一台主机”不等于“两个 Addr 值完全相等”。普通 IPv4 是 192.0.2.10，映射形式是 ::ffff:192.0.2.10，真正 IPv6 则可能是 2001:db8::10。

判断时不要只看 Is4。官方文档明确说明，IPv4-mapped IPv6 会被视为 IPv6，所以 Is4() 返回 false；应使用 Is4In6() 判断它是否位于 ::ffff:0:0/96，再用 Unmap() 取出包裹的 IPv4。

直接 map 查找未命中，问题在比较键不一致

下面这段代码故意保留了常见的失败写法。白名单键由普通 IPv4 解析得到，请求值则保留了 IPv4-mapped IPv6 形态；两者的字符串和内部身份不同，因此查找结果是 false。

package main

import (
    "fmt"
    "net/netip"
)

func main() {
    // 配置端写入普通 IPv4 地址。
    allow := map[netip.Addr]bool{
        netip.MustParseAddr("192.0.2.10"): true,
    }
    // 请求端可能拿到 IPv4-mapped IPv6 形态。
    requestIP := netip.MustParseAddr("::ffff:192.0.2.10")

    // 两个 Addr 表示的地址身份不同，直接查找不会命中。
    fmt.Println(allow[requestIP], requestIP.Is4(), requestIP.Is4In6())
}

这里的 Is4()、Is4In6() 和 String() 一起看，通常就能把“白名单配置没生效”定位到地址规范化，而不是继续怀疑 map 或网络层。

白名单比较要先统一地址规范

修复点应该放在白名单的统一入口：解析成功后立即调用 Unmap()，再把规范化后的值作为 map 键。Unmap() 只移除 IPv4-mapped IPv6 的前缀，真正 IPv6 会原样返回，所以不会把 IPv6 白名单误变成 IPv4。

package main

import "net/netip"

// canonicalAddr 把两种 IPv4 表示统一成同一个可比较的 Addr。
func canonicalAddr(raw string) (netip.Addr, error) {
    // ParseAddr 负责拒绝非法输入；不要用字符串截断替代解析。
    addr, err := netip.ParseAddr(raw)
    if err != nil {
        return netip.Addr{}, err
    }
    // 映射 IPv4 变回 4 字节 IPv4，真正 IPv6 保持不变。
    return addr.Unmap(), nil
}

func allowed(raw string, whitelist map[netip.Addr]bool) bool {
    // 白名单键和请求值必须走同一个规范化函数。
    addr, err := canonicalAddr(raw)
    if err != nil {
        return false
    }
    return whitelist[addr]
}

配置加载时也要调用同一个函数，而不是只规范化请求侧。这样普通 IPv4、映射 IPv4 会落到同一个键；真正 IPv6 仍按自己的 128 位地址参与比较。

把边界收在解析和比较入口

如果输入来自 netip.AddrPort，先取出地址部分再规范化；不要把 host:port 整串交给 ParseAddr。另外，规范化是比较策略，不代表所有代理链都能提供可信的客户端源地址，信任边界仍应由网络架构单独决定。

常见问题

为什么不用 strings.TrimPrefix 去掉 ::ffff:？

字符串截断无法替代 IP 语法解析，也容易漏掉大小写、非法文本和其他 IPv6 情况。使用 ParseAddr 与 Unmap 能让判断对象保持为类型安全的地址值。

Unmap() 会不会把所有 IPv6 变成 IPv4？

不会。它只处理 IPv4-mapped IPv6；普通 IPv6 地址会原样返回。

白名单 map 的键应该用字符串吗？

通常不必。netip.Addr 可比较且适合做 map 键，关键是配置加载与请求判断必须共享同一套规范化函数。