Go net.SplitHostPort 为什么解析裸 IPv6 失败

net.SplitHostPort 解析的是“主机加端口”，不是单独的 IP。裸 IPv6 如 2001:db8::42 自身包含多个冒号，也没有独立的端口边界，因此不能直接交给它。如果只有 IP，使用 netip.ParseAddr；若要表达端口 9443，应写 [2001:db8::42]:9443。

地址与端口分开输入时，优先用 net.JoinHostPort 组装。它会为含冒号的主机加上需要的方括号，避免手工拼接把地址的最后一段误当端口。方括号属于端点文本的边界标记，不是 IP 本身的一部分。

Go 官方地址：https://go.dev/

先确认输入框要收 IP 还是连接端点

例如一个连接配置表单，用户在“IP 地址”框里填写 IPv6，后端却用 SplitHostPort 拆分，最终提示格式不对。用户输入的 IP 可能完全合法，只是程序选错了输入契约。应先确定页面到底让用户填一个地址，还是一次填完地址和端口。

表单若有独立端口框，IP 框的提示应写“IPv6 无需方括号”，端口框单独提示范围。只有一个端点框时，则明确给出带方括号的例子。不要在同一个框里同时接受未说明的多种格式，再靠最后一个冒号猜测。

用方括号给 IPv6 与端口划清边界

[2001:db8::42]:9443 中，方括号内是主机，右括号之后的冒号才分隔端口。SplitHostPort 成功后，host 不再包含方括号，port 是字符串 9443。

即使输入 2001:db8::42:9443 看起来像“地址后面接了端口”，它也可能整体就是 IPv6 地址，不能直接拆最后一段。端点形式缺少明确边界时，应要求调用方补充格式，而不是自动猜一个结果。

分开的 IP 和端口字段怎样实现

下面示例只接受数字 IP，端口约定为 1 至 65535。它先分别处理两个字段，再组装端点，并用 SplitHostPort 展示拆分。示例未在本文执行，打印内容是供读者自行观察的结果。

package main

import (
    "fmt"
    "net"
    "net/netip"
    "strconv"
    "strings"
)

// IPPort 面向“纯 IP + 数字端口”表单，不接受域名和整段 URL。
func IPPort(ipText, portText string) (string, error) {
    ipText = strings.TrimSpace(ipText)
    portText = strings.TrimSpace(portText)

    addr, err := netip.ParseAddr(ipText)
    if err != nil {
        // IP 字段要求不带方括号；错误由调用方展示在该字段旁。
        return "", fmt.Errorf("IP 地址格式错误，请只填写 IPv4 或 IPv6: %w", err)
    }
    if portText == "" {
        return "", fmt.Errorf("端口不能为空")
    }
    for _, ch := range portText {
        if ch  '9' {
            return "", fmt.Errorf("端口只能包含十进制数字")
        }
    }
    port, err := strconv.ParseUint(portText, 10, 16)
    if err != nil || port == 0 {
        // 这是本表单的业务范围；不表示网络库一律禁止端口 0。
        return "", fmt.Errorf("端口必须在 1 到 65535 之间")
    }
    return net.JoinHostPort(addr.String(), strconv.FormatUint(port, 10)), nil
}

func main() {
    endpoint, err := IPPort("2001:db8::42", "9443")
    if err != nil {
        fmt.Println(err)
        return
    }
    host, port, err := net.SplitHostPort(endpoint)
    if err != nil {
        fmt.Println("拆分端点失败:", err)
        return
    }
    // 只演示字符串处理，不建立网络连接。
    fmt.Printf("endpoint=%s host=%s port=%s\n", endpoint, host, port)
}

按代码逻辑，endpoint 应为 [2001:db8::42]:9443，host 为 2001:db8::42，port 为 9443。代码只做字符串与值解析，不访问示例地址，也不证明地址可达。2001:db8::/32 用于文档示例，不应作为真实服务部署地址照搬。

范围检查是这个表单自己的约束。网络接口在某些用途允许端口 0，比如让监听器选择可用端口；不要把“连接配置不接受 0”写成 Go 全部网络 API 的规则。

拆分成功还不代表 IP 与端口都合法

SplitHostPort 的职责是拆出主机和端口文本。不能把返回 err 为 nil 当成数字 IP、合法端口范围或域名存在的证明。例如业务要求端口是十进制数字，就应继续做数字与范围校验；业务允许域名时，则不应把所有主机都交给 ParseAddr 后拒绝。

如果输入明确限定为数字 IP 加数字端口，可以选 netip.ParseAddrPort。它不做域名解析，适合得到一个明确的 AddrPort 值：

// 适用于“数字IP+数字端口”，不会把域名解析成地址。
value, err := netip.ParseAddrPort("[2001:db8::42]:9443")
if err != nil {
    fmt.Println("端点格式错误:", err)
    return
}
fmt.Println(value.Addr(), value.Port())

这个片段可放进已经导入 fmt 与 net/netip 的函数中。即使严格解析成功，也应按实际用途判断端口是否允许为 0，以及地址是否满足本业务的使用范围。

让错误提示对输入者有用

不要把“too many colons”直接作为所有错误的统一提示。IP 框格式不对时解释它只接受地址；端点框缺端口时提示完整形式；端口超范围时保留原来的 IP 输入，避免用户反复重填。字段标签应可识别，错误信息应与对应字段关联，不能只依靠红色区分。

这些解析操作不需要先做 DNS 或网络连接。将语法校验与连接尝试分开，能避免用户每输一个字符就触发网络请求，也能明确区分“格式错误”和“连接失败”。语法通过后若连接失败，再检查路由、防火墙或服务监听，不要继续改写已经正确的端点。

只有 [::1] 可以直接用 SplitHostPort 吗？

只有括起来的主机仍然没有端口。端点可写 [::1]:9443；若只需要 ::1 这个 IP，则让地址解析器处理不带括号的地址。

IPv6 的 zone 应怎样处理？

对于确实需要作用域标识的地址，端点格式可包含 [host%zone]:port。zone 来自运行环境的接口信息，不能照抄他人机器上的名称；也不要为了移除报错任意丢掉它。

能把 https 开头的完整地址直接拆分吗？

不要这样做。完整 URL 应先由 net/url 解析，再读取 Hostname、Port 等部分。URI 中的转义规则与普通端点字符串也应分开处理。

规则参见 SplitHostPort 官方文档、JoinHostPort 官方文档及 netip.ParseAddrPort 官方文档。