简介本资源面向需要在 Qt5 环境下实现 USB 设备热插拔检测的开发者尤其适合从事硬件交互、设备管理类桌面应用的中级 Qt 程序员。包内提供已成功编译的 QDeviceWatcher 移植实例覆盖 Windows、Linux、macOS 多平台兼容配置并演示如何通过 deviceAdded 与 deviceRemoved 信号实时响应设备插入与移除进而读取设备信息或打开通信。资源共 72 个文件以 cpp 源码、h 头文件、pro 工程文件为主另含 obj、o 编译产物、so 动态库及 vcproj、sln 等工程配置压缩包约 1.18MB目录结构清晰便于按模块查阅与二次开发。目前已有 1383 人学习下载读者可借此掌握 Qt5 中 USB 设备监控的标准化写法理解跨平台适配要点并直接复用示例代码到自己的项目中快速搭建与硬件交互的应用雏形。1. 从一块“插上没反应”的板子说起Qt5 检测 USB 设备到底在做什么很多做上位机的朋友都遇到过这种场景设备明明插在电脑上系统也“叮咚”响了一声但自己用 Qt5 写的界面就是没反应日志里干干净净用户只能反复拔插最后甩过来一句“你这软件是不是坏了”。问题往往不在驱动也不在硬件而在于程序根本没有去监听 USB 设备的插拔事件。Qt5 检测 USB 设备这件事说白了就是让上位机在设备接入和移除的瞬间拿到通知然后刷新界面、打开端口、启动采集而不是靠用户手动点“刷新”按钮。这个资源面向的是用 Qt5 做工业上位机、仪器控制、串口调试工具的开发者。它解决的核心诉求有三个第一知道设备什么时候来、什么时候走第二拿到设备的 VID、PID、序列号这些能区分“是不是我要的那台”的信息第三在 Windows、Linux 上都能跑而不是换台机器就翻车。如果你正在写一个需要跟 USB 转串口、USB 采集卡、USB HID 设备打交道的 Qt5 程序这份东西就是冲着你来的。2. Qt5 检测 USB 的三条技术路线选错了后面全是坑2.1 为什么不能只靠 QSerialPort 的 availablePorts很多人第一反应是用QSerialPortInfo::availablePorts()去枚举串口插拔一次就重新枚举一遍。这个做法在“只关心串口”的场景下能凑合用但它有两个硬伤。一是它只能看到已经生成串口节点的设备像 USB HID、USB 存储、厂商自定义的免驱设备根本不会出现在串口列表里。二是它没有“事件”概念你只能靠定时器轮询轮询间隔设大了反应慢设小了 CPU 占用上去了属于典型的治标不治本。更关键的是availablePorts()拿到的是串口名比如 COM3、ttyUSB0但你要判断“这是不是我那台设备”还得再拿 VID、PID 去比对。而 VID、PID 在QSerialPortInfo里虽然有但设备刚插入、驱动还没加载完的那几百毫秒里枚举结果是不稳定的。我见过太多程序在设备插入瞬间去读串口结果拿到空列表然后用户以为设备坏了。2.2 原生事件监听Windows 的 WM_DEVICECHANGE 与 Linux 的 udev真正靠谱的做法是走操作系统的设备事件机制。Windows 下每个顶层窗口都能收到WM_DEVICECHANGE消息其中DBT_DEVICEARRIVAL和DBT_DEVICEREMOVECOMPLETE就是设备接入和移除。你需要在 Qt 的nativeEvent里拦截这个消息再根据DEV_BROADCAST_DEVICEINTERFACE里的 GUID 去判断是不是自己关心的设备类。Linux 下则是 udev 的天下。你可以用 libudev 的udev_monitor创建一个监听套接字把它挂到 Qt 的事件循环里设备一插一拔就能收到add和remove事件。这条路的好处是实时性极高基本是毫秒级响应而且不依赖轮询。代价是你要写平台相关代码Windows 和 Linux 两套逻辑编译时还得链接不同的库。2.3 跨平台折中方案libusb 热插拔回调如果你不想写两套原生代码libusb 的热插拔回调是个折中选项。libusb 在 1.0.16 之后提供了libusb_hotplug_register_callback可以注册一个回调函数当指定 VID、PID 或设备类的设备接入移除时触发。它内部在 Windows 上用窗口消息、在 Linux 上用 udev 或 netlink 实现等于帮你把平台差异抹平了。不过 libusb 的热插拔有个前提你的设备得能被 libusb 识别。如果设备已经被系统驱动接管了比如 USB 转串口芯片被虚拟成 COM 口libusb 可能拿不到它的句柄。这时候你仍然可以用 libusb 监听“设备到达”事件但打开设备还得走串口那条路。所以实际项目里常见做法是 libusb 负责监听QSerialPort 负责通信两者配合。方案实时性跨平台能识别的设备类型实现复杂度QSerialPort 轮询低好仅串口类低原生事件高差按设备类/GUID高libusb 热插拔高好需 libusb 可见中提示如果你的设备是 USB 转串口且只关心串口用QSerialPortInfo配合短间隔轮询也能用但一定要在设备到达后延迟几百毫秒再打开串口给驱动加载留时间。3. 动手实现从注册监听到拿到 VID/PID 的完整链路3.1 Windows 下拦截 WM_DEVICECHANGE 的代码骨架先看 Windows 这条路。核心是重写QWidget或QMainWindow的nativeEvent在里面判断消息类型。下面这段代码可以直接抄进你的窗口类里。// windows_usb_watcher.h #include QWidget #include windows.h #include dbt.h class UsbWatcher : public QWidget { Q_OBJECT public: explicit UsbWatcher(QWidget *parent nullptr); protected: bool nativeEvent(const QByteArray eventType, void *message, long *result) override; signals: void deviceArrived(const QString vidPid); void deviceRemoved(const QString vidPid); private: HDEVNOTIFY m_notifyHandle nullptr; void registerDeviceNotification(); };// windows_usb_watcher.cpp #include windows_usb_watcher.h #include QDebug UsbWatcher::UsbWatcher(QWidget *parent) : QWidget(parent) { registerDeviceNotification(); } void UsbWatcher::registerDeviceNotification() { // 监听所有 USB 设备接口类GUID_DEVINTERFACE_USB_DEVICE 是 USB 设备类的标准 GUID DEV_BROADCAST_DEVICEINTERFACE filter {}; filter.dbcc_size sizeof(filter); filter.dbcc_devicetype DBT_DEVTYP_DEVICEINTERFACE; filter.dbcc_classguid GUID_DEVINTERFACE_USB_DEVICE; m_notifyHandle RegisterDeviceNotificationW( (HANDLE)winId(), filter, DEVICE_NOTIFY_WINDOW_HANDLE); if (!m_notifyHandle) { qWarning() RegisterDeviceNotification failed: GetLastError(); } } bool UsbWatcher::nativeEvent(const QByteArray eventType, void *message, long *result) { MSG *msg static_castMSG *(message); if (msg-message WM_DEVICECHANGE) { PDEV_BROADCAST_HDR pHdr reinterpret_castPDEV_BROADCAST_HDR(msg-lParam); if (pHdr pHdr-dbch_devicetype DBT_DEVTYP_DEVICEINTERFACE) { PDEV_BROADCAST_DEVICEINTERFACE pDevInf reinterpret_castPDEV_BROADCAST_DEVICEINTERFACE(pHdr); QString devicePath QString::fromWCharArray(pDevInf-dbcc_name); // devicePath 形如 \\?\USB#VID_1234PID_5678#... if (msg-wParam DBT_DEVICEARRIVAL) { emit deviceArrived(devicePath); } else if (msg-wParam DBT_DEVICEREMOVECOMPLETE) { emit deviceRemoved(devicePath); } } } return QWidget::nativeEvent(eventType, message, result); }这段代码的逻辑分三步。第一步在构造函数里调用RegisterDeviceNotificationW告诉系统“这个窗口关心 USB 设备类的变化”GUID_DEVINTERFACE_USB_DEVICE是 USB 设备接口类的标准 GUID注册一次就行。第二步nativeEvent里拦截WM_DEVICECHANGE判断lParam指向的是不是设备接口广播。第三步根据wParam区分到达和移除把设备路径发出去。参数上要注意dbcc_classguid如果你只关心某一类设备比如 HID可以换成GUID_DEVINTERFACE_HID。但大多数情况下用 USB 设备类就够了后面再根据 VID、PID 过滤。dbcc_name里已经包含了 VID 和 PID格式是\\?\USB#VID_xxxxPID_xxxx#...你可以用正则把它抠出来。3.2 Linux 下用 udev 监听并解析设备属性Linux 这边用 libudev。先在.pro里加上LIBS -ludev然后写一个监听类。udev 的监听套接字要挂到 Qt 的事件循环里用QSocketNotifier来触发读取。// linux_usb_watcher.h #include QObject #include QSocketNotifier #include libudev.h class LinuxUsbWatcher : public QObject { Q_OBJECT public: explicit LinuxUsbWatcher(QObject *parent nullptr); ~LinuxUsbWatcher(); signals: void deviceArrived(const QString vid, const QString pid, const QString devNode); void deviceRemoved(const QString devNode); private slots: void onUdevEvent(); private: struct udev *m_udev nullptr; struct udev_monitor *m_monitor nullptr; QSocketNotifier *m_notifier nullptr; };// linux_usb_watcher.cpp #include linux_usb_watcher.h #include QDebug #include fcntl.h LinuxUsbWatcher::LinuxUsbWatcher(QObject *parent) : QObject(parent) { m_udev udev_new(); if (!m_udev) { qWarning() udev_new failed; return; } m_monitor udev_monitor_new_from_netlink(m_udev, udev); // 只过滤 usb 子系统减少无关事件 udev_monitor_filter_add_match_subsystem_devtype(m_monitor, usb, nullptr); udev_monitor_enable_receiving(m_monitor); int fd udev_monitor_get_fd(m_monitor); m_notifier new QSocketNotifier(fd, QSocketNotifier::Read, this); connect(m_notifier, QSocketNotifier::activated, this, LinuxUsbWatcher::onUdevEvent); } void LinuxUsbWatcher::onUdevEvent() { struct udev_device *dev udev_monitor_receive_device(m_monitor); if (!dev) return; const char *action udev_device_get_action(dev); const char *vid udev_device_get_sysattr_value(dev, idVendor); const char *pid udev_device_get_sysattr_value(dev, idProduct); const char *devNode udev_device_get_devnode(dev); if (action vid pid) { if (QString(action) add) { emit deviceArrived(QString(vid), QString(pid), QString(devNode ? devNode : )); } else if (QString(action) remove) { emit deviceRemoved(QString(devNode ? devNode : )); } } udev_device_unref(dev); }逻辑说明udev_monitor_new_from_netlink创建一个 netlink 监听udev_monitor_filter_add_match_subsystem_devtype把事件限定在 usb 子系统避免硬盘、网卡的事件也涌进来。udev_monitor_get_fd拿到文件描述符后用QSocketNotifier监听可读事件这样就能融入 Qt 的事件循环不用另开线程。收到事件后udev_device_get_sysattr_value读idVendor和idProduct这两个属性就是 VID 和 PID 的十六进制字符串。参数上idVendor和idProduct是 sysfs 属性不是所有设备节点都有比如 USB 接口设备可能没有devnode但 VID、PID 一般都在。如果你的设备是串口devNode会是/dev/ttyUSB0这种可以直接拿去打开。3.3 用 libusb 热插拔回调做跨平台统一如果你不想维护两套代码libusb 的热插拔回调值得一试。先在.pro里加LIBS -lusb-1.0然后注册回调。// libusb_hotplug_watcher.cpp #include libusb-1.0/libusb.h #include QDebug static int hotplugCallback(libusb_context *ctx, libusb_device *dev, libusb_hotplug_event event, void *userData) { struct libusb_device_descriptor desc; libusb_get_device_descriptor(dev, desc); if (event LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED) { qDebug() Arrived VID: QString::number(desc.idVendor, 16) PID: QString::number(desc.idProduct, 16); } else if (event LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT) { qDebug() Removed VID: QString::number(desc.idVendor, 16) PID: QString::number(desc.idProduct, 16); } return 0; } void setupLibusbHotplug() { libusb_context *ctx nullptr; libusb_init(ctx); libusb_hotplug_callback_handle handle; // 监听所有 VID/PID 的 USB 设备实际项目里建议填上具体 VID/PID int rc libusb_hotplug_register_callback( ctx, (libusb_hotplug_event)(LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED | LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT), LIBUSB_HOTPLUG_NO_FLAGS, LIBUSB_HOTPLUG_MATCH_ANY, // VID LIBUSB_HOTPLUG_MATCH_ANY, // PID LIBUSB_HOTPLUG_MATCH_ANY, // 设备类 hotplugCallback, nullptr, handle); if (rc ! LIBUSB_SUCCESS) { qWarning() hotplug register failed: libusb_error_name(rc); } }这里的关键参数是三个LIBUSB_HOTPLUG_MATCH_ANY分别对应 VID、PID 和设备类。实际项目里我一般会把 VID、PID 填成具体值这样回调只在目标设备插拔时触发省得被无关设备干扰。libusb_hotplug_register_callback注册后libusb 内部会在后台处理事件但你需要确保 libusb 的事件处理循环在跑通常是在 Qt 里开一个低优先级线程调用libusb_handle_events。注意libusb 热插拔在 Windows 上依赖系统消息如果你的程序没有窗口或消息循环回调可能不触发。纯控制台程序要额外处理。4. 避坑与排查设备插拔检测里最容易翻车的五件事4.1 设备到达事件来了但 VID/PID 读出来是空的现象是回调触发了但idVendor或idProduct返回空字符串。原因通常是事件到达时设备节点还没完全创建好sysfs 属性还没生成。Windows 上表现为dbcc_name里信息不全Linux 上表现为udev_device_get_sysattr_value返回 nullptr。解决办法是在回调里加一个短延迟比如 200 到 500 毫秒再去读属性或者干脆在收到到达事件后重新枚举一次设备列表用 VID、PID 去匹配。4.2 同一个设备触发多次到达事件插一个 USB 转串口结果收到两三次DBT_DEVICEARRIVAL。这是因为一个物理设备可能对应多个设备接口比如串口接口和厂商自定义接口各广播一次。如果不去重界面就会重复添加设备项。解决办法是用设备路径或 VIDPID序列号做唯一键收到事件后先查重已经存在的就跳过。Linux 下 udev 也可能对同一个物理设备的多个接口分别发事件同样需要去重。4.3 Linux 下普通用户没有权限监听 udev程序在 root 下跑得好好的普通用户一跑就收不到事件。原因是 udev 的 netlink 套接字对普通用户有权限限制或者你的程序没有加入合适的用户组。解决办法是给可执行文件加上 udev 规则或者把用户加入plugdev组。更稳妥的做法是在程序里检测权限没权限时降级为轮询并给出提示而不是直接静默失败。4.4 Windows 下 nativeEvent 收不到 WM_DEVICECHANGE有时候nativeEvent压根不触发。常见原因有三个一是窗口还没创建就调用了RegisterDeviceNotificationwinId()返回无效句柄二是注册时用的 GUID 不对比如用了GUID_DEVINTERFACE_USB_HUB而不是GUID_DEVINTERFACE_USB_DEVICE三是程序用了QApplication但主窗口被隐藏或销毁了。解决办法是把注册放到showEvent里确保窗口句柄有效GUID 用标准设备类如果窗口会隐藏考虑用DEVICE_NOTIFY_SERVICE_HANDLE或换 libusb。4.5 拔掉设备后句柄没释放再插就打开失败这是血泪经验。设备移除事件里只更新了界面但没有关闭之前打开的QSerialPort或 libusb 句柄导致文件描述符泄漏。下次同一设备插入系统分配的节点名可能变了或者旧句柄还占着资源打开就报错。解决办法是在deviceRemoved信号对应的槽里先close()再deleteLater()确保资源释放干净。libusb 那边要调用libusb_close并libusb_unref_device。5. 进阶技巧把 VID/PID 过滤、去重和热插拔测试串成一条线5.1 用 QRegularExpression 从设备路径里抠 VID/PIDWindows 的dbcc_name格式比较固定用正则提取最省事。下面这个片段可以直接用。#include QRegularExpression QPairQString, QString parseVidPid(const QString devicePath) { // 匹配 VID_xxxx 和 PID_xxxx忽略大小写 QRegularExpression re(VID_([0-9A-Fa-f]{4})PID_([0-9A-Fa-f]{4})); QRegularExpressionMatch match re.match(devicePath); if (match.hasMatch()) { return {match.captured(1).toUpper(), match.captured(2).toUpper()}; } return {, }; }这个正则只认四位十六进制VID_和PID_之间的是 Windows 设备路径的标准分隔符。拿到之后统一转大写方便跟配置文件里的白名单比对。Linux 那边idVendor和idProduct本身就是四位十六进制字符串直接toUpper()即可。5.2 维护一个设备白名单只响应目标设备实际项目里不可能对所有 USB 设备都做反应通常只关心一两个 VID/PID。我一般会在配置文件里写一个白名单程序启动时加载回调里先查白名单再发信号。struct UsbFilter { QString vid; QString pid; QString description; }; // 从 JSON 配置加载 QListUsbFilter loadFilters(const QString path) { QListUsbFilter filters; QFile file(path); if (!file.open(QIODevice::ReadOnly)) return filters; QJsonArray arr QJsonDocument::fromJson(file.readAll()).array(); for (const auto item : arr) { QJsonObject obj item.toObject(); filters.append({obj[vid].toString().toUpper(), obj[pid].toString().toUpper(), obj[description].toString()}); } return filters; }配置文件大概长这样[ { vid: 1A86, pid: 7523, description: USB转串口模块 }, { vid: 0483, pid: 5740, description: 虚拟串口设备 } ]这样换设备只需要改 JSON不用重新编译。查白名单时用 VID 和 PID 同时匹配避免同 VID 不同 PID 的设备误触发。5.3 热插拔测试的土办法与自动化思路测试热插拔最直接的办法就是手动拔插但拔插几十次之后人容易麻木漏掉偶发问题。我一般会写一个简单的测试脚本在 Linux 下用usbip或者直接控制 USB 集线器的电源来模拟插拔Windows 下则用devcon命令禁用再启用设备。更土但有效的办法是拿一个带开关的 USB 集线器手动开关电源同时让程序打日志跑一晚上看有没有漏事件或重复事件。自动化方面可以在程序里加一个统计计数器记录到达和移除的次数跟实际拔插次数比对。如果到达次数大于拔插次数说明有重复事件如果小于说明有漏事件。这个计数器在调试阶段非常有用能帮你快速判断是系统没发事件还是程序处理逻辑有问题。5.4 一个容易忽略的细节事件循环与线程安全不管用哪种方案设备事件最终都要回到 Qt 的主线程来更新界面。如果你在 libusb 的回调线程里直接操作 UI程序迟早崩。我习惯的做法是回调里只做数据提取然后通过QMetaObject::invokeMethod把结果抛到主线程或者用信号槽跨线程连接。QSocketNotifier和nativeEvent本身就在主线程不用额外处理但 libusb 的回调线程一定要小心。从那以后我每次做 USB 检测都会先把事件循环和线程归属画清楚再动手写代码。希望帮到你。本文还有配套的精品资源点击获取