报“找不到头文件”不是代码错误，而是编译器未获知搜索路径：INCLUDEPATH未配置或错误、CMake未用target_include_directories指定、提升类头文件路径未被uic识别、或ClangCodeModel误报。

直接说结论：报“找不到头文件”不是代码写错了，而是编译器压根没被告诉去哪找——路径没配对、构建缓存没清、或工具链根本没对齐。

qmake项目里INCLUDEPATH漏加或路径错

这是新手最常踩的坑。Qt Creator不会自动把你的头文件目录加进编译搜索路径，INCLUDEPATH必须手动写。

• 检查 .pro 文件里有没有类似 INCLUDEPATH += $$PWD/include 或 INCLUDEPATH += $$PWD/src/widgets 这样的行
• 路径用 $$PWD（当前项目根目录），别用绝对路径；Linux/macOS 区分大小写，MyWidget.h 和 mywidget.h 是两个文件
• 如果头文件在子目录里，比如 src/core/Config.h，那 INCLUDEPATH += $$PWD/src 就够了，#include "core/Config.h" 才能命中
• 改完 .pro 后，必须右键项目 → “重新运行 qmake”，否则改动不生效

CMakeLists.txt 没把头文件目录传给编译器

CMake 不像 qmake 那样默认读 .pro 里的 INCLUDEPATH，它靠 target_include_directories() 控制搜索路径。

Qt Creator 18.0.2

Qt Creator 18.0.2 Windows x86_64 历史版本安装包，适合需要旧版本 IDE、旧项目兼容、Qt/C++ 项目维护、构建套件配置和调试环境回退的用户使用。

下载

• 确保有类似这样的语句，且作用域正确（通常放在 add_executable() 之后）：

  target_include_directories(MyApp PRIVATE ${CMAKE_SOURCE_DIR}/include)<br>target_include_directories(MyApp PRIVATE ${CMAKE_SOURCE_DIR}/src)

• 别只写 include_directories(...) —— 它是全局的，容易污染其他 target，而且 Qt 6 推荐用 target_* 形式
• 如果用了 find_package(Qt6 REQUIRED COMPONENTS Widgets)，记得后面跟 target_link_libraries(MyApp PRIVATE Qt6::Widgets)，否则 Qt 头文件路径也不会自动注入

提升类（Promoted Widget）头文件路径不被 uic 识别

Qt Designer 里设了提升类，但生成的 ui_*.h 里 #include 的路径不对，编译时自然找不到。

• 先确认提升类的头文件确实存在，且名字和 Designer 里填的“Header file”字段完全一致（包括大小写和扩展名）
• Designer 填的路径是相对路径，起点是 ui_*.h 的生成位置（通常是 build/ 目录），不是源码目录 —— 所以常见写法是 ../../src/widgets/MyButton.h
• 更稳的做法：在 CMakeLists.txt 中显式告诉 uic 哪儿找头文件，加这一行：

  set(CMAKE_AUTOUIC_OPTIONS -i ${CMAKE_SOURCE_DIR}/src/widgets)

• 或者干脆把提升类头文件放到和 .ui 同级目录，Designer 里就填 MyButton.h，最不容易出错

ClangCodeModel 导致编辑器误报，但实际能编译通过

Qt Creator 编辑界面标红说 fatal error: 'stddef.h' file not found，可点构建却成功——这是 Clang 代码模型解析失败，不是真编译错误。

• 打开 帮助 → 选项 → C++ → ClangCodeModel，取消勾选“启用 Clang 代码模型”
• 或者换匹配的 libclang-common 版本：用 apt list --installed | grep libclang-common 查当前版本，卸载新版（如 libclang-common-10-dev），装 Qt Creator 官方支持的旧版（如 libclang-common-8-dev）
• 注意：这个错误只影响编辑器提示，不影响构建。别花时间改 .pro 或 CMakeLists.txt 去“修复”它

真正麻烦的是路径配置和构建系统之间的隐含依赖：qmake 缓存、CMake 生成的中间目录结构、uic 的工作目录、ClangCodeModel 的独立解析逻辑——它们各自有一套路径规则，改一处不联动，就容易断链。动手前先看清楚报错发生在编辑器、构建日志还是链接阶段，再决定动哪块配置。