Go net.SplitHostPort 解析 IPv6 地址为什么必须带方括号

我第一次在 Go 里处理 IPv6 地址和端口时，最容易误写的是 ::1:8080。直觉上它像是“地址后面再加一个端口”，但对解析器来说，地址内部已经有很多冒号，最后哪个冒号才是端口分隔符并不明确。正确写法是 [::1]:8080：用方括号先把 IPv6 主机圈起来，再用最后一个冒号分隔端口。

只要一个 host:port 的 host 是 IPv6 字面量，就把 IPv6 放进方括号；调用 net.SplitHostPort 时不要自己按冒号切字符串，生成地址时优先使用 net.JoinHostPort。

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

冒号多了，解析器就失去了边界

IPv4 地址 192.0.2.10:8080 和主机名 api.example.com:443 都只有一个关键分隔冒号，按最后一个冒号拆分通常没有歧义。IPv6 字面量则不同，2001:db8::10 的冒号属于主机本身。如果把它直接拼成 2001:db8::10:443，解析器无法仅凭冒号判断哪一段是端口。

SplitHostPort 实际识别哪些输入

SplitHostPort 支持普通的 host:port、带 zone 的 host%zone:port，以及用方括号包住主机的 [host]:port 和 [host%zone]:port。返回值是 host、port 和 error，所以即便输入来自配置文件，也应先判断错误，再使用前两个字符串。

package main

import (
    "fmt"
    "net"
)

func main() {
    samples := []string{
        "api.example.com:443",
        "192.0.2.10:8080",
        "[::1]:8080",
        "[fe80::1%lo0]:5353",
        "2001:db8::10:443", // IPv6 没有用方括号标出主机边界
    }

    for _, raw := range samples {
        host, port, err := net.SplitHostPort(raw)
        if err != nil {
            // 解析失败时不要继续使用 host 和 port 的空值。
            fmt.Printf("%-24s -> error: %v\n", raw, err)
            continue
        }
        // 只有无错误时，host 和 port 才是可供后续逻辑使用的字段。
        fmt.Printf("%-24s -> host=%q port=%q\n", raw, host, port)
    }
}

关键不是“IPv6 必须在任何场景都写方括号”，而是：当 IPv6 出现在带端口的 host:port 语法里时，方括号承担了主机边界标记。单独表示一个不带端口的 IPv6 地址时，不需要为了调用 net.ParseIP 而额外加方括号。

从错误文本反推输入边界

标准库实现先找最后一个冒号作为端口起点。输入没有冒号时，通常会得到 missing port in address；输入没有方括号却在主机部分出现额外冒号时，会得到 too many colons in address。如果以 [ 开头但没有匹配的 ]，则会得到缺少右方括号的错误。

这些错误适合用于定位配置问题，但不要把错误字符串当成长期稳定的业务枚举。更稳妥的做法是记录原始地址和 error，在代码里按“是否有错误”决定是否继续；如果业务确实要分类，可以在自己的层面把输入场景分类，而不是依赖错误文本精确匹配。

生成地址时为什么应使用 JoinHostPort

如果地址来自结构化字段，手工写 host + ":" + port 很容易在 IPv6 场景漏掉方括号。net.JoinHostPort 会根据 host 是否含有冒号决定是否加方括号，适合把主机和端口重新组合成可供网络 API 使用的地址。

package main

import (
    "fmt"
    "net"
)

func main() {
    cases := [][2]string{
        {"192.0.2.10", "8080"},
        {"api.example.com", "443"},
        {"2001:db8::10", "443"},
        {"fe80::1%lo0", "5353"},
    }

    for _, pair := range cases {
        // JoinHostPort 负责处理 IPv6 的方括号，不要再手工拼接冒号。
        address := net.JoinHostPort(pair[0], pair[1])
        host, port, err := net.SplitHostPort(address)
        if err != nil {
            // 组合后的地址仍要检查错误，避免把异常输入传给拨号层。
            fmt.Printf("address=%q error=%v\n", address, err)
            continue
        }
        // 拆分结果应与输入的两个结构化字段保持对应。
        fmt.Printf("address=%q host=%q port=%q\n", address, host, port)
    }
}

带 zone 的 IPv6 也遵循同一边界规则：fe80::1%lo0 是 host 字段，组合成带端口地址时应变成 [fe80::1%lo0]:5353。方括号只标记主机整体，不会删除或改写 zone。

网络代码里可以固定的检查顺序

• 接收完整地址时，用 net.SplitHostPort 解析，不要用 strings.Split(raw, ":") 代替。
• 解析返回错误时，先保留原始输入和错误上下文，不要把空的 host、port 继续传给连接层。
• 从 host、port 两个字段生成地址时，用 net.JoinHostPort，让标准库决定是否添加方括号。
• 涉及 IPv6 zone 时，把 zone 当作 host 的一部分传给组合函数，不要先按百分号拆掉。
• 日志中可以记录“地址格式错误”这类业务分类，但不要把某一版错误文本作为协议契约。

几个容易混淆的边界

“IPv6 不带端口也要方括号吗？”不一定。方括号是 host:port 语法中的边界标记，单独保存 IPv6 字面量时可以使用不带方括号的形式。

“能不能取最后一个冒号就行？”不能把这个规则扩展成自己的通用解析器。标准库还要检查方括号是否匹配、括号后是否紧跟端口分隔符，以及 host 中是否混入了不应出现的括号。

“JoinHostPort 会验证端口吗？”它负责组合字符串，不替你判断端口是否是数字、是否在合法范围内。端口的业务校验仍应放在解析之后的业务层。

总结

IPv6 之所以在 net.SplitHostPort 中必须带方括号，是因为 IPv6 本身包含冒号，而 host:port 还需要一个明确的端口分隔符。把 [IPv6]:port 当作完整地址格式，用 SplitHostPort 解析、用 JoinHostPort 生成，就能把主机边界、端口字段和错误处理分开，避免把字符串切分问题带进拨号、代理或日志解析代码。