Qt网络编程：网卡枚举、主机名解析与IP地址判断

做桌面客户端的人迟早会撞上一个挺别扭的问题：程序在自己机器上跑得好好的，换台机器就连不上服务端，或者连上了却走错了网段。这类问题十有八九不是业务代码写错了，而是程序压根不知道自己身处什么网络环境。于是 Qt 网络编程里那个看起来最不起眼的模块——获取基本网络信息——就变成了一块必须提前铺好的地基。我说的基本网络信息，指的是三样东西：本机有哪些网卡、每张网卡挂了哪些 IP 和掩码、某个主机名到底解析成什么地址。对应的三个类就是 QNetworkInterface、QNetworkAddressEntry、QHostInfo，外加一个贯穿始终的 QHostAddress。这套组合能把一台机器在网络层面的自我认知摸清楚，用它来做服务绑定、局域网设备发现、连接前的环境自检、日志里的现场快照，都很实用。这篇内容适合刚接触 Qt 网络模块、想快速上手的人，也适合写过几年客户端、但一直靠QHostAddress::LocalHost糊弄过去的人。

1. 网络信息采集到底在采什么：先把边界划清楚

1.1 三类信息与它们各自的坑

很多人一开始会把"获取网络信息"理解成一件事，实际动手才发现它至少分三层，而且每层的失败模式完全不同。第一层是接口层，问操作系统"你有几张网卡、每张卡上配了哪些地址"。这一层靠 QNetworkInterface 完成，特点是同步、即时、不需要网络连通性，哪怕断网也能拿到回环接口。坑在于列表里会混进一堆你根本不想用的东西：虚拟机桥接出来的虚拟网卡、容器运行时留下的虚拟接口、蓝牙 PAN 接口，还有一些名字古怪的隧道接口。你不做过滤，程序就可能绑到一张永远不通的卡上。

第二层是名称解析层，问"这个主机名对应哪个 IP"。这层靠 QHostInfo，特点是可能阻塞、可能很慢、可能一个名字返回多个地址。坑在于很多人直接在 UI 线程里调QHostInfo::fromName()，DNS 服务器不通的时候界面会僵住好几秒甚至十几秒，用户以为程序卡死了。

第三层是地址对象层，也就是 QHostAddress。它看着只是个包装字符串的类，实际上承担了协议族判断、合法性校验、字节序转换、网段比较这些活。坑在于 IPv4 和 IPv6 混在一起时，很多判断逻辑会悄悄失效——比如你写了个"是不是内网地址"的函数，遇到 IPv6 直接返回 false，然后在纯 IPv6 环境里整个自检逻辑全线失灵。

把这三层分开看，代码结构就清楚了：接口层负责枚举和过滤，解析层负责名称到地址的映射，地址层负责所有判断与转换。混在一起写，最后一定是一坨几百行的函数，改一处崩三处。

1.2 一个绑定错网卡的教训

我印象最深的一次，是给某公司的内网做一套客户端。测试机上有线网卡、无线网卡、两个虚拟网卡，程序启动时随手取"第一个非回环地址"来绑定本地监听端口。测试机上恰好有线网卡排第一，一切正常。交付到现场，那台机器无线网卡排在前面，而无线网卡连的是一个隔离的访客网络，结果就是服务端日志里能看到客户端上线，但同网段的采集设备永远发现不了它。排查了大半天，最后打印出QNetworkInterface::allInterfaces()的完整列表才看明白。

从那以后我给自己定了个规矩：任何需要选网卡的地方，都不能靠"第一个"或者"最后一个"这种顺序假设，必须让用户看得见、选得着，或者至少有明确的过滤规则。Qt 返回的接口顺序在不同平台上并不一致，Windows 上按系统内部顺序，Linux 上大体按 ifindex，但都不保证和你的直觉吻合。这个教训值一篇博文，也是我写这套采集逻辑的起点。

2. 工程骨架：从模块依赖到最小可运行程序

2.1 模块依赖与构建配置

QNetworkInterface、QHostInfo、QHostAddress 这三个类都在 Qt Network 模块里，不在 Core 里，所以第一步是把依赖加上。用 CMake 的话，在CMakeLists.txt里写：

find_package(Qt6 REQUIRED COMPONENTS Core Network) target_link_libraries(YourTarget PRIVATE Qt6::Core Qt6::Network)

还在 Qt5 上的项目对应写find_package(Qt5 REQUIRED COMPONENTS Core Network)和Qt5::Network。用 qmake 的老项目就在.pro文件里加一行：

QT += network

这里有个常见误区：有人以为查本机网卡信息不需要联网，所以不用引 Network 模块。实际上类所在的模块和功能是否依赖网络连通性没关系，编译期找不到头文件就是找不到。另外提一句，Qt 6 已经把QNetworkConfigurationManager整个删掉了，老代码里如果有基于它的"判断当前是否有网络连接"逻辑，迁移时得换成直接看接口状态，别再往那个方向找替代品。

2.2 我把采集逻辑单独抽成一个类的理由

功能简单，很多人会顺手写在 MainWindow 的某个槽函数里。我的建议是抽出来，哪怕只有一百多行。原因有三个：一是这套逻辑在日志快照、连接前自检、设置页展示、故障上报四个地方都要用，散着写必然复制粘贴；二是异步的名称解析需要信号槽或者回调，塞进窗口类里会让生命周期变得难管；三是抽出来之后可以单独写测试，用模拟的接口列表验证过滤规则对不对。

我的做法是一个纯数据类加一个采集器。数据类只放结构体，不带任何 Qt 对象语义，方便跨线程传递和序列化；采集器负责调用 Qt API 填充数据。这样上层想怎么展示都行，表格、树、纯文本日志、JSON 上报，全都只是渲染问题。

struct AddressEntryInfo { QString ip; QString netmask; QString broadcast; int prefixLength = -1; bool isIpv4 = true; }; struct InterfaceInfo { QString name; // 系统内部名，如 eth0 / en0 QString humanName; // 友好名，Windows 上常见 QString hardwareAddr; int index = -1; int mtu = 0; QString typeText; QStringList flagText; QVector<AddressEntryInfo> entries; };

结构体里我特意保留了index。Qt 的QNetworkInterface可以靠 index 反查，某些场景下比用名字更可靠，因为名字在系统里可能被改，索引相对固定。mtu也留着，排查"能 ping 通但大包发不出去"这类问题时，看一眼 MTU 有没有被隧道接口压到 1400 以下，往往一眼就能定位。

3. QHostInfo：主机名和 IP 的双向翻译

3.1 fromName 与 lookupHost 的取舍：什么时候能阻塞

QHostInfo 提供两套接口：fromName()是同步阻塞的，调用后线程停在那里等结果；lookupHost()是异步的，发起后立刻返回一个查询 id，结果通过信号或者回调送回来。选择标准其实只有一条：这段代码跑在哪个线程，以及用户能不能等。

在 UI 线程里，fromName()应该被当成禁忌。它不是"稍微慢一点"，而是取决于系统解析器，可能走 DNS、可能走 mDNS、可能走 hosts 文件，服务器不可达时超时时间由系统决定，实测有的环境能拖到十几秒。用户看到的就是白屏加"未响应"。

反过来，在启动阶段的一次性自检里，同步接口反而更省事。比如程序启动时想把本机主机名解析成 IP 写进日志，这时候界面还没出来，阻塞一下无伤大雅，代码也简单：

QHostInfo info = QHostInfo::fromName(QHostInfo::localHostName()); if (info.error() != QHostInfo::NoError) { qWarning() << "本地主机名解析失败:" << info.errorString(); } else { for (const QHostAddress &addr : info.addresses()) qDebug() << "本机地址:" << addr.toString(); }

注意这里用的是QHostInfo::localHostName()而不是QSysInfo::machineHostName()。两者有区别：前者拿到的是系统配置的主机名，后者是机器名，在某些系统上结果不一样。做名称解析就用前者，保持一致。

3.2 异步查询的写法与对象生命周期

异步接口的写法在不同 Qt 小版本上略有差异。Qt 5.9 之后推荐用带上下文对象的函数对象重载，好处是当上下文对象销毁时，回调不会再被触发，天然避免了野指针：

int lookupId = QHostInfo::lookupHost(QStringLiteral("some-host"), this, [this](const QHostInfo &info) { if (info.error() != QHostInfo::NoError) { qWarning() << "解析失败:" << info.errorString(); return; } for (const QHostAddress &addr : info.addresses()) qDebug() << "解析结果:" << addr.toString(); });

这个重载的参数顺序在不同版本里存在差异，有的版本是(name, functor, context)，有的是(name, context, functor)。写的时候以本地头文件为准，编译器会直接报错，不用猜。如果项目要兼容很老的版本，那就退回信号槽写法：先lookupHost(name, this, SLOT(onLookupFinished(QHostInfo)))，然后在槽里靠info.lookupId()和保存的 id 比对，因为多个查询可能共用一个槽。

还有一个容易忽略的点：lookupHost()返回的 id 可以用来取消查询，调QHostInfo::abortHostLookup(id)。窗口在查询途中被关闭、或者用户快速改了输入框内容触发新查询时，把上一个取消掉是有必要的，否则回调可能在对象已经进入析构流程时到达。虽然带上下文的函数对象重载能挡住大部分情况，主动取消依然是更干净的做法。

3.3 反向查询、多结果与错误码处理

QHostInfo 支持反向查询，也就是给一个 IP 问它对应的主机名。QHostInfo::fromName()传 IP 字符串进去就会走反向解析路径，返回的hostName()就是结果。反向解析在很多环境里是禁的或者很慢，所以只适合做"锦上添花"的展示，不要把它放进任何关键路径。

多结果是必须处理的。一个主机名返回四五个地址是常态，尤其是同时配了 IPv4 和 IPv6 的环境。只取addresses().first()是很危险的习惯，因为你无法保证第一个是 IPv4，也无法保证第一个是可达的。我的处理方式是按协议族分组，优先选和当前网卡同网段的那个，选不出来再退回第一个 IPv4，最后才考虑 IPv6。

错误码也要认真看，QHostInfo::HostNotFound表示名字确实不存在，QHostInfo::UnknownError表示解析过程本身出了问题。这两者对用户的提示应该是完全不同的：前者是"你输入的名字错了"，后者是"你的网络环境有问题"。混成一句"解析失败"，排查时会多绕很多弯路。

4. QNetworkInterface：把本机网卡一次看透

4.1 接口枚举与 flags 过滤的正确姿势

QNetworkInterface::allInterfaces()返回一个列表，直接遍历打印通常是一屏噪音。过滤的关键在 flags，几个标志位的含义必须分清：

一个稳妥的过滤顺序是：先看IsUp，再看IsRunning，然后按业务需要排除回环和点对点。这里有个细节值得说：IsUp && IsRunning是判断"这张卡现在真的能用"的组合条件，只判断IsUp会漏掉那些启用了但没插网线、没有拿到地址的接口。我见过有代码只判断IsUp，结果把一张没有 IP 的网卡当成可用接口，绑定的时候直接失败。

const auto ifaces = QNetworkInterface::allInterfaces(); for (const QNetworkInterface &iface : ifaces) { const auto flags = iface.flags(); if (!(flags & QNetworkInterface::IsUp)) continue; if (!(flags & QNetworkInterface::IsRunning)) continue; if (flags & QNetworkInterface::IsLoopBack) continue; // 到这里才是"可用"的候选 }

过滤完之后我习惯再按type()分一层。Qt 5.11 之后提供了接口类型枚举，Loopback、Ethernet、Wifi、Virtual、Ppp、CanBus这些值都有。把它映射成中文文本展示给用户，比只给一个eth0友好得多。尤其是Virtual这个类型，能帮你屏蔽掉相当一部分虚拟机桥接出来的接口，但它不是万能的——Windows 上有些虚拟网卡会被识别成Ethernet，最终还是得靠名字或者 MAC 前缀做二次判断。

4.2 QNetworkAddressEntry 里到底有什么

一张网卡可以有多个地址条目，所以 QNetworkInterface 和 QNetworkAddressEntry 是一对多关系。每个条目里装着四样东西：ip()地址本身、netmask()子网掩码、broadcast()广播地址、prefixLength()前缀长度。这四者不是完全冗余的，掩码和前缀长度可以互相换算，但 Qt 在部分平台上只会填其中一个，另一个返回 -1 或者空。所以代码里要做兼容：

for (const QNetworkAddressEntry &entry : iface.addressEntries()) { QHostAddress mask = entry.netmask(); int prefix = entry.prefixLength(); if (prefix < 0 && !mask.isNull()) { prefix = netmaskToPrefixLength(mask); // 自己算 } qDebug() << entry.ip().toString() << "/" << prefix << "broadcast:" << entry.broadcast().toString(); }

broadcast()只有在接口带CanBroadcast标志时才有意义，其他情况返回的是空地址，别拿它当有效值用。还有一个容易踩的坑是 IPv6 条目：IPv6 没有广播概念，broadcast()一定是空的，netmask()返回的是前缀对应的掩码形式。如果代码里对每个条目都无条件读广播地址做展示，IPv6 那一行就会空着，看着像 bug，其实是对的。

地址条目的顺序也不保证。同一张网卡上可能同时挂着 IPv4 主地址、IPv4 别名地址、IPv6 链路本地地址、IPv6 全局地址，返回顺序在不同平台不同版本上都不一样。要选"主地址"，得自己定规则，比如优先选 IPv4 且不是链路本地且不是回环的那个。

4.3 硬件地址、MTU 与接口索引

hardwareAddress()返回 MAC 地址的字符串形式，形如00:11:22:33:44:55。这个函数有几个现实约束：回环接口返回空、部分隧道接口返回空、在移动端受系统限制可能返回空或者固定值。所以它只能作为"有就用、没有就别展示"的辅助信息，不能作为设备唯一标识的依赖项。

maximumTransmissionUnit()在 Qt 5.7 之后可用，返回链路层的最大传输单元。这个值在排查网络问题时非常有用：以太网通常是 1500，某些隧道接口会被压到 1400 甚至 1280，如果你的应用要发大块数据又不做分片，MTU 小的链路上就会出现"小包通、大包不通"的经典现象。把 MTU 打进日志，能省掉很多抓包的时间。

index()返回接口索引，在 Windows 上就是适配器索引，在 Linux 上对应 ifindex。前面说了，用索引反查接口比用名字更可靠：

int idx = iface.index(); QNetworkInterface same = QNetworkInterface::interfaceFromIndex(idx);

QNetworkInterface::interfaceFromName()也常用，适合配置里保存了接口名的场景。但要注意，名字在 Windows 上可能是{GUID}形式，也可能是内部短名，用户看到的"以太网 2"是humanReadableName()，这两者不能混用。存配置就存name()，展示就展示humanReadableName()，别把展示名当键用。

4.4 虚拟网卡、回环、链路本地地址怎么处理

虚拟网卡是这套逻辑里最烦的部分。一台装了虚拟化软件的开发机上，allInterfaces()返回七八个接口是常事，其中可能只有一两个是真实在用的。处理策略我一般分两档：展示模式全列出来并标注类型，让用户自己认；自动选择模式严格过滤，只保留IsUp && IsRunning && !IsLoopBack && !IsPointToPoint且类型不是Virtual的接口，并且要求至少有一个非链路本地地址。

链路本地地址指的是 IPv4 的169.254.0.0/16和 IPv6 的fe80::/10。前者出现意味着 DHCP 没拿到地址，这本身就是个故障信号，拿它去做服务绑定基本等于绑了个寂寞；后者是 IPv6 的自动配置地址，同一链路上能用，跨网段就不行。QHostAddress 提供了isLinkLocal()直接判断，代码里加一行过滤能省掉很多"为什么连不上"的疑问。

回环地址的处理要分场景。做自检展示的时候，127.0.0.1是有价值的信息，说明协议栈正常；做服务绑定时，绑到回环意味着只有本机能访问，很多"外网访问不了"的问题就出在这——用户以为绑了0.0.0.0，实际代码里写死了QHostAddress::LocalHost。这两种地址的语义差别值得在代码注释里写清楚。

5. QHostAddress：地址对象的类型判断与格式互转

5.1 有效性校验与协议族判断

QHostAddress 最常见的误用是把"非空"当成"有效"。isNull()判断的是这个对象有没有承载地址，和地址本身合不合法是两回事。从字符串构造时，一定要检查构造结果：

QHostAddress addr; bool ok = addr.setAddress(QStringLiteral("192.168.1.10")); if (!ok) { qWarning() << "地址字符串非法"; return; }

protocol()返回QAbstractSocket::IPv4Protocol、IPv6Protocol或UnknownNetworkLayerProtocol。这个判断在混合环境里必须做，因为同一个处理流程里 IPv4 和 IPv6 的分支逻辑差别很大。我习惯在最外层就把地址按协议族分流，而不是在每个函数内部零散判断，不然代码里到处都是if (protocol() == ...)。

还有一个实用方法是QHostAddress::parseSubnet()，可以把192.168.1.0/24这样的字符串解析成地址加前缀长度的一对值，用来做配置项解析非常方便，省得自己写字符串切分和校验。

5.2 字符串、整数、字节序的转换细节

toIPv4Address()返回一个quint32，这个值是主机字节序，不是网络字节序。这一点特别容易搞错，因为网络编程里大量 API 用的是网络字节序。Qt 在这里做了转换，好处是你直接拿来做位运算就行，坏处是如果把这个值直接塞进setsockopt或者原始 socket 调用，字节序就反了。

用整数构造地址同样要小心。QHostAddress(quint32 ip4Addr)接收的是主机字节序的值，和toIPv4Address()是配套的。我一般把网段运算全部放在整数域做，需要展示时再转回字符串：

bool ok = false; quint32 ip = addr.toIPv4Address(&ok); if (!ok) return false; quint32 mask = 0xFFFFFF00u; // /24 quint32 network = ip & mask; QHostAddress netAddr(network); qDebug() << "网段:" << netAddr.toString();

IPv6 那边没有对应的整数接口，toIPv6Address()返回的是一个结构体，包含c、a、d等字段，实际使用中很少直接操作，更多是用toString()和isInSubnet()。所以我给个建议：凡是需要做位运算的，先确认是 IPv4，IPv6 走另一条路径，不要试图用统一逻辑覆盖两者，得不偿失。

5.3 回环、私有网段、同网段判断

QHostAddress 自带isLoopback()，IPv4 的127.0.0.0/8和 IPv6 的::1都能识别。私有网段没有直接接口，得自己写：

bool isPrivateIPv4(const QHostAddress &addr) { bool ok = false; quint32 v4 = addr.toIPv4Address(&ok); if (!ok) return false; if ((v4 & 0xFF000000u) == 0x0A000000u) return true; // 10.0.0.0/8 if ((v4 & 0xFFF00000u) == 0xAC100000u) return true; // 172.16.0.0/12 if ((v4 & 0xFFFF0000u) == 0xC0A80000u) return true; // 192.168.0.0/16 return false; }

注意172.16.0.0/12的范围是172.16.0.0到172.31.255.255，掩码是0xFFF00000，写成0xFFFF0000就只覆盖了172.16.0.0/16，这是个高频错误。分段判断的时候，掩码的 1 的位数必须和 CIDR 前缀一致。

同网段判断用isInSubnet(const QHostAddress &subnet, int netmask)，第二个参数是前缀长度不是掩码。两个地址都要先转成整数域算网段再比较当然也行，但用这个接口更直观：

bool sameSubnet(const QHostAddress &a, const QHostAddress &b, const QHostAddress &mask, int prefix) { return a.isInSubnet(b, prefix) || b.isInSubnet(a, prefix); }

严格来说应该拿掩码和地址算出网络号再比，isInSubnet内部就是干这个的，直接传前缀长度即可。手头只有掩码没有前缀长度时，前面那个netmaskToPrefixLength()就派上用场了——数掩码里连续 1 的个数，同时校验是不是连续的，非连续掩码在正常配置里不该出现，出现了说明配置有问题，值得在日志里报警。

6. 完整实操：一个可直接复用的网络信息面板

6.1 数据结构设计

前面给了两个结构体，这里补全采集器的接口。设计原则是同步部分一次性采集完，异步部分单独回调，两者解耦。这样调用方可以先拿到一份"接口快照"立即展示，主机名解析慢就慢去，解析回来再填进面板。

class NetProbe : public QObject { Q_OBJECT public: explicit NetProbe(QObject *parent = nullptr) : QObject(parent) {} QVector<InterfaceInfo> collectInterfaces(bool skipVirtual = true); void resolveAsync(const QString &host); static bool isPrivateIPv4(const QHostAddress &addr); static int netmaskToPrefixLength(const QHostAddress &mask); signals: void resolveFinished(const QString &host, const QStringList &addresses); void resolveFailed(const QString &host, const QString &reason); };

collectInterfaces带一个skipVirtual参数，是因为展示和自动选择的需求不同。默认跳过虚拟接口，设置页里传false全展示，用户能看到全部现场。

6.2 采集主流程代码

主流程就是遍历加过滤加填充，逻辑不复杂但细节多：

QVector<InterfaceInfo> NetProbe::collectInterfaces(bool skipVirtual) { QVector<InterfaceInfo> result; const auto ifaces = QNetworkInterface::allInterfaces(); for (const QNetworkInterface &iface : ifaces) { const auto flags = iface.flags(); if (!(flags & QNetworkInterface::IsUp)) continue; if (!(flags & QNetworkInterface::IsRunning)) continue; if (flags & QNetworkInterface::IsLoopBack) continue; if (flags & QNetworkInterface::IsPointToPoint) continue; if (skipVirtual && iface.type() == QNetworkInterface::Virtual) continue; InterfaceInfo info; info.name = iface.name(); info.humanName = iface.humanReadableName(); info.hardwareAddr= iface.hardwareAddress(); info.index = iface.index(); info.mtu = iface.maximumTransmissionUnit(); info.typeText = typeToString(iface.type()); const auto f = iface.flags(); if (f & QNetworkInterface::CanBroadcast) info.flagText << QStringLiteral("广播"); if (f & QNetworkInterface::CanMulticast) info.flagText << QStringLiteral("组播"); bool hasUsableAddr = false; for (const QNetworkAddressEntry &entry : iface.addressEntries()) { const QHostAddress ip = entry.ip(); if (ip.isNull()) continue; if (ip.isLinkLocal()) continue; // 169.254 / fe80 不算可用 AddressEntryInfo e; e.ip = ip.toString(); e.isIpv4 = (ip.protocol() == QAbstractSocket::IPv4Protocol); e.netmask = entry.netmask().toString(); e.broadcast = (f & QNetworkInterface::CanBroadcast) ? entry.broadcast().toString() : QString(); e.prefixLength = entry.prefixLength(); if (e.prefixLength < 0 && !entry.netmask().isNull()) e.prefixLength = netmaskToPrefixLength(entry.netmask()); info.entries.append(e); hasUsableAddr = true; } if (!hasUsableAddr) continue; // 没地址的卡对业务没意义 result.append(info); } return result; }

这段代码里有三个决定是我反复权衡过的。第一，IsPointToPoint直接排除，因为是隧道接口居多，业务用不上；如果你的场景恰好要通过点对点链路通信，把这行删掉。第二，链路本地地址不计入"可用"，但仍然建议在完整展示模式下保留，作为诊断信息。第三，hasUsableAddr这个判断必须有，否则会出现一张没有地址的网卡被推荐给用户选择的尴尬情况。

6.3 子网计算与同网段判断的实现

掩码转前缀长度，核心是数连续的 1 并校验连续性：

int NetProbe::netmaskToPrefixLength(const QHostAddress &mask) { bool ok = false; quint32 m = mask.toIPv4Address(&ok); if (!ok) return -1; int bits = 0; while (bits < 32 && (m & (1u << (31 - bits)))) ++bits; const quint32 expect = (bits == 0) ? 0u : (~0u << (32 - bits)); return (m == expect) ? bits : -1; // 非连续掩码返回 -1 }

注意~0u << (32 - bits)在bits == 0时位移 32 位属于未定义行为，所以单独处理。这种边界在写的时候容易忽略，运行起来可能"碰巧"是对的，换个编译器就出问题。

有了前缀长度，判断两个地址是否同网段就很直接。实际用的时候，我会把"本机每个可用地址"和"目标地址"做一轮比对，找出同网段的那张网卡，用于提示"建议使用此网卡"，这个交互在双网卡机器上很受欢迎。

6.4 输出格式与界面呈现建议

数据拿到了，怎么展示是另一回事。我的经验是分层展示效果最好：第一层是接口卡片，显示友好名 + 类型 + MAC + MTU；第二层是每张卡下面的地址列表，一行一个地址，带上/前缀和广播地址；第三层是折叠的诊断信息，包括 flags、索引、原始名称。默认只展开第一二层，排查时才看第三层。

如果是纯命令行工具或者日志输出，我会用一行一地址的紧凑格式，方便 grep：

[wlan0] Wifi 00:11:22:33:44:55 MTU 1500 - 192.168.1.23/24 mask 255.255.255.0 bcast 192.168.1.255 - fe80::1c2d:3e4f:5a6b:7c8d/64 (链路本地，已排除)

日志里带上接口名和地址，出问题时用户截个图就能定位，比让他描述"我有两个网卡"有用一百倍。这也是我一直坚持把这段代码抽成公共模块的原因——它出现的最高频场景其实不是设置页，而是故障上报。

7. 踩坑记录与排查速查表

7.1 常见问题速查表

这张表里的每一条我都真切遇到过，尤其是最后一条。绑定地址写成QHostAddress::LocalHost而不是QHostAddress::Any，现象是本地测试全通、外部一律超时，日志里看不到任何错误，因为绑定本身是成功的。

7.2 几个容易忽略的细节

中文主机名与编码。主机名里含非 ASCII 字符时，不同系统的解码方式可能不一致，直接拿来做 DNS 查询有概率失败。稳妥做法是先转成 IDN 形式再查，展示时再转回来。这个场景不常见，但一旦出现就很难查，因为错误信息往往只说"找不到"。

多网卡同名。极少数环境下会出现两张卡name()相同的情况，此时用名字反查会拿到错的那张。这就是我坚持在结构体里保留index的原因，反查一律用索引。

接口列表的时效性。插拔网线、连接无线网络、修改 IP，这些操作都会让接口列表变化。Qt 在部分平台提供了接口变化的信号，但覆盖度不一致，跨平台项目我一般不用信号，改成"用户打开设置页时重新采集一次"，简单可靠。真有实时需求就加个定时轮询，间隔别低于两三秒，太频繁纯属浪费。

Qt 版本差异。QNetworkInterface::type()是 5.11 才有的，maximumTransmissionUnit()是 5.7 才有的。项目要兼容更老的版本，这两个得用条件编译包起来，或者干脆自己维护一份类型推断表。

7.3 性能与线程安全

采集本身很快，allInterfaces()是读系统状态，通常一两毫秒内完成，放在 UI 线程完全没问题。真正慢的只有名称解析，所以我的原则是接口采集同步做，名称解析一律异步。

如果你确实需要在一个后台线程里做同步解析，注意 QHostInfo 本身是可重入的，但返回的 QHostInfo 对象是值语义，跨线程传递时按值拷贝就行，别传指针。另外QNetworkInterface的静态方法也是线程安全的，可以在工作线程里直接调。

还有一个内存层面的小提醒：如果做长周期轮询，每次采集都会新建一堆 QString，量不大但会持续产生分配。我的做法是轮询间隔不低于五秒，并且复用同一个 QVector 容器，用clear()加append()而不是每次重建，减少分配压力。这只是优化习惯，不影响功能正确性。

再分享一个调试技巧：把这套采集逻辑做成一个隐藏的快捷键或命令行参数，比如启动时加--netinfo就直接打印完整网络快照然后退出。用户报障时让他跑一次把输出发过来，比让他描述网络环境高效得多，而且这份输出里通常能直接看出问题所在——绑错网卡、地址是链路本地、只有一个回环地址，基本一眼就能认出来。整个模块加起来不到三百行，投入产出比在我做过的所有基础设施代码里都算高的。