Go net TCP连接 IPv6 链路本地地址的参数写法

Go 用 net 连接 IPv6 链路本地地址时，关键不是把 fe80:: 换成更长的字符串，而是把接口作用域写进地址。目标地址应当形如 [fe80::1%en0]:8080，其中 %en0 是 zone；再用 net.JoinHostPort 负责方括号和端口拼接，最后通过 tcp6 与 DialContext 建立可取消的 TCP 连接。

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

链路本地 IPv6 为什么必须写 zone

链路本地地址只在本地链路有效，同一个 fe80::1 可能同时出现在多块网卡上。系统需要 zone 判断应该从哪一个接口发包，因此 Go 的 TCP 地址把作用域写在 IPv6 文本的百分号后面，例如 fe80::1%en0。这里的 en0 只是示例，服务器上可能是 eth0、ens160 或操作系统返回的数字接口索引。

zone 不是端口，也不是 DNS 名称；它只补充链路本地地址的作用域。没有它时，地址即使能被解析，也无法稳定地选出本地接口。Go 的 net.Dial 文档明确要求字面量 IPv6 地址放在方括号内，并以 %zone 表示 scope。

用 JoinHostPort 构造正确的 tcp6 目标

不要用 ip + ":" + port 直接拼接 IPv6。冒号本身已经出现在 IPv6 地址中，手工拼接很容易得到无法拆分的地址；JoinHostPort 会在 host 含冒号时自动补上方括号，同时保留 zone。

package main

import (
    "context"
    "errors"
    "fmt"
    "net"
    "time"
)

func dialLinkLocal(parent context.Context, ip, zone, port string) (net.Conn, error) {
    // zone 必须对应本机真实接口，例如 en0、eth0 或系统返回的接口索引。
    host := ip + "%" + zone
    address := net.JoinHostPort(host, port)

    // tcp6 强制选择 IPv6；超时同时受 parent 和这里的 3 秒预算约束。
    ctx, cancel := context.WithTimeout(parent, 3*time.Second)
    defer cancel()
    conn, err := (&net.Dialer{}).DialContext(ctx, "tcp6", address)
    if err != nil {
        // 保留 context 原因，日志中还应记录 address 便于核对 zone 和端口。
        if errors.Is(err, context.DeadlineExceeded) {
            return nil, fmt.Errorf("连接 IPv6 链路本地地址超时 %s: %w", address, err)
        }
        return nil, fmt.Errorf("连接 IPv6 链路本地地址失败 %s: %w", address, err)
    }
    return conn, nil
}

func main() {
    // 这里只演示参数写法；en0 和 8080 必须替换为部署环境的接口与监听端口。
    conn, err := dialLinkLocal(context.Background(), "fe80::1", "en0", "8080")
    if err != nil {
        fmt.Println(err)
        return
    }
    defer conn.Close() // 连接使用完毕后释放文件描述符。
    fmt.Println("TCP 连接已建立")
}

这个示例最终传给拨号器的地址是 [fe80::1%en0]:8080。实际连接前，先确认目标接口上确实存在该地址，并且对端在同一链路上监听 TCP 8080。代码只展示参数和生命周期，不代表当前机器已经执行过这次连接。

按地址、接口和连接三层排查错误

如果报错出现在地址拆分或解析阶段，先看是否写成了 [fe80::1%en0]:8080，方括号不能省略。若地址格式正确但出现找不到接口、无效 scope 一类错误，应核对 zone 是否来自当前机器的真实接口，而不是复制了另一台主机的网卡名称。

地址能够解析却连接失败，问题通常已经进入 TCP 层：对端没有监听该端口、链路不通、主机防火墙拦截，或选择的接口不是目标所在链路。context.DeadlineExceeded 只说明在给定时间内没有完成连接，不等于地址一定不存在。

部署前的检查清单

• 从目标主机的网络接口信息中确认 IPv6 地址和 zone 成对出现。
• 使用 net.JoinHostPort 生成最终地址，并在日志中保留脱敏后的 host、zone、port。
• 明确使用 tcp6，不要依赖双栈环境下的隐式选择。
• 为 DialContext 传入请求或任务上下文，并设置符合业务预算的超时。
• 成功后关闭连接；失败时分别记录地址格式、接口作用域和 TCP 监听检查结果。

常见问题

IPv6 地址中一定要写百分号吗？

对链路本地地址通常需要，因为它必须绑定接口作用域；全局单播地址一般不需要 zone。最终以目标地址类型和操作系统网络配置为准。

为什么不能把地址写成 fe80::1:8080？

IPv6 本身使用冒号分段，拨号地址必须用方括号隔开主机和端口，正确形式是 [fe80::1%en0]:8080。

zone 写错会导致 TCP 端口错误吗？

不一定。zone 错误通常先表现为作用域或接口选择失败；如果接口正确但端口无人监听，才会进入连接拒绝或超时等 TCP 错误。

记住一条即可：先把 IPv6 地址 + zone 组成完整 host，再交给 JoinHostPort，最后用带截止时间的 tcp6 DialContext 连接。这样排查时每一层都有明确的参数边界。