Qt调用SetupAPI读取设备管理器详细信息的实战案例

简介：面向 Qt 开发者与 Windows 系统编程人员的示例项目源代码，演示通过 setupapi.h 中的 SetupDiGetClassDevs 与 SetupDiEnumDeviceInfo 等函数枚举设备管理器中的设备列表，并逐项读取属性。项目覆盖设备描述、图标、类名、GUID、设备实例路径、硬件 ID、驱动 INF 名称、驱动版本、显示名称、供应商等常用字段，可在设备管理、驱动信息查询、硬件监控等桌面应用开发中直接复用。压缩包共 12 个文件，以 4 个 C++ 源文件、3 个头文件、2 个 UI 界面文件、1 个 Qt 工程文件及 README 说明为主体，整体仅 21KB，轻量紧凑，适合导入 Qt Creator 研读。工程按主窗口、设备枚举与管理、驱动信息提取等模块划分，界面可直观展示设备列表，并与两篇系列博客文章配套，便于对照理解设备信息集获取、设备逐项遍历、关键属性读取的完整调用链条。已有 142 人学习，适合具备基础 Qt 知识、需要快速掌握 Windows 设备管理 API 与 Qt 程序结合方式的开发者，可作为设备管理功能模块的起步模板。

1. 这个 Qt 案例解决什么问题：通过 SetupAPI.h 把设备管理器明细搬到自己界面

设备管理器里那些“详细信息”并不神秘，一个 Qt 案例要去获取它们，最常见的做法就是直接调 Windows API 中的 SETUPAPI.H 库。你打开设备管理器看到的设备描述、硬件 ID、驱动版本、设备状态，本质上都能通过 SetupAPI 枚举出来。我最初做设备排查工具时，遇到“网卡灯不亮但设备管理器显示正常”这种问题，单靠人眼点属性太慢，于是把设备枚举逻辑做成了 Qt 模块，几十行代码就能把整棵设备树读出来。这篇笔记适合正在做硬件检测、驱动安装器、运维排查工具的 Qt 开发者，也适合刚接触 Windows 设备信息的 C++ 新手。读完你不仅能跑通示例项目，还能知道哪些参数不能乱填、为什么有人枚举结果多有人结果少。

2. 设备管理器的数据从哪里来：SetupAPI 的枚举原理与选型理由

2.1 设备树在注册表里，但别直接去读注册表

Windows 的即插即用管理器会在系统启动和热插拔时维护一棵设备树，设备详细信息通常落在HKLM\SYSTEM\CurrentControlSet\Enum下，驱动信息则在HKLM\SYSTEM\CurrentControlSet\Control\Class下。很多初学者第一次想实现“获取设备管理器中的详细信息”时，会直接打开注册表，按照设备实例路径一层一层找，甚至用QSettings去读这两个路径。这条路短期内能拿到几个字段，但真正做产品时会被打脸：注册表项的权限、系统版本差异、字符串类型转换、设备类 GUID 的映射关系，全都要自己维护。而 SetupAPI 本来就是设备管理器背后的 API，设备管理器窗口里每一次枚举和属性读取，走的都是同一套函数，没必要绕远路。

2.2 为什么用 SetupAPI 而不是 WMI：速度、字段、稳定性的取舍

Qt 里有哥们会问：用 WMI 查询Win32_PnPEntity不是更简单吗？确实，WMI 能拿到设备描述、PNP DeviceID、状态等信息，代码写起来也像 SQL。但 WMI 有两个让人难受的点。第一是慢，WMI 走的是 COM 跨进程查询，在大量设备、频繁刷新时延迟明显，做工具箱的实时刷新很难受。第二是字段粒度不够，WMI 给出的字段偏“业务化”，拿不到 SetupAPI 中那些原始属性，比如SPDRP_DRIVER指向的驱动服务键、设备问题码、设备实例 ID 的原始格式；而这些恰恰是排查驱动异常时最需要的细节。所以在需要贴近设备管理器视图、又需要原始字段的场景下，SetupAPI 是更稳的选择。你可以把 WMI 当作快速预览工具，而把 SetupAPI 当作能落地的数据接口。

2.3 核心调用链：从 HDEVINFO 到 SP_DEVINFO_DATA 的一整套句柄规则

SetupAPI 的枚举逻辑其实是一条固定的流水线。第一步用SetupDiGetClassDevs拿到一个HDEVINFO设备信息集句柄，第二步用SetupDiEnumDeviceInfo按索引遍历设备，第三步对每一个设备用SetupDiGetDeviceRegistryProperty读取具体属性，最后用SetupDiDestroyDeviceInfoList释放句柄。这里的“设备”不是用一个指针表示的，而是通过SP_DEVINFO_DATA结构体来承载设备实例的上下文。SP_DEVINFO_DATA有一个魔鬼字段cbSize，它必须在调用前手工设置成结构体大小，否则函数会直接拒绝执行。很多实例项目源码跑不起来，就是少了这行初始化。

HDEVINFO deviceInfoSet = SetupDiGetClassDevs( nullptr, nullptr, nullptr, DIGCF_ALLCLASSES | DIGCF_PRESENT); SP_DEVINFO_DATA devInfo = {}; devInfo.cbSize = sizeof(SP_DEVINFO_DATA); for (DWORD index = 0; SetupDiEnumDeviceInfo(deviceInfoSet, index, &devInfo); ++index) { // 到这里，devInfo 就代表设备管理器中的一项设备 } SetupDiDestroyDeviceInfoList(deviceInfoSet);

第一行参数里的四个nullptr分别表示设备类 GUID、设备枚举器名和父窗口句柄。传nullptr时枚举范围由最后一个参数DIGCF_ALLCLASSES | DIGCF_PRESENT控制。DIGCF_ALLCLASSES表示不限定设备类，DIGCF_PRESENT表示只枚举当前物理存在的设备。如果你把DIGCF_PRESENT去掉，就会把历史上安装过但现在不在线的“幽灵设备”也列出来，数量会一下子变多，一开始容易吓一跳。这个循环里每次迭代拿到的是同一个devInfo变量，Windows 内部会帮你更新其中的设备实例句柄DevInst，不需要你手动释放单个设备信息。

3. 在 Qt 中跑通最小示例：工程配置、枚举循环与表格展示

3.1 新建 Qt Widgets 工程并正确链接 setupapi.lib

我一般直接用 Qt Creator 创建 Qt Widgets Application，然后手动改.pro文件。关键是要让编译器找到setupapi.h，并且链接到setupapi.lib。使用 MSVC 工具链时，Windows SDK 的头文件和库文件默认在系统目录里，qmake 能找得到，但不会自动帮你带上 setupapi，所以必须显式声明。

QT += core gui widgets CONFIG += c++11 TARGET = DeviceInspector TEMPLATE = app DEFINES += UNICODE _UNICODE LIBS += -lsetupapi SOURCES += main.cpp mainwindow.cpp HEADERS += mainwindow.h

UNICODE和_UNICODE两个宏非常重要。如果漏掉，Windows 头文件中SetupDiGetDeviceRegistryProperty会被展开成SetupDiGetDeviceRegistryPropertyA，也就是 ANSI 版本，中文设备名大概率乱码。LIBS += -lsetupapi告诉链接器导入 SetupAPI 的导出函数。这里有个容易犯的错：如果电脑上装了多个 Qt 版本，比如 MinGW 版本和 MSVC 版本，一定要在 Qt Creator 的“工具链”设置里选对配套编译器。你用msvc2019_64的 Qt 库，却用 MinGW 的g++去链接，会亮红灯。

3.2 用 SetupDiGetClassDevs 与 SetupDiEnumDeviceInfo 枚举设备

这个步骤的目标是拿到设备实例 ID 列表。设备实例 ID 是设备管理器里“详细信息 -> 设备实例路径”那一栏的字符串，它是设备的唯一标识。我们先把它枚举出来，再做属性读取。

#include <windows.h> #include <setupapi.h> #include <QDebug> QStringList enumerateDeviceInstanceIds() { QStringList instanceList; HDEVINFO deviceInfoSet = SetupDiGetClassDevs( nullptr, nullptr, nullptr, DIGCF_ALLCLASSES | DIGCF_PRESENT); if (deviceInfoSet == INVALID_HANDLE_VALUE) { qWarning() << "SetupDiGetClassDevs failed, error:" << GetLastError(); return instanceList; } SP_DEVINFO_DATA devInfo = {}; devInfo.cbSize = sizeof(SP_DEVINFO_DATA); for (DWORD index = 0; SetupDiEnumDeviceInfo(deviceInfoSet, index, &devInfo); ++index) { WCHAR instanceId[MAX_PATH] = {}; if (SetupDiGetDeviceInstanceIdW(deviceInfoSet, &devInfo, instanceId, MAX_PATH, nullptr)) { instanceList << QString::fromWCharArray(instanceId); } } SetupDiDestroyDeviceInfoList(deviceInfoSet); return instanceList; }

SetupDiEnumDeviceInfo返回BOOL，当返回FALSE时，通常表示枚举完毕，此时调用GetLastError会得到ERROR_NO_MORE_ITEMS。这不是报错，是你循环退出的正常信号。我习惯不在循环里频繁调用GetLastError，而是在循环结束后再判断一次，避免性能损失。SetupDiGetDeviceInstanceIdW的缓冲区我直接用MAX_PATH，设备实例 ID 一般不会超过这个长度，但如果遇到超长路径，函数会返回FALSE并报ERROR_INSUFFICIENT_BUFFER，此时可以用SetupDiGetDeviceInstanceIdW传nullptr长度的方式先查询一下所需长度。

3.3 用 SetupDiGetDeviceRegistryPropertyW 读取宽字符属性

设备实例 ID 只是开始，设备管理器里真正的“详细信息”是设备描述、硬件 ID、制造商、驱动版本这一串属性。读取这些统一走一个函数：SetupDiGetDeviceRegistryPropertyW。它的第四个参数可以返回属性类型，第五、六个参数接收缓冲区，最后一个参数返回实际数据长度。这个函数既能读字符串，也能读二进制，所以缓冲区用BYTE数组更通用。

QString getDeviceProperty(HDEVINFO deviceInfoSet, SP_DEVINFO_DATA &devInfo, DWORD property, DWORD &propertyType) { BYTE buffer[4096] = {}; DWORD bufferSize = sizeof(buffer); DWORD reqSize = 0; BOOL ok = SetupDiGetDeviceRegistryPropertyW( deviceInfoSet, &devInfo, property, &propertyType, buffer, bufferSize, &reqSize); if (!ok) { if (GetLastError() == ERROR_INSUFFICIENT_BUFFER && reqSize > 0) { // 缓冲区不够时才二次调用 } return QString(); } if (propertyType == REG_SZ) { return QString::fromWCharArray( reinterpret_cast<const wchar_t *>(buffer)); } return QString(); }

这段代码有几个关键点。property参数填的是SPDRP_DEVICEDESC、SPDRP_HARDWAREID这类常量，它直接决定这次读出来的是设备描述还是硬件 ID。propertyType会返回注册表值的类型，常见的REG_SZ表示宽字符串，REG_MULTI_SZ表示以空字符分隔的多字符串。读取硬件 ID 时经常是REG_MULTI_SZ，直接转成QString只会得到第一项，后面需要手动用\0分割。缓冲区用BYTE的原因在于像SPDRP_DEVICE_POWER_DATA这种属性是二进制结构体，直接用wchar_t数组容易因越界被系统检测到访问冲突。

3.4 把 WinAPI 结果塞进 QTableWidget 的三种写法

枚举和设备属性都拿到以后，Qt 界面展示反而是最没技术含量的一步。我常用QTableWidget做三列表格：设备描述、硬件 ID、实例路径。最简单的方式是在循环内逐行插入。

ui->tableWidget->setColumnCount(3); ui->tableWidget->setHorizontalHeaderLabels( QStringList() << "设备描述" << "硬件 ID" << "实例路径"); HDEVINFO deviceInfoSet = SetupDiGetClassDevs( nullptr, nullptr, nullptr, DIGCF_ALLCLASSES | DIGCF_PRESENT); SP_DEVINFO_DATA devInfo = {}; devInfo.cbSize = sizeof(SP_DEVINFO_DATA); for (DWORD index = 0; SetupDiEnumDeviceInfo(deviceInfoSet, index, &devInfo); ++index) { DWORD propertyType = 0; QString desc = getDeviceProperty(deviceInfoSet, devInfo, SPDRP_DEVICEDESC, propertyType); QString hwid = getDeviceProperty(deviceInfoSet, devInfo, SPDRP_HARDWAREID, propertyType); WCHAR instanceId[MAX_PATH] = {}; SetupDiGetDeviceInstanceIdW(deviceInfoSet, &devInfo, instanceId, MAX_PATH, nullptr); QString instance = QString::fromWCharArray(instanceId); int row = ui->tableWidget->rowCount(); ui->tableWidget->insertRow(row); ui->tableWidget->setItem(row, 0, new QTableWidgetItem(desc)); ui->tableWidget->setItem(row, 1, new QTableWidgetItem(hwid)); ui->tableWidget->setItem(row, 2, new QTableWidgetItem(instance)); }

逐行insertRow在小规模设备几十项时完全够用。如果你有几千台虚拟设备，性能瓶颈会出现在QTableWidget的重绘上，此时可以改用QStandardItemModel+QTableView，先setRowCount再填充，最后一次性更新视图。另一个写法是用QTreeWidget按设备类分组，把 USB 设备、网络设备、显示设备分到不同父节点下，更贴近设备管理器的树形结构。无论哪种写法，都不要在 UI 线程里同时做枚举和填充，后面避坑章节会展开说。

4. 参数别靠猜：设备类 GUID、SPDRP 属性索引与状态码对照

4.1 常用设备类 GUID 表：限定枚举范围避免全量扫描

调用SetupDiGetClassDevs时，第一参数如果传一个具体的设备类 GUID，那么只会枚举该设备类下的设备。这样在写“列出所有网卡”功能时，不用枚举几百个设备再慢慢过滤，效率高很多。Windows SDK 的devguid.h头文件里已经定义了常用设备类的 GUID 宏，见下表。

我一般把枚举逻辑封装成一个函数，参数设为const GUID *deviceClass，当deviceClass为nullptr时走全量枚举，否则走单类枚举。这样既能拿到“设备管理器全部设备”，也能快速定位“网卡灯不亮但系统显示正常”时那块网卡。注意，GUID_DEVCLASS_NET枚举出来的是网络适配器，而不是网络协议，别把它和网卡的硬件设备混淆。

4.2 SPDRP_* 属性索引：从设备描述、硬件 ID 到驱动键

SetupDiGetDeviceRegistryPropertyW的第三参数property决定了你要读哪个字段。设备管理器里“详细信息”下拉框中的每一个条目，几乎都对应一个SPDRP_常量。常用的有这几个：

最常用的SPDRP_HARDWAREID是个坑，它是多字符串，字段间用\0分隔，整个数据末尾用两个\0结束。直接用QString::fromWCharArray只显示第一个 ID，通常是最短的那个。正确做法是把缓冲区里的宽字符按\0切分：

QStringList splitMultiSz(const BYTE *buffer, DWORD bufferSize) { QStringList result; if (bufferSize < 2) { return result; } const wchar_t *data = reinterpret_cast<const wchar_t *>(buffer); int remain = static_cast<int>(bufferSize / sizeof(wchar_t)); while (remain > 0 && data[0] != L'\0') { QString item = QString::fromWCharArray(data); result << item; int len = item.length() + 1; data += len; remain -= len; } return result; }

SPDRP_DRIVER读出来的是驱动在注册表Class键下的子键名，比如网卡驱动往往是{{4d36e972-e325-11ce-bfc1-08002be10318}}\0011。你可以用这个值继续拼接出驱动版本等信息，但需要再调用SetupDiOpenDevRegKey去读驱动注册表项，这一步超出了基础示例范围，但思路是通的。

4.3 用 CM_Get_DevNode_Status 判断设备是否正常

设备管理器里的“设备状态”是一个很关键的信息，但它不走SetupDiGetDeviceRegistryPropertyW。判断设备是否正常，常见做法是用CM_Get_DevNode_Status，它声明在cfgmgr32.h中，跟 SetupAPI 是同一个设备安装组件群。函数会根据设备实例句柄返回status和problem两个值，其中problem就是设备管理器属性里的“问题代码”。

#include <cfgmgr32.h> DWORD getDeviceProblemCode(HDEVINFO deviceInfoSet, SP_DEVINFO_DATA &devInfo) { DWORD status = 0; DWORD problem = 0; CONFIGRET cr = CM_Get_DevNode_Status( &status, &problem, devInfo.DevInst, 0); if (cr != CR_SUCCESS) { return static_cast<DWORD>(-1); } return problem; }

devInfo.DevInst是SetupDiEnumDeviceInfo取得的设备节点句柄，可以直接使用。problem为 0 表示设备状态正常，非 0 则对应一个CM_PROB_*常量，比如CM_PROB_FAILED_START表示设备无法启动，CM_PROB_OUT_OF_MEMORY表示内存资源不足。写界面时可以直接把problem转成用户能看懂的文本。

4.4 从设备实例路径反推网卡型号和总线位置

设备实例路径是排查硬件问题时最值得看的字段。常见格式有三种：PCI\VEN_10EC&DEV_8139\SUBSYS_...、USB\VID_046D&PID_C52B\...、ROOT\SYSTEM\...。VEN后面跟的是厂商 ID，DEV后面是设备 ID，SUBSYS后面是子系统 ID。拿到这些值，基本就能判断设备物理位置和实际芯片型号。比如网卡灯不亮、设备管理器又显示“这个设备运转正常”，你先看实例路径里的VEN_10EC，再对照驱动版本，就能缩小范围是芯片故障还是驱动与芯片不匹配。

解析实例路径用QRegularExpression最省事：

QRegularExpression pciRe( "PCI\\\\VEN_(\\w{4})&DEV_(\\w{4})&(?:SUBSYS|CC_)"); QRegularExpressionMatch match = pciRe.match(instancePath); if (match.hasMatch()) { QString vendorId = match.captured(1); QString deviceId = match.captured(2); // CAD 设备表或在线数据库映射厂商名 }

这种解析不涉及额外权限，纯字符串操作，放后台线程跑也没问题。很多开源维护工具里的“设备识别”核心就是这段逻辑。USB 设备则是VID_和PID_，解析规则一样。建议把实例路径解析和属性读取分开，前者可以反复用于设备定位，后者只在需要显示详情时才调用。

5. 避坑：Qt 里调 SetupAPI 常见的五个翻车点

5.1 编译报错找不到 Qt 模块：工具链错配而不是代码问题

现象：Qt Creator 里点击构建，直接报-1: error: dependent '..\..\..\..\..\..\qt\5.15.2\msvc2019_64\...一长串路径，代码一行没写错，工程就是编不过。

原因：这个报错几乎都是 Qt 版本与编译器工具链不匹配。比如你装的是qt 5.15.2 msvc2019_64，却在构建套件里选了 MinGW 64 位编译器。qmake 生成的 Makefile 去链接 Qt 库时，发现库文件格式不一致，于是把 Qt 安装路径拼接进依赖关系，报出的路径是一个“找不到”或者“格式错误”的状态。

解决：在 Qt Creator 的“工具 -> 选项 -> Kits”里，确认编译器是 Microsoft Visual C++ 2019 或 2022，然后再确认 Qt 版本路径里有msvc2019_64。如果你的环境是 VS2022，但要兼容 Qt 5.15.2，可以用 VS2022 自带的 MSVC v142 工具集，或者在安装 Qt 时多装一个msvc2019_64。清理掉 build 目录重新 qmake，这个低级错误就消失了。

5.2 设备名显示乱码或只有第一个字符：Unicode 开关没打开

现象：枚举出来的设备描述在控制台或 QTableWidget 里显示成一团乱码，或者只显示出第一个字母和后面的方块。

原因：典型原因是.pro文件里没有定义UNICODE和_UNICODE，导致 Windows 头文件自动选择了SetupDiGetDeviceRegistryPropertyA。ANSI 版本的函数把宽字符转换成当前代码页，中文设备描述在这种转换下很容易丢失信息。另一种情况是缓冲区类型用char*去接REG_SZ，也会得到截断结果。

解决：在.pro里加上DEFINES += UNICODE _UNICODE，并且在代码里强制使用SetupDiGetDeviceRegistryPropertyW和SetupDiGetDeviceInstanceIdW。我从不在代码里直接写 ANSI 版本函数，因为 Windows 的这套 API 本身就是宽字符为主，ANSI 版本只为了兼容老程序。把缓冲区定义为BYTE数组后，读取REG_SZ时用reinterpret_cast<const wchar_t *>(buffer)转一次再交给QString::fromWCharArray，就不会出现半个字符的问题。

5.3 枚举结果比设备管理器少：DIGCF_PRESENT 和 cbSize 的坑

现象：同样的电脑，设备管理器里能看到 30 多个设备，程序枚举出来只有十几个，少了打印机、蓝牙、虚拟设备等一大串。

原因：这里有两个常见错。第一是SetupDiGetClassDevs里传了nullptr但没带DIGCF_ALLCLASSES，或者带了DIGCF_ALLCLASSES却没带DIGCF_PRESENT，行为都不一样。只加DIGCF_ALLCLASSES会枚举注册表里所有设备类，但这没过滤不存在的设备；只加DIGCF_PRESENT会过滤当前在线的设备，但如果不加DIGCF_ALLCLASSES，它只枚举默认设备类。第二是SP_DEVINFO_DATA忘了初始化cbSize，导致SetupDiEnumDeviceInfo每次都跳过部分设备。

解决：统一写成SetupDiGetClassDevs(nullptr, nullptr, nullptr, DIGCF_ALLCLASSES | DIGCF_PRESENT)。SP_DEVINFO_DATA定义后立刻devInfo = {}，再给cbSize赋值。如果你确实想看到设备管理器里“查看 -> 显示隐藏的设备”中的离线设备，那就把DIGCF_PRESENT去掉。但注意，离线设备的属性读取会失败，因为设备节点没有真正激活。

5.4 属性读取失败 ERROR_INSUFFICIENT_BUFFER：先查长度再分配

现象：一些设备的硬件 ID 或位置路径特别长，SetupDiGetDeviceRegistryPropertyW返回FALSE，GetLastError是 122（ERROR_INSUFFICIENT_BUFFER）。

原因：我前面给的示例用了固定 4096 字节缓冲区，大多数情况够用，但某些设备实例路径会带超长的LUID或子系统中包含长字符串，特别是虚拟设备和某些 HID 设备，缓冲区不够的时候函数不会自动扩容。

解决：常见的稳健写法是第一次调用传nullptr作为缓冲区，requiredSize参数接收所需字节数，然后动态分配。下面的代码展示了这种双次调用思路：

QByteArray readRawProperty(HDEVINFO set, SP_DEVINFO_DATA &dev, DWORD property, DWORD &type) { DWORD reqSize = 0; if (!SetupDiGetDeviceRegistryPropertyW(set, &dev, property, &type, nullptr, 0, &reqSize)) { DWORD err = GetLastError(); if (err != ERROR_INSUFFICIENT_BUFFER) { return QByteArray(); } } QByteArray buf(static_cast<int>(reqSize), Qt::Uninitialized); if (!SetupDiGetDeviceRegistryPropertyW(set, &dev, property, &type, reinterpret_cast<BYTE *>(buf.data()), reqSize, nullptr)) { return QByteArray(); } return buf; }

注意，reqSize返回的是字节数，不是宽字符个数。缓冲区分配使用Qt::Uninitialized是为了避免QByteArray默认清零带来的额外开销，因为紧接着就会被系统数据覆盖。对于REG_MULTI_SZ属性，读完后记得最后一个宽字符后还有一个终止符，别把终止符当作有效字符。

5.5 在非主线程调 SetupAPI：界面卡死和无效数据的来源

现象：把枚举函数丢进QThread的run里，程序偶尔崩溃或者界面上显示的数据时好时坏，有时还会出现“QObject: Cannot create children for a parent that is in a different thread”的警告。

原因：SetupAPI 本身是线程安全的，问题在于你在工作线程里直接操作了QTableWidget。Qt 的 UI 对象只能在主线程访问，跨线程操作是未定义行为。另外一个隐含问题是，如果枚举循环里包含了耗时很高的属性读取，虽然不崩溃，界面也会因为主线程被占住而假死。

解决：把枚举和属性读取全部放在一个普通函数里，在QtConcurrent::run或QThread中执行，等数据全部准备成普通QList<QStringList>后，通过信号queuedConnection发给主线程槽函数，再由主线程一次性填充表格。给个信号定义：

// 在 MainWindow 内部 void devicesReady(const QList<QStringList> &rows);

工作线程只负责收集数据，主线程只负责显示，两边各干各的，就不会有 Qt 对象归属问题。这也是我每次做这种工具时的固定习惯，避开撞车。

6. 进阶：把枚举结果做成可刷新侧栏，并验证发布版本依赖

6.1 用 QTimer 定时刷新，但注意刷新间隔

设备信息是动态变化的，USB 设备插拔、网卡重驱动都会让设备列表变化。我习惯在界面里放一个“刷新”按钮，再提供一个可选定时刷新，用QTimer每 3 到 5 秒触发重新枚举。不要用 1 秒刷新，因为属性读取和实例路径解析虽然快，但高频重绘 QTableWidget 会带来明显闪烁。定时刷新时先清空旧数据，再插入新行；如果数据量超过 100 个设备，建议用QStandardItemModel做局部更新，只更新状态列。

6.2 用 windeployqt 验证发布版：SetupAPI 不需要打包，但 CRT 需要

发布 Qt 程序时，很多人只记得带 Qt 的 DLL，忘了确认系统 API 的链接方式。SetupAPI 是 Windows 系统库，位于System32，不需要也不应该打包到程序目录。真正需要验证的是 MSVC 运行时vcruntime140.dll和msvcp140.dll是否被带齐。发布前在 Qt 的bin下执行windeployqt.exe 你的程序.exe，它会自动拷入 Qt 相关 DLL，同时检查系统程序集依赖。我用一个简单验证方法：把生成目录拷贝到一台精简虚拟机里，关闭网络，直接运行，然后插拔一个 USB 设备看列表是否变化。这个操作能同时验证依赖完整性和设备热插拔监听路径。

还有一个我最近养成的习惯：把枚举到的设备实例路径和问题码导出到文本文件，在排查“网卡灯不亮但设备管理器显示正常”这类问题时，对比前后两次导出的差异，能快速定位是哪一次驱动更新改变了设备状态。以前我总喜欢直接读注册表去猜设备数据，后来全部回归 SetupAPI 之后，维护成本低了很多，报错也能从GetLastError里直接看出问题。希望这个 Qt 案例能帮你少走一次弯路，尤其是那些看着玄学的参数和缓冲区，都有明确答案。希望帮到你。

本文还有配套的精品资源，点击获取