Qt serialport模块识别失败问题求助及解决记录

问题场景 #

使用Qt Creator 10.0.1搭配Qt 6.5.1版本，通过Qt维护工具安装了QtSerialPort 6.5.2版本，已在项目.pro文件中添加QT += serialport配置，但编译时仍出现「Unknown module(s) in QT: serialport」错误。原本认为同属6.5系列的版本可以兼容，最终将整个项目切换为Qt 6.5.3版本后，问题得以解决。

核心原因 #

Qt的模块（如QtSerialPort）与Qt主框架的版本必须严格完全匹配，哪怕是同大版本下的小版本差异（比如6.5.1和6.5.2）也会导致qmake无法识别模块。这是因为Qt模块的安装路径与对应主版本的Qt目录绑定，不同小版本的模块不会被跨版本的Qt环境加载识别。

可行解决办法 #

• 卸载已安装的QtSerialPort 6.5.2，通过Qt维护工具安装与Qt主版本完全一致的QtSerialPort（即6.5.1版本），确保模块版本和主框架版本一一对应。
• 升级Qt主框架到与已安装的SerialPort模块匹配的版本，或直接升级到更高兼容版本（如用户实际操作的切换到Qt 6.5.3，此时维护工具会自动匹配安装对应版本的QtSerialPort模块）。

附：项目.pro文件代码 #

QT  += core gui
QT  += serialport

greaterThan(QT_MAJOR_VERSION, 4): QT += widgets printsupport

CONFIG += c++17

# You can make your code fail to compile if it uses deprecated APIs.
# In order to do so, uncomment the following line.
DEFINES += QT_DISABLE_DEPRECATED_BEFORE=0x060000    # disables all the APIs deprecated before Qt 6.0.0

QMAKE_CXXFLAGS += -Wa,-mbig-obj # This line is for QCustomPlot to work

SOURCES += \
    main.cpp \
    mainwindow.cpp \
    qcustomplot.cpp

HEADERS += \
    mainwindow.h \
    qcustomplot.h

FORMS += \
    mainwindow.ui

RESOURCES += \
    resources.qrc

# Default rules for deployment.
qnx: target.path = /tmp/$${TARGET}/bin
else: unix:!android: target.path = /opt/$${TARGET}/bin
!isEmpty(target.path): INSTALLS += target

内容的提问来源于stack exchange，提问作者loora