Go IPv6 地址解析失败如何检查方括号

Go 里把 IPv6 地址和端口拼成网络地址时，最容易误判的地方就是冒号。IPv4 或域名可以直接写成 host:port，但 IPv6 本身已经包含多个冒号，完整地址必须用方括号把主机部分包起来。排查“IPv6 地址解析失败”时，先确认输入是裸主机还是已经带方括号的完整地址，再决定是否让标准库负责加括号。

官方文档：https://pkg.go.dev/net

• 传给 net.JoinHostPort 的 IPv6 主机建议保持为 2001:db8::1，不要提前写成 [2001:db8::1]。
• 带端口的字面量 IPv6 地址应写成 [2001:db8::1]:8080。
• 解析失败先看括号数量、端口是否存在，以及 zone 标识是否仍在主机部分。

先拆开裸主机和完整地址

一个配置字段如果叫 host，它最好只保存主机，不保存端口和方括号；另一个字段保存 port。如果把完整地址再次当作 host 传入，JoinHostPort 会把原有方括号当成普通字符继续包裹，结果就可能出现 [[2001:db8::1]]:8080。这不是 IPv6 本身不可用，而是数据边界被重复编码了。

因此，日志里不要只打印最终地址。排障时同时打印原始 host、port 和拼接结果，重点看 host 是否以 [ 开始、以 ] 结束，是否混入了 :端口。

用 JoinHostPort 生成地址

统一拼接入口可以把 IPv4、域名和 IPv6 的差异交给标准库处理。官方文档说明，JoinHostPort 会把 host 和 port 组合成网络地址；当 host 含有冒号时，它会返回带方括号的形式。关键是调用方只负责提供主机和端口，不要在调用前手工补括号。

package main

import (
    "fmt"
    "net"
)

func main() {
    hosts := []string{"example.com", "192.0.2.10", "2001:db8::1"}
    for _, host := range hosts {
        // 统一让标准库处理 IPv4、域名和 IPv6 的 host:port 边界。
        address := net.JoinHostPort(host, "8080")
        fmt.Println(address)
    }

    // 已经带方括号的输入不应再次作为 host 传入。
    fmt.Println(net.JoinHostPort("[2001:db8::1]", "8080"))
}

上面最后一行专门保留为反例：它会产生重复方括号。生产代码可以在配置入口约定“host 必须是裸值”，并在入口处拒绝带端口的字符串；不要在每个调用点各写一套猜测式修剪逻辑。

用 SplitHostPort 反查错误

当你拿到一个完整网络地址时，可以用 net.SplitHostPort 把 host 和 port 拆开。它支持普通的 host:port、带方括号的 IPv6，以及带 zone 的地址；字面量 IPv6 如果没有方括号，内部冒号就无法和端口分界。

package main

import (
    "fmt"
    "net"
)

func inspect(address string) {
    host, port, err := net.SplitHostPort(address)
    if err != nil {
        // 记录原始地址，方便区分缺括号、重复括号和缺少端口。
        fmt.Printf("address=%q parse_error=%v\n", address, err)
        return
    }

    // host 返回主机部分，port 返回不带分隔符的端口文本。
    fmt.Printf("host=%q port=%q\n", host, port)
}

func main() {
    inspect("[2001:db8::1]:8080")
    inspect("2001:db8::1:8080")
    inspect("[fe80::1%eth0]:8080")
}

看到错误时按三个方向检查：地址是否缺少方括号，是否出现了重复方括号，是否漏写端口。带接口 zone 的 IPv6 例如 [fe80::1%eth0]:8080 中，%eth0 属于 host 内容，不要把它截掉再拼接。

处理 zone 标识与边界输入

如果地址来自环境变量或配置文件，建议在读取层明确数据契约：分别读取 host 与 port，由一个小函数调用 net.JoinHostPort。对外接收完整地址时，则只在边界处调用 net.SplitHostPort，解析成功后再把拆出的 host 和 port 传给后续逻辑。

空端口、包含空白的端口、已经带端口的 host 都应该在配置层给出清晰错误。不要用简单的 strings.Split(address, ":") 代替标准库，因为 IPv6 的多个冒号会让切分结果失去主机边界。

常见问题

IPv6 一定要加方括号吗？

作为带端口的完整网络地址时，字面量 IPv6 需要方括号，例如 [::1]:80；作为单独 host 保存时不需要。让 JoinHostPort 负责从裸 host 生成完整地址最稳妥。

为什么会出现双层方括号？

通常是输入 host 已经是 [::1]，调用方又把它传给 JoinHostPort。统一约定 host 字段保存裸 IPv6，可以从数据源上消除这个问题。

zone 标识应该放在哪里？

zone 属于 IPv6 host，例如 fe80::1%eth0；带端口的完整地址写成 [fe80::1%eth0]:8080。不要把 zone 当成端口分隔符处理。

这类问题的判断顺序可以固定为：先确认输入是裸 host 还是完整地址，再用 JoinHostPort 统一拼接，遇到已有地址则用 SplitHostPort 拆分。只要把方括号视为“完整地址的边界标记”，而不是 host 内容，IPv6 解析失败通常就能快速定位。