如何解决CMake构建Qt项目时QSerialPortInfo未定义引用报错

该报错属于典型的链接阶段依赖库缺失问题，已完成Qt SerialPort模块查找但仍出现报错，可按以下步骤依次排查：

• 检查目标链接配置
  find_package仅完成库路径查找，不会自动将依赖库添加到目标的链接列表中，你需要为你的可执行文件/动态库目标显式链接Qt5::SerialPort模块。示例配置如下：

  # 假设你的目标名为MyProject，根据实际情况修改
  add_executable(MyProject main.cpp xxx.cpp)
  target_link_libraries(MyProject PRIVATE
      Qt5::Core
      Qt5::Widgets
      Qt5::Gui
      Qt5::SerialPort
  )
  

• 检查Qt版本与组件完整性
  确认你安装的Qt5套件包含SerialPort组件，且项目全局没有混用Qt5与Qt6依赖，可添加以下代码打印配置验证：

  message(STATUS "Qt5 全局版本: ${Qt5_VERSION}")
  message(STATUS "SerialPort 组件是否找到: ${Qt5SerialPort_FOUND}")
  

  若Qt5SerialPort_FOUND值为OFF，需重新安装对应Qt5版本的SerialPort组件。
• 清理旧构建缓存重新编译
  旧的CMake构建缓存可能残留错误的依赖配置，删除整个build目录后重新生成配置编译即可：

  # Linux/macOS 清理构建命令
  rm -rf build && mkdir build && cd build && cmake .. && make
  

  # Windows PowerShell 清理构建命令
  rmdir /s /q build; mkdir build; cd build; cmake ..; cmake --build .
  

• 检查代码头文件引入
  确认调用QSerialPortInfo的源文件已引入对应头文件：

  #include <QSerialPortInfo>
  

  头文件缺失通常触发编译阶段报错，但若存在同名自定义类或特殊编译配置时也可能引发链接异常，可作为兜底排查项。

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