Go net/http 访问 IPv6 地址为什么 URL 格式错误

我第一次把 Go 服务从域名切到 IPv6 时，最容易误判的一类错误不是网络不通，而是 URL 根本没有通过解析。原因通常是把 IPv6 地址直接写成 2001:db8::10:8080：地址本身就含有多个冒号，程序无法稳定判断最后一个冒号是不是端口分隔符。

正确做法是把 IPv6 host 放进方括号，再加端口；在 Go 里优先使用 net.JoinHostPort。例如 2001:db8::10 和 8080 应组合为 [2001:db8::10]:8080，之后再交给 url.Parse 或 http.NewRequest。

为什么 IPv6 不能按普通 host:port 拼接

普通域名的结构很直观：example.com:8080 中的冒号可以唯一地分开 host 和 port。IPv6 地址却把冒号用于十六进制分组，因此直接拼接后，下面两种含义混在了一起：

这里的方括号不是 IPv6 地址的一部分，而是 URL 语法给 host 划出的边界。Go 的 net/url 文档也明确说明，IPv6 host 必须用方括号包裹。

用 net.JoinHostPort 构造可解析的 Host

不要用字符串加号拼接地址和端口，把两个语义独立的值交给标准库更稳妥：

package main

import (
    "fmt"
    "net"
)

func main() {
    host := "2001:db8::10"
    port := "8080"

    // 标准库负责处理 IPv4、域名和 IPv6 的端口边界。
    address := net.JoinHostPort(host, port)
    fmt.Println(address) // [2001:db8::10]:8080
}

JoinHostPort 返回的是适合放进 Host 字段的字符串。传入 IPv6 zone 时也不要提前手写方括号，例如链路本地地址可把 fe80::1%en0 作为 host 传入，让标准库统一处理：

// zone 属于地址信息，端口仍然作为独立参数传入。
host := "fe80::1%en0"
address := net.JoinHostPort(host, "8080")
// 结果形如：[fe80::1%en0]:8080
_ = address

如果输入本身已经带了方括号，先检查数据来源，避免生成双层方括号。更好的约定是：业务层保存不带方括号的 host，只有在构造 Host 或 URL 时统一格式化。

用 url.URL 组合完整请求地址

得到 Host 后，还要把 scheme、路径和查询参数放进正确的 URL 字段。路径和查询较复杂时，手写整条字符串会把另一个问题带进来：斜杠、问号或参数转义错误。可以先组合结构，再调用 String：

package main

import (
    "fmt"
    "net"
    "net/url"
)

func main() {
    // 先明确 host 与 port 的边界，再交给 URL 结构保存。
    host := net.JoinHostPort("2001:db8::10", "8080")
    u := url.URL{
        Scheme: "http",
        Host:   host,
        Path:   "/api/items",
    }

    // RawQuery 保存已经编码的查询串；复杂参数可用 url.Values 生成。
    q := url.Values{}
    q.Set("limit", "20")
    u.RawQuery = q.Encode()
    fmt.Println(u.String())
    // http://[2001:db8::10]:8080/api/items?limit=20
}

也可以把最终字符串交给 url.Parse，它返回错误时先修地址结构，不要急着调大超时时间：

// Parse 只负责检查 URL 结构，不代表目标服务一定可连接。
u, err := url.Parse("http://[2001:db8::10]:8080/api")
if err != nil {
    // 这里记录可复制的地址和解析错误，方便定位方括号或端口问题。
    fmt.Println("URL 格式错误:", err)
}
_ = u

zone、端口和错误层级怎么排查

遇到“URL 格式错误”时，可以按错误出现的层级排查，而不是把所有问题都归到 IPv6 网络：

• 拼接前：host 是否是不带方括号的纯地址，port 是否是单独字段；优先重新调用 net.JoinHostPort。
• 解析时：确认 scheme 存在，IPv6 host 是否形如 [地址]，端口是否位于右方括号之后。
• 连接时：如果已经得到合法 URL，继续检查目标是否监听 IPv6、系统是否有路由，以及链路本地地址的 zone 是否正确。
• 请求后：收到 HTTP 状态码说明连接已经建立，后续应转向服务端路由、认证或响应处理，而不是继续修改方括号。

特别要注意 localhost、127.0.0.1 和 ::1 不是完全等价的测试目标。服务只监听 IPv4 时，改成 IPv6 URL 仍会连接失败；这属于网络或监听配置，不是 URL 格式问题。

相关问题

IPv6 没有端口时还需要方括号吗？

作为 URL 的 host 使用时，写成 http://[2001:db8::10]/api 更清楚；如果只是单独保存地址文本，则不需要方括号。方括号主要解决 URL 中 host 与端口的边界。

能不能用 strings.Join 拼出 IPv6 地址？

不建议。它不知道 host 的类型和 URL 语法，容易漏掉方括号；用 net.JoinHostPort 表达意图更直接。

url.Parse 成功后为什么请求仍然失败？

url.Parse 只检查地址结构。请求阶段还可能失败于 DNS、IPv6 路由、监听地址、TLS、代理或服务端响应。