关键词：Qt6, Qt Creator, Ubuntu, CMake, LD_LIBRARY_PATH, 缺少依赖, libgl1-mesa-dev
在 Ubuntu 24.04 上使用 Qt 6 进行开发时，可能会遇到以下令人沮丧的问题：
-
Qt Creator 启动时崩溃，报错
undefined symbol -
项目配置失败，CMake 提示
configuration failed -
MaintenanceTool 无法正常工作
本文将深入分析这些问题的根本原因，并提供完整的解决方案。
问题现象
现象一：Qt Creator 启动崩溃
运行 Qt Creator 时，终端输出类似错误：
libQt6Gui.so.6: undefined symbol: _Zls6QDebugRK15QDBusObjectPath, version Qt_6现象二：Qt Creator 项目配置失败
在 Qt Creator 中打开项目后，底部"问题"面板显示：
CMake project configuration failed. No CMake configuration found.
Qt MaintenanceTool returned an error.
The command "/home/xxx/Qt/Tools/CMake/bin/cmake ..." terminated with exit code 1.问题根因分析
经过排查，发现问题由两个独立原因共同导致：
原因一：LD_LIBRARY_PATH 环境变量冲突
在配置 Qt 开发环境时，很多教程会建议在 ~/.bashrc 中添加以下内容：
export QT6_PATH=/home/lwz/Qt/6.5.3/gcc_64
export LD_LIBRARY_PATH=$QT6_PATH/lib:$LD_LIBRARY_PATH问题在于 ：Qt Creator 自带了一套完整的 Qt 运行时库（通常版本与您安装的 SDK 不同）。当您在终端启动 Qt Creator 时，它会优先加载您在 LD_LIBRARY_PATH 中指定的旧版库，导致符号版本不匹配，从而崩溃。
全局设置 LD_LIBRARY_PATH 是 Linux 开发中的常见陷阱。它会影响所有程序的动态库加载行为，极易导致难以排查的兼容性问题。
原因二：缺少系统级开发依赖库
Qt 在线安装器 (qt-online-installer) 只会下载 Qt 框架本身，不会安装编译 Qt 程序所需的系统库。
例如，Qt6Gui 模块在编译时需要链接到 OpenGL 和 X11 的开发头文件。如果系统缺少这些 -dev 包，CMake 配置阶段就会失败。
| 依赖类型 | 运行时库（系统已有） | 开发库（需额外安装） |
|---|---|---|
| OpenGL | libgl1-mesa-glx |
libgl1-mesa-dev |
| X11 | libx11-6 |
libx11-xcb-dev |
| XKB | libxkbcommon0 |
libxkbcommon-dev |
解决方案
步骤一：移除 LD_LIBRARY_PATH 配置
-
打开终端，编辑
~/.bashrc：nano ~/.bashrc -
找到并注释掉 （在行首添加
#）以下行：# export LD_LIBRARY_PATH=$QT6_PATH/lib:$LD_LIBRARY_PATH -
保存并使配置生效：
source ~/.bashrc
您不需要设置 LD_LIBRARY_PATH，因为 Qt 应用在编译时会通过 RPATH 机制自动记录库的搜索路径。
步骤二：安装系统开发依赖
运行以下命令安装 Qt 6 开发所需的全部系统库：
sudo apt-get update
sudo apt-get install -y \
build-essential \
libgl1-mesa-dev \
libglu1-mesa-dev \
libx11-xcb-dev \
libxrender-dev \
libxi-dev \
libxkbcommon-dev \
libxkbcommon-x11-dev步骤三：清理并重新配置项目
在 Qt Creator 中：
-
点击左侧 项目 (Projects) 图标
-
在 Build 选项卡中，点击 Clear CMake Configuration
-
重新点击 Configure Project 或直接点击构建按钮
验证修复
您可以在终端中手动验证：
# 验证 Qt Creator 可以启动
/home/lwz/Qt/Tools/QtCreator/bin/qtcreator --version
# 验证项目可以编译（以 untitled6 为例）
cd ~/qtu/untitled6/build/Desktop_Qt_6_5_3_GCC_64bit-Debug/
/home/lwz/Qt/Tools/CMake/bin/cmake -S ~/qtu/untitled6 -B .
cmake --build .如果看到 [5/5] Linking CXX executable untitled6 等输出，说明问题已完全解决。
总结
| 问题 | 根因 | 解决方案 |
|---|---|---|
| Qt Creator 启动崩溃 (undefined symbol) | ~/.bashrc 中的 LD_LIBRARY_PATH 干扰了 Qt Creator 自带库的加载 |
注释掉该行 |
| CMake 配置失败 | 系统缺少 OpenGL/X11 开发库 | apt install libgl1-mesa-dev ... |
Qt 在线安装器不会安装系统依赖，这是设计如此。在任何新 Linux 环境中使用 Qt 开发前，请务必先安装开发依赖。
参考链接
本文基于 Ubuntu 24.04 + Qt 6.5.3 环境编写，其他版本可能略有差异。