Qt自定义控件bug记录

Bug 原因深度分析（针对 CMake 构建的 Qt6.8 项目）

从你的项目结构（CMake 构建）和报错信息来看，核心问题出在UI 提升配置错误 + CMake 包含路径缺失 ，导致自动生成的ui_widget.h用了错误的头文件包含方式：

---

一、核心 Bug 原因

1. UI 文件提升配置错误（直接导致尖括号包含）

在 Qt Designer 中提升自定义控件时，你可能误将头文件路径设置为 ```（尖括号），而非相对路径的``"form.h"`（双引号）。

• 自动生成的 ui_widget.h 中出现了 #include（尖括号是系统库包含语法），而 form.h 是你的自定义头文件，编译器会去系统路径查找，自然找不到。

• 正确的包含方式应该是 #include "form.h"（双引号，项目路径包含）。

2. CMake 配置缺失（头文件路径未被包含）

你的 CMakeLists.txt 没有将 form.h 所在的目录（如 Header Files 虚拟分组对应的物理路径）添加到编译器的包含路径中，即使 UI 生成的代码用了双引号，编译器也无法定位到 form.h。

3. 构建缓存残留

CMake/Ninja 的构建缓存可能保留了旧的错误配置，导致修改后仍无法生效。

---

二、分步骤解决方案（适配 CMake 项目）

步骤 1：修复 UI 文件的提升配置（关键）

1. 打开 widget.ui（Qt Designer），找到被提升为自定义控件的 QWidget。

2. 右键该控件 → 提升为...（Promote to...）。

3. 在弹出的对话框中：

   • 确保 "提升的类名称（Promoted class name）" 为 Form（与 form.h 中的类名一致）。

   • 修正 "头文件（Header file）" 为 form.h（双引号包裹的相对路径，不要用尖括号）。

   • 点击 "添加（Add）"→"提升（Promote）"，保存 UI 文件。

4. 重新生成 UI 文件：右键 widget.ui → 编译（Compile） ，确保新生成的 ui_widget.h 中包含的是 #include "form.h"（双引号）。

步骤 2：修改 CMakeLists.txt 配置（必做）

打开项目根目录的 CMakeLists.txt，添加以下配置，确保头文件路径被正确包含：

cmake

cmake_minimum_required(VERSION 3.16)
​
project(12_myWidget LANGUAGES CXX)
​
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
​
# Qt相关配置
find_package(Qt6 REQUIRED COMPONENTS Core Widgets)
qt_standard_project_setup()
​
# 1. 添加头文件包含路径（关键：让编译器找到form.h）
# 如果Header Files是虚拟分组，实际文件在项目根目录，直接包含项目根目录
include_directories(${PROJECT_SOURCE_DIR})
# 如果Header Files是实际子文件夹（如存在物理路径Header Files），则：
# include_directories("${PROJECT_SOURCE_DIR}/Header Files")
​
# 2. 收集所有源文件、头文件、UI文件
set(SOURCES
    main.cpp
    widget.cpp
    form.cpp
)
​
set(HEADERS
    widget.h
    form.h
)
​
set(FORMS
    widget.ui
    form.ui
)
​
# 3. 生成可执行文件并链接Qt库
qt_add_executable(12_myWidget
    ${SOURCES}
    ${HEADERS}
    ${FORMS}
)
​
target_link_libraries(12_myWidget PRIVATE Qt6::Core Qt6::Widgets)

步骤 3：彻底清理构建缓存

1. 关闭 Qt Creator，删除项目根目录下的 build 文件夹（即报错中的 Desktop_Qt_6_8_2_MinGW_64_bit-Debug 目录）。

2. 重新打开 Qt Creator，选择 "构建"→"重新配置项目"，让 CMake 重新生成配置。

3. 点击 "构建"→"重新构建项目"，确保编译无错误。

步骤 4：验证自动生成的包含语句

打开新生成的 ui_widget.h（路径：build/xxx_autogen/include/ui_widget.h），检查第 15 行是否为：

cpp

运行

#include "form.h" // 双引号，正确

如果仍然是 ``，重复步骤 1 重新配置 UI 提升。

---

三、关键预防措施

1. UI 提升时头文件路径用双引号 ：自定义头文件必须用双引号包含（如 "form.h"），避免尖括号导致系统路径搜索。

2. CMake 包含路径必须配置 ：所有自定义头文件所在的目录都要通过 include_directories 添加到 CMake 配置中。

3. 避免缓存残留：修改 CMake 或 UI 配置后，必须删除 build 文件夹并重新构建，否则旧缓存会导致错误残留。

4. 虚拟分组与物理路径一致：Qt Creator 的 "Header Files" 是虚拟分组，确保实际文件的物理路径与 CMake 配置的包含路径一致。

---

总结

1. 直接原因：UI 提升时头文件路径用了尖括号，导致自动生成的代码包含方式错误。

2. 根本原因：CMake 未配置头文件包含路径，且缓存残留旧配置。

3. 修复顺序：先修正 UI 提升配置 → 再修改 CMake 包含路径 → 最后清理缓存重新构建。