MySQL INET6_ATON 怎样把 IPv6 文本转成二进制

我在整理地址字段时遇到过一个很典型的混入问题：有的记录是 2001:db8::10，有的却带着端口、网段掩码或网卡 zone ID。此时如果直接把文本塞进一个字符串字段，后续查询很难统一。MySQL 的 INET6_ATON() 可以把合法的 IPv4 或 IPv6 文本转换成二进制值；无效地址或 SQL NULL 输入会得到 NULL。

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

我的做法是把它拆成四步：先清理输入格式，再调用 INET6_ATON()，用 HEX() 和长度确认结果，最后用 VARBINARY 保存。需要给人看时再用 INET6_NTOA() 转回文本，而不是把二进制结果直接当字符串展示。

要把 IPv6 文本转换成 MySQL 二进制值，直接使用 INET6_ATON(ip_text)。合法 IPv4 通常得到 4 字节，合法 IPv6 得到 16 字节；带端口、网段掩码或 zone ID 的字符串不要直接传入，先拆出纯地址，否则结果可能是 NULL。

调用之前先把输入边界分清

INET6_ATON() 接收的是地址文本，不是完整的网络连接地址。下面几类字符串外形相似，含义却不同：

• 192.0.2.10 和 2001:db8::10 是可以尝试转换的纯地址。
• 2001:db8::10:443 不能凭外观判断为“IPv6 加端口”，它也可能被误当成地址文本；端口应在进入函数前单独保存。
• 2001:db8::/64 是带网段掩码的 CIDR，不是单个主机地址。
• fe80::3%en0 带 zone ID，MySQL 文档列出的地址转换约束不接受这种尾部标识。

-- 只把纯 IP 文本送入转换函数，端口和掩码应在应用层单独拆列
SELECT
  INET6_ATON('192.0.2.10') AS ipv4_binary,
  INET6_ATON('2001:db8::10') AS ipv6_binary,
  INET6_ATON('2001:db8::/64') AS cidr_result;

-- 用 NULL 结果暴露输入清洗问题，不要把失败值静默写成空字符串
SELECT
  CASE
    WHEN INET6_ATON(:ip_text) IS NULL THEN '地址格式需要先处理'
    ELSE '可以继续保存二进制值'
  END AS decision;

这里的 :ip_text 代表应用绑定参数。实际项目中应在应用层识别端口和 CIDR，再把纯地址传给 SQL；不要在 SQL 里用一串不透明的字符串替换规则猜测 IPv6 的端口边界。

用 INET6_ATON 转换并判断 NULL

转换函数的结果是二进制字符串。对合法 IPv4，官方文档说明结果类型为 VARBINARY(4)；对合法 IPv6，结果类型为 VARBINARY(16)。输入本身是 SQL NULL，或者文本不是函数能接受的有效地址时，函数结果也会是 NULL。

-- 用显式列名区分原始文本、转换结果和失败原因
SELECT
  :ip_text AS input_text,
  INET6_ATON(:ip_text) AS address_binary,
  CASE
    WHEN :ip_text IS NULL THEN '输入是 SQL NULL'
    WHEN INET6_ATON(:ip_text) IS NULL THEN '输入不是可接受的 IP 地址'
    ELSE '转换成功'
  END AS conversion_status;

排查时我会把“原始输入”和“转换状态”一起记录，这样不会把三种情况混为一谈：字段本来为空、输入被清洗成空值、输入有内容但格式无效。对批量导入尤其重要，因为只看转换后的列很难追溯是哪一类数据出了问题。

用 HEX 和长度看懂二进制结果

二进制字段不适合直接在终端或管理页面里阅读。检查时可以用 HEX() 把每个字节显示为十六进制字符串，再用 OCTET_LENGTH() 查看实际字节数。IPv4 的十六进制结果通常有 8 个字符，IPv6 通常有 32 个字符，但最终判断应以字节长度为准。

-- HEX 只用于诊断展示，OCTET_LENGTH 才是二进制长度判断
SELECT
  '192.0.2.10' AS input_text,
  HEX(INET6_ATON('192.0.2.10')) AS hex_value,
  OCTET_LENGTH(INET6_ATON('192.0.2.10')) AS byte_length;

SELECT
  '2001:db8::10' AS input_text,
  HEX(INET6_ATON('2001:db8::10')) AS hex_value,
  OCTET_LENGTH(INET6_ATON('2001:db8::10')) AS byte_length;

这两条查询的作用是帮助确认“转换确实发生了”，不是给业务代码增加重复计算。生产表里如果已经保存了转换结果，检查现有列即可；不要为了展示而把二进制值永久改成十六进制文本，因为那会改变存储形态和索引长度。

用 VARBINARY 保存，需要展示时再转回文本

如果地址需要参与等值查询、去重或索引，通常可以把转换结果保存到二进制列，而不是把不同写法的文本直接作为唯一值。字段长度可以按业务选择统一的 VARBINARY(16)，也可以根据是否混合保存 IPv4 与 IPv6 设计更细的模型。关键是先确定一个契约：传入列的值必须已经是 INET6_ATON() 的结果。

-- 二进制列统一预留 IPv6 的最大地址长度
CREATE TABLE client_endpoint (
  id BIGINT UNSIGNED PRIMARY KEY,
  address_text VARCHAR(45) NOT NULL,
  address_bin VARBINARY(16) NOT NULL,
  KEY idx_address_bin (address_bin)
);

-- 写入时保留原始文本用于审计，同时保存可比较的二进制值
INSERT INTO client_endpoint (id, address_text, address_bin)
VALUES (:id, :ip_text, INET6_ATON(:ip_text));

-- 给读者展示时再把二进制值转回标准化文本
SELECT id, INET6_NTOA(address_bin) AS normalized_address
FROM client_endpoint
WHERE address_bin = INET6_ATON(:ip_text);

示例保留了 address_text，是为了说明和审计；如果业务不需要原文，可以只保留二进制值。无论选择哪种模型，都不要忽略插入前的 NULL 检查：如果列是 NOT NULL，无效输入会在写入时暴露；如果列允许为空，错误数据可能会悄悄变成缺失值。

IPv4、IPv6 和反向转换有哪些细节

INET6_ATON() 不只处理 IPv6，也可以处理 IPv4。二者的二进制长度不同，所以应用层读取时不能假定所有地址都是 16 字节。若要把二进制值恢复为可读文本，可以使用 INET6_NTOA()；它的输入应当是 INET6_ATON() 产生的二进制地址。

-- 先比较两种地址的长度，再反向转回文本
SELECT
  OCTET_LENGTH(INET6_ATON('198.51.100.7')) AS ipv4_bytes,
  OCTET_LENGTH(INET6_ATON('2001:db8:1::7')) AS ipv6_bytes;

SELECT
  INET6_NTOA(INET6_ATON('198.51.100.7')) AS ipv4_text,
  INET6_NTOA(INET6_ATON('2001:db8:1::7')) AS ipv6_text;

反向转换适合报表、日志或接口响应的展示，不代表原始输入的每个字符会被原样保留。IPv6 可以有多种等价书写方式，标准化输出的价值是让同一个地址有稳定的展示形式；如果还需要保留用户输入，就另存原始文本。

我会把这五项放进导入清单

1. 先确认输入字段是纯 IP，端口、CIDR 掩码和 zone ID 不与地址混在同一列。
2. 调用 INET6_ATON() 后立即判断 NULL，不要把无效值当成空地址。
3. 用 OCTET_LENGTH() 区分 4 字节 IPv4 和 16 字节 IPv6，调试时再用 HEX()。
4. 二进制值用 VARBINARY 保存，需要展示时使用 INET6_NTOA()。
5. 批量迁移时统计转换失败的原始值，先修正数据契约，再决定是否允许空值或回滚导入。

如果你的目标只是查询一列文本里的 IP，直接在查询里调用转换函数即可；如果地址会被频繁比较、去重或建立索引，更适合在写入阶段完成转换，把二进制结果作为明确的数据模型。这样既保留了 IPv6 的完整 16 字节，也不会把“展示格式”和“比较格式”混为一谈。

相关问题

为什么 INET6_ATON 返回 NULL？常见原因是输入包含端口、CIDR 掩码、zone ID，或者文本本身不是 MySQL 接受的地址格式；也可能是输入就是 SQL NULL。

IPv4 一定要单独用 INET_ATON 吗？不一定。INET6_ATON() 可以处理 IPv4，并返回对应的二进制表示；是否单独使用取决于现有数据模型和兼容需求。

为什么不直接保存十六进制字符串？十六进制适合排查和日志，不是最紧凑的地址存储形式。需要比较或索引时，直接保存二进制值更容易保持统一的数据类型。

INET6_NTOA 会还原用户输入的原样格式吗？它用于把二进制地址转成可读文本，重点是表达同一个地址，不应当当作原始字符串的无损回显；需要原样审计时请另存输入文本。