如何在CMakeLists.txt中添加Qt私有头文件？

要在CMake项目的CMakeLists.txt里添加Qt私有头文件的支持，关键就是在find_package指令中明确声明对应的私有组件，下面是具体的配置步骤和说明：

核心配置示例 #

Qt的私有组件命名通常是在公共组件名称后加上Private后缀，比如Quick组件对应的私有组件是QuickPrivate。你可以这样配置：

# 先查找Qt版本（优先Qt6，其次Qt5），同时指定需要的公共组件和私有组件
find_package(QT NAMES Qt6 Qt5 COMPONENTS Core Quick QuickPrivate REQUIRED)
# 根据检测到的Qt主版本，再次查找对应版本的组件（保证版本一致性）
find_package(Qt${QT_VERSION_MAJOR} COMPONENTS Core Quick QuickPrivate REQUIRED)

配置说明 #

• 第一行的find_package(QT ...)用来检测系统中安装的Qt版本，同时指定我们需要的公共组件（Core、Quick）和私有组件（QuickPrivate），REQUIRED表示如果找不到这些组件就终止构建。
• 第二行则根据第一行得到的QT_VERSION_MAJOR（值为5或6），精准查找对应大版本的Qt组件，确保整个项目使用的Qt版本统一。

配置完成后，CMake会自动将对应私有组件的头文件路径添加到项目的包含目录中，你就可以在代码中直接引用私有头文件了，比如：

#include <private/qquickitem_p.h>

重要提醒 #

⚠️ 注意：Qt的私有API是不对外承诺兼容性的，不同Qt版本之间私有头文件的内容、结构可能会发生变化。如果你的项目依赖了私有API，在升级Qt版本时很可能会出现编译错误或运行问题，所以除非有特殊需求（比如需要扩展Qt的内部功能），建议优先使用Qt的公共API。

内容的提问来源于stack exchange，提问作者xavi-b