MySQL IS_IPV4_MAPPED 怎样识别映射形式的 IPv6 地址

MySQL 里要识别一个地址是不是 IPv4-mapped IPv6，最稳妥的写法是把文本先交给 INET6_ATON()，再把返回值传给 IS_IPV4_MAPPED()：

-- 先把文本地址转成 MySQL 的二进制网络地址，再判断是否为 ::ffff:IPv4
SELECT IS_IPV4_MAPPED(INET6_ATON('::ffff:192.0.2.10')) AS is_mapped;
-- 结果为 1

IS_IPV4_MAPPED() 不是直接解析普通字符串的函数，它接收的是 INET6_ATON() 产生的二进制地址。匹配 ::ffff:IPv4 返回 1，不匹配返回 0，输入为 NULL 时返回 NULL。

官方地址：https://dev.mysql.com/doc/refman/8.4/en/miscellaneous-functions.html

为什么要先调用 INET6_ATON

INET6_ATON() 把 IPv4 或 IPv6 文本转换成网络字节序的二进制值：IPv4 通常是 4 字节，IPv6 是 16 字节。IS_IPV4_MAPPED() 的参数语义建立在这个数值表示上，因此不能把带冒号的字符串直接当作它的判断输入。

-- HEX 只用于观察转换后的二进制内容，不改变判断逻辑
SELECT
  HEX(INET6_ATON('::ffff:192.0.2.10')) AS mapped_hex,
  IS_IPV4_MAPPED(INET6_ATON('::ffff:192.0.2.10')) AS is_mapped;
-- mapped_hex 是地址的二进制十六进制展示，is_mapped 为 1

地址文本如果无法被 INET6_ATON() 识别，转换结果会是 NULL；这时后面的判断也会落到 NULL。因此，业务上要区分“不是 mapped”和“输入无法解析”，不能只把所有非 1 的值显示成否定。

最小判断配方：mapped、compatible 和普通 IPv6

IPv4-mapped 地址的形式是 ::ffff:IPv4。例如 ::ffff:192.0.2.10 会返回 1；看起来相近的 IPv4-compatible 地址 ::192.0.2.10 没有 ffff 这一段，应该返回 0。

-- 通过同一条表达式对比两种容易混淆的 IPv6 形式
SELECT
  IS_IPV4_MAPPED(INET6_ATON('::ffff:192.0.2.10')) AS mapped_result,
  IS_IPV4_MAPPED(INET6_ATON('::192.0.2.10')) AS compatible_result,
  IS_IPV4_MAPPED(INET6_ATON('2001:db8::10')) AS normal_ipv6_result;
-- 结果依次为 1、0、0

IPv4 部分也可以用十六进制表示。::ffff:c000:020a 与 ::ffff:192.0.2.10 表示同一类映射结构，因此不要只用字符串前缀判断。

用 CASE 保留 NULL 的含义

实际表里常见三类数据：合法的 mapped 地址、合法但不是 mapped 的地址，以及空值或解析失败值。推荐先保留函数原始结果，再用 CASE 给页面或报表添加可读标签：

-- 把 1、0、NULL 分别映射为可读标签，避免把未知输入误报成普通 IPv6
SELECT
  client_ip,
  CASE IS_IPV4_MAPPED(INET6_ATON(client_ip))
    WHEN 1 THEN 'ipv4-mapped'
    WHEN 0 THEN 'not-mapped'
    ELSE 'invalid-or-null'
  END AS ip_kind
FROM access_log;

这里的 ELSE 同时覆盖两种情况：client_ip 为 NULL，或者文本不是 MySQL 能转换的有效网络地址。如果这两类数据需要分开统计，可以先判断 client_ip IS NULL，再判断 INET6_ATON(client_ip) IS NULL。

放进 WHERE 条件时要注意三值逻辑

如果目标只是筛出 mapped 地址，条件可以直接写成：

-- 只保留能确定为 IPv4-mapped IPv6 的记录
SELECT id, client_ip
FROM access_log
WHERE IS_IPV4_MAPPED(INET6_ATON(client_ip)) = 1;

NULL = 1 不是 true，所以空值和无法转换的值不会被筛进来。相反，如果你要找“不是 mapped 或者无法识别”的记录，不能只写 ... = 0，因为这样会漏掉 NULL：

-- 明确把未知输入纳入排查范围；注释说明 OR 的目的
SELECT id, client_ip
FROM access_log
WHERE IS_IPV4_MAPPED(INET6_ATON(client_ip)) = 0
   OR IS_IPV4_MAPPED(INET6_ATON(client_ip)) IS NULL;

数据量较大时，建议在查询层先完成格式清洗或建立适合业务的生成列，再围绕生成结果设计索引；不要在没有测量的情况下假定函数表达式一定能直接复用普通列索引。

一张表记住返回结果

常见问题

IS_IPV4_MAPPED 能直接接收字符串吗？

不建议这样写。按该函数的参数语义，应先用 INET6_ATON() 把文本地址转换为二进制形式，再交给判断函数。

为什么 IPv4-mapped 返回 1，IPv4-compatible 返回 0？

两者的前缀结构不同：mapped 使用 ::ffff:，compatible 使用 :: 加 IPv4 部分。函数判断的是地址结构，不是“里面包含 IPv4”这一宽泛条件。

如何区分无效地址和普通 IPv6？

先看 INET6_ATON(value) 是否为 NULL。转换成功后再看 IS_IPV4_MAPPED(...) 的 0 或 1；不要把这两个步骤合成一个只返回布尔值的展示字段。

记忆这条链路即可：文本地址先转换，映射形式再判断，查询条件明确处理 NULL。这样既能识别 ::ffff:IPv4，也不会把 compatible、普通 IPv6 和无法解析的输入混在一起。