编译Qt6源码时遇winapifamily.h缺失的致命编译错误求助

环境与操作步骤 #

• 目录结构：

C:\
  Qt\
    qt-src  // 源码文件夹
    qt-6    // 构建文件夹

• 配置命令：

..\qt-src\configure.bat -prefix C:\Qt\qt6

• 构建命令：

cmake --build .

错误信息 #

compilation terminated.
[6/9076] Building CXX object qtbase/src/3rdparty/harfbuzz-ng/CMakeFiles/BundledHarfbuzz.dir/hb-dummy.cc.obj
FAILED: qtbase/src/3rdparty/harfbuzz-ng/CMakeFiles/BundledHarfbuzz.dir/hb-dummy.cc.obj
C:\MinGW\bin\c++.exe -DHAVE_ATEXIT -DHAVE_CONFIG_H -DHAVE_OT -DHB_EXTERN="" -DHB_NDEBUG -DHB_NO_UNICODE_FUNCS -DHB_NO_WIN1256 -DMINGW_HAS_SECURE_API=1 -DQT_NO_DEBUG -DQT_NO_EXCEPTIONS -DQT_NO_JAVA_STYLE_ITERATORS -DQT_NO_NARROWING_CONVERSIONS_IN_CONNECT -DQT_NO_VERSION_TAGGING -DUNICODE -DWIN32 -DWINVER=0x0A00 -D_ENABLE_EXTENDED_ALIGNED_STORAGE -D_UNICODE -D_USE_MATH_DEFINES -D_WIN32_WINNT=0x0A00 -IC:/Qt/qt-src/qtbase/src/3rdparty/harfbuzz-ng/include/harfbuzz -IC:/Qt/qt-6/qtbase/src/corelib/Core_autogen/include -IC:/Qt/qt-6/qtbase/include -IC:/Qt/qt-6/qtbase/include/QtCore -IC:/Qt/qt-src/qtbase/src/corelib -IC:/Qt/qt-6/qtbase/src/corelib -IC:/Qt/qt-6/qtbase/src/corelib/global -IC:/Qt/qt-6/qtbase/src/corelib/kernel -IC:/Qt/qt-src/qtbase/src/corelib/../3rdparty/tinycbor/src -IC:/Qt/qt-6/qtbase/include/QtCore/6.3.1 -IC:/Qt/qt-6/qtbase/include/QtCore/6.3.1/QtCore -IC:/Qt/qt-src/qtbase/src/corelib/../3rdparty/double-conversion/double-conversion -IC:/Qt/qt-src/qtbase/src/corelib/../3rdparty/double-conversion -IC:/Qt/qt-6/qtbase/src/corelib/.rcc -IC:/Qt/qt-src/qtbase/mkspecs/win32-g++ -IC:/Qt/qt-6/qtbase/include/QtZlib -IC:/Qt/qt-src/qtbase/src/3rdparty/zlib -IC:/Qt/qt-6/qtbase/src/3rdparty/zlib -IC:/Qt/qt-src/qtbase/src/3rdparty/pcre2/src -IC:/Qt/qt-src/qtbase/src/3rdparty/harfbuzz-ng -DNDEBUG -O2 -fvisibility=hidden -fno-keep-inline-dllexport -w -fno-exceptions -Wa,-mbig-obj -std=c++1z -MD -MT qtbase/src/3rdparty/harfbuzz-ng/CMakeFiles/BundledHarfbuzz.dir/hb-dummy.cc.obj -MF qtbase\src\3rdparty\harfbuzz-ng\CMakeFiles\BundledHarfbuzz.dir\hb-dummy.cc.obj.d -o qtbase/src/3rdparty/harfbuzz-ng/CMakeFiles/BundledHarfbuzz.dir/hb-dummy.cc.obj -c C:/Qt/qt-src/qtbase/src/3rdparty/harfbuzz-ng/hb-dummy.cc
In file included from C:/Qt/qt-src/qtbase/src/3rdparty/harfbuzz-ng/src/hb-common.cc:29:0,
                 from C:/Qt/qt-src/qtbase/src/3rdparty/harfbuzz-ng/hb-dummy.cc:7:
C:/Qt/qt-src/qtbase/src/3rdparty/harfbuzz-ng/src/hb.hh:208:26: fatal error: winapifamily.h: No such file or directory
 #include <winapifamily.h>
                          ^
compilation terminated.
ninja: build stopped: subcommand failed

该错误源于MinGW环境缺少Windows SDK中的winapifamily.h头文件，可通过以下方式解决：

方式一：升级MinGW版本 #

较新版本的MinGW-w64已内置该头文件，推荐安装MinGW-w64 8.0及以上版本，优先选择支持UCRT的构建版本（如x86_64-posix-seh或i686-posix-dwarf）。

方式二：手动添加头文件路径 #

若不想升级MinGW，可找到Windows SDK的安装目录（通常为C:\Program Files (x86)\Windows Kits\10\Include\<版本号>\um），将该路径添加到CMake编译参数中：

1. 打开构建目录qt-6下的CMakeCache.txt文件
2. 搜索CMAKE_CXX_FLAGS，在原有参数后追加-IC:/Program Files (x86)/Windows Kits/10/Include/<你的SDK版本号>/um（替换为实际路径）
3. 重新执行cmake --build .

方式三：禁用Harfbuzz依赖（临时方案） #

在configure阶段添加参数，强制跳过Harfbuzz的编译（会影响Qt字体渲染特性）：

..\qt-src\configure.bat -prefix C:\Qt\qt6 -no-harfbuzz

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