Go 用 netip 解析 IPv6 地址失败怎么办

Go 用 netip.ParseAddr 解析 IPv6 失败，通常不是 IPv6 不能压缩，而是把不同类型的文本交给了错误的入口。纯地址和带接口 Zone 的文本可以交给 ParseAddr；如果字符串还包含端口，应该改用 netip.ParseAddrPort。先按这个边界分流，再处理错误，往往比手写冒号和百分号替换更可靠。

官方文档入口：https://pkg.go.dev/net/netip。本文的示例用于解释 API 边界和预期结果，不是运行截图或本机测试记录。

结论：2001:db8::68 和 fe80::1%ens18 是地址文本，可用 ParseAddr；[2001:db8::1]:443 是地址加端口，应使用 ParseAddrPort。

先把输入分成三类

netip 的 Addr 是一个可比较的值类型，表示 IPv4 或 IPv6 地址，也可以带 scoped addressing zone。最容易误判的是把“地址加端口”当成“地址”传入：IPv6 自身就含有冒号，所以端口文本通常需要方括号来消除歧义。

纯 IPv6 和 Zone 的最小写法

package main

import (
    "fmt"
    "net/netip"
)

func main() {
    samples := []string{
        "2001:db8::68", // 双冒号压缩的普通 IPv6 地址。
        "fe80::1%ens18", // 链路本地地址，百分号后是接口 Zone。
    }

    for _, text := range samples {
        addr, err := netip.ParseAddr(text)
        if err != nil {
            // 保留原始输入，便于日志定位是格式还是来源数据的问题。
            fmt.Printf("parse %q: %v\n", text, err)
            continue
        }
        // Zone 只描述作用域；地址主体仍可通过 String 和 Zone 分开读取。
        fmt.Printf("addr=%s zone=%q ipv6=%t\n", addr, addr.Zone(), addr.Is6())
    }
}

这段代码的关键是不要先把 :: 展开成八组，也不要为了去掉百分号而截断字符串。ParseAddr 负责识别 IPv6 的规范文本，Addr.Zone() 单独返回 Zone；没有 Zone 时返回空字符串。示例中可以预期第一行的 Zone 为空，第二行的 Zone 为 ens18。

带端口时不要继续调用 ParseAddr

如果输入是监听地址、连接目标或配置中的完整端点，字符串往往形如 [2001:db8::1]:443。它不是一个单独的 IP 地址，所以用 ParseAddr 失败是预期边界，不应通过删除方括号或切分最后一个冒号来“修复”。

package main

import (
    "fmt"
    "net/netip"
)

func main() {
    endpoint := "[fe80::1%ens18]:8080"
    addrPort, err := netip.ParseAddrPort(endpoint)
    if err != nil {
        // 端点错误要带上原文，避免把地址错误误报成端口错误。
        fmt.Printf("invalid endpoint %q: %v\n", endpoint, err)
        return
    }

    // AddrPort 同时保留地址、端口和地址上的 Zone 信息。
    fmt.Printf("addr=%s zone=%q port=%d\n", addrPort.Addr(), addrPort.Addr().Zone(), addrPort.Port())
}

需要比较或存储地址时，可取出 addrPort.Addr()；需要端口时读取 addrPort.Port()。这比把文本拆成“冒号前半段”和“冒号后半段”更能覆盖 IPv6 的双冒号和 Zone 情况。

如果业务输入本来就只有 IP，不要为了迁就端点格式而把端口塞进 Addr 字符串。反过来，如果下游需要连接端点，也不要只保存 Addr.String()，否则端口和端点边界会丢失。

从旧字符串判断迁移时要检查什么

迁移前后最重要的变化不是把函数名替换掉，而是让下游使用类型信息。可以按下面的变更表检查：

回归检查至少覆盖：普通压缩 IPv6、完整八组写法、带 Zone 的链路本地地址、带端口的方括号端点、空字符串和明显缺失分组的非法文本。检查点应同时确认 error 是否被处理，以及错误分支是否保留原始输入。

• 只需要地址：调用 ParseAddr，成功后读取 Is6 和 Zone。
• 需要地址加端口：调用 ParseAddrPort，不要先手工切字符串。
• 需要稳定键：使用可比较的 Addr，但明确带 Zone 的地址与无 Zone 地址不是同一业务含义。
• 需要格式化输出：使用类型的 String，不要把输入原文当作规范化结果。

两个容易混淆的问题

为什么 [2001:db8::1]:443 解析失败？ 因为它是端点而不是单独地址；把入口换成 ParseAddrPort，再通过 Addr() 和 Port() 分开使用。

Zone 是 IPv6 地址的一部分吗？ 在 netip.Addr 中 Zone 是地址作用域信息，适合链路本地等需要接口范围的场景。不要把它无条件删除，也不要把它当作端口；如果业务只允许全局地址，应在解析成功后另行做业务判断。

归纳起来，解析失败时先问一句“我拿到的是地址还是端点”，再问一句“这个 IPv6 是否带 Zone”。这两个判断明确后，netip 的 API 选择就不会被冒号和百分号牵着走。