net.LookupIP 地址族顺序影响连接选择的排查

net.LookupIP 返回的第一个地址不等于“DNS 指定的首选地址”，也不适合直接当成唯一连接目标。Go 可能根据本机路由和 RFC 6724 规则调整地址顺序，系统解析器与纯 Go 解析器也可能表现不同。排查这类问题时，先确认代码是否取了 ips[0]，再分别观察 IPv4、IPv6 候选和实际拨号地址；普通 TCP/HTTP 客户端优先把主机名交给 net.Dialer，让它处理双栈 Fast Fallback。

这个特性解决什么：解析地址不等于选择连接

域名可能同时拥有 A 与 AAAA 记录。net.LookupIP 的工作是返回 IPv4 和 IPv6 地址，真正“先连谁、失败后试谁”属于拨号阶段。把两个阶段混成一句 net.Dial("tcp", ips[0]+":443")，会把一个动态候选列表错误地压成唯一地址。

这种代码在单栈环境通常不暴露问题，一旦进入双栈容器、IPv6 路由不完整的机房或解析器行为不同的系统，就可能出现三类现象：同一域名在不同机器上首地址族不同；第一地址不可达导致长时间等待；手写连接 IP 后 TLS 的 ServerName 或 HTTP Host 又被破坏。

支持范围：顺序由哪些层共同决定

包级 net.LookupIP 使用本地解析器并返回 IPv4、IPv6 地址。需要超时或取消时，应改用 Resolver.LookupIP 或 LookupIPAddr，因为包级函数内部使用背景上下文。

在 Unix 系统上，Go 可能使用纯 Go DNS 解析器，也可能调用系统的 cgo 解析器。Go 文档列出的选择条件包括操作系统能力、环境变量和系统名称服务配置。因此，即便 DNS 区域数据相同，开发机、容器与生产主机也可能走不同解析路径。

当前 Go 源码还会执行最小化的 RFC 6724 地址选择排序。排序会考虑目的地址属性、当前主机可用的源地址和可达性，并保持等价项的稳定顺序。这意味着列表不只是 DNS 应答包的原始排列；同时，这也是实现细节，不应成为业务代码的永久契约。

最小示例：先记录候选，不在这里决定唯一地址

排查阶段可以显式调用带上下文的 Resolver，把每个候选的地址族记录下来。下面的函数只做观测，不重排、不连接，也不把第一个结果标记为“正确答案”。

package main

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

func printCandidates(host string) error {
    ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
    defer cancel()

    // 使用 ip 同时查询 IPv4 与 IPv6；需要限族时改为 ip4 或 ip6。
    ips, err := net.DefaultResolver.LookupIP(ctx, "ip", host)
    if err != nil {
        return fmt.Errorf("解析 %s 失败: %w", host, err)
    }

    for i, ip := range ips {
        family := "IPv6"
        if ip.To4() != nil {
            family = "IPv4"
        }
        // 仅记录候选与族，不把索引 0 当成业务优先级。
        fmt.Printf("index=%d family=%s ip=%s\n", i, family, ip.String())
    }
    return nil
}

一次输出只代表该环境、该时刻的结果。DNS 记录、路由、网络命名空间和解析器缓存都会变化，所以排查报告中应附上主机、时间、Go 版本和解析器模式，而不是只贴一个地址列表。

兼容处理：优先让 Dialer 接收主机名

如果目标是建立 TCP 连接，通常不需要先调用 LookupIP。把 host:port 直接交给 Dialer.DialContext，它会在主机名解析到多个地址时分配拨号超时，并按地址尝试。对于同时存在 IPv4 和 IPv6 的 TCP 目标，Fast Fallback 默认开启。

func dialService(ctx context.Context, host, port string) (net.Conn, error) {
    dialer := &net.Dialer{
        Timeout:       5 * time.Second,
        // 0 表示使用默认 300ms；主地址族未成功时启动另一地址族。
        FallbackDelay: 0,
        KeepAlive:     30 * time.Second,
    }

    // JoinHostPort 能正确处理 IPv6 方括号，保留域名则让 Dialer 管理多地址尝试。
    address := net.JoinHostPort(host, port)
    conn, err := dialer.DialContext(ctx, "tcp", address)
    if err != nil {
        return nil, fmt.Errorf("连接 %s 失败: %w", address, err)
    }
    return conn, nil
}

FallbackDelay 为零时使用默认 300ms；设置为负值会禁用 Fast Fallback。不要为了“稳定顺序”随意禁用它。该机制的目的正是容忍首个地址族配置不完整或连接挂起。

标准文档说明，Fast Fallback 会把第一个解析地址所属的地址族视为主族；若主族未及时成功，再启动另一族。因此首个地址族确实会影响最初尝试，但它不是唯一选择。只有手写 ips[0] 时，才把这种影响扩大成单点失败。

确实需要限族时，明确写 tcp4 或 tcp6

某些业务有明确边界，例如旧设备只监听 IPv4、IPv6 专线测试必须禁止 IPv4 回退。此时直接在网络参数里表达意图，比解析后自行筛选更清楚。

func dialIPv4Only(ctx context.Context, host, port string) (net.Conn, error) {
    dialer := &net.Dialer{Timeout: 3 * time.Second}
    address := net.JoinHostPort(host, port)

    // tcp4 是明确的业务约束；不要把它伪装成通用性能优化。
    conn, err := dialer.DialContext(ctx, "tcp4", address)
    if err != nil {
        return nil, fmt.Errorf("仅 IPv4 连接失败: %w", err)
    }
    return conn, nil
}

同理，只查询某一族可以调用 Resolver.LookupIP(ctx, "ip4", host) 或 "ip6"。限族会失去另一族的容错能力，应该记录原因并覆盖对应部署环境，而不是作为遇到首地址失败时的永久补丁。

如何确认使用了纯 Go 解析器还是系统解析器

Go 文档提供 GODEBUG=netdns 诊断开关。数字 1 会打印解析器决策信息；go+1 或 cgo+1 可在强制某个实现的同时输出诊断。它适合临时对比环境，不应在常态生产日志中长期打开。

# 临时查看 Go 如何选择 DNS 解析器；排查结束后移除
GODEBUG=netdns=1 ./client

# 临时强制纯 Go 解析器并打印决策，只用于对照实验
GODEBUG=netdns=go+1 ./client

如果两种模式返回的候选或顺序不同，应继续核对 /etc/resolv.conf、/etc/nsswitch.conf、搜索域、容器 DNS 代理与主机路由，不要直接得出“某个解析器错误”的结论。

性能注意：看最终远端地址与耗时，不只看候选顺序

双栈故障常表现为固定的额外延迟，而不是完全失败。若 IPv6 是主族但路径黑洞，另一族会在 FallbackDelay 后开始，整体耗时可能多出约一个回退等待。反过来，如果应用自己串行尝试每个地址，单个连接超时还会被分摊或累计，延迟形态与标准 Fast Fallback 不同。

观测至少应包含：解析耗时、IPv4/IPv6 候选数量、连接总耗时、最终 RemoteAddr 的地址族、错误类型和超时来源。不要把完整域名、内部 IP 或用户目标无差别写入公共日志；按系统的数据分级规则脱敏或聚合。

安全注意：过滤一个地址不等于过滤一个主机

如果解析结果用于访问控制或 SSRF 防护，只检查 ips[0] 是错误的：攻击者可能让同一主机名同时返回公开地址与私有地址，或在校验后改变解析结果。至少要检查全部候选，并尽量让验证与实际拨号使用同一批解析结果，避免检查与使用之间发生变化。

直接把域名替换成 IP 拨号还会影响 TLS SNI 与证书主机名校验。自定义连接时应保留原始服务名作为 TLS ServerName，HTTP 请求也要保留正确的 Host 语义。不要用 InsecureSkipVerify 掩盖因手写 IP 连接造成的证书错误。

排查清单

• 搜索代码中是否存在 LookupIP(...)[0]、手写排序或只连接第一个地址。
• 用带超时的 Resolver.LookupIP 分别记录 ip、ip4、ip6 结果。
• 确认生产环境使用纯 Go 解析器还是系统解析器，并记录相关系统配置。
• 让 Dialer.DialContext 直接接收主机名，保留默认 Fast Fallback。
• 仅在明确业务要求下使用 tcp4 或 tcp6。
• 记录最终远端地址族与连接耗时，区分解析慢、首族慢和全部地址失败。
• 自定义 TLS/HTTP 拨号时保留 ServerName 与 Host，不通过关闭校验绕过错误。
• 安全过滤必须覆盖全部候选，并处理 DNS 结果在校验后变化的风险。

常见问题

net.LookupIP 会保证 IPv6 在 IPv4 前面吗？

不会。文档只说明返回该主机的 IPv4 和 IPv6 地址，没有给出固定族顺序契约。当前实现会按本机条件执行 RFC 6724 相关排序，但调用方不应依赖某个固定排列。

为什么容器和宿主机返回顺序不同？

两者可能使用不同解析器、DNS 配置、网络命名空间、路由和可用源地址。逐项记录这些条件，比比较一张结果截图更有用。

把 IPv4 永久排到前面能解决问题吗？

它只能掩盖当前 IPv6 路径问题，还会损失 IPv6 可用时的能力。普通客户端应使用标准 Dialer 的 Fast Fallback；只有明确的 IPv4-only 业务才使用 tcp4。