解决 Ubuntu 上 Qt Creator 项目编译失败的问题

关键词: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 配置

  1. 打开终端,编辑 ~/.bashrc:

    复制代码
    nano ~/.bashrc
  2. 找到并注释掉 (在行首添加 #)以下行:

    复制代码
    # export LD_LIBRARY_PATH=$QT6_PATH/lib:$LD_LIBRARY_PATH
  3. 保存并使配置生效:

    复制代码
    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 中:

  1. 点击左侧 项目 (Projects) 图标

  2. 在 Build 选项卡中,点击 Clear CMake Configuration

  3. 重新点击 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 环境编写,其他版本可能略有差异。

相关推荐
隔窗听雨眠19 小时前
SQL执行计划固化的原理与稳定性工程
数据库·sql优化·执行计划
TDengine (老段)21 小时前
TDengine IDMP 功能点—数据接入
大数据·数据库·物联网·时序数据库·tdengine·涛思数据
索西引擎21 小时前
MySQL 进阶:视图、存储过程、存储函数与触发器
数据库·mysql
ShineWinsu1 天前
对于Qt:QHBoxLayout常见属性以及方法的解析
c++·qt·面试·gui·客户端·布局管理器·水平布局器
bksczm1 天前
InnoDB 通用表空间与临时表空间详解
大数据·数据库·mysql
靠沿1 天前
MySQL数据库进阶——存储过程和触发器
java·数据库·mysql
码少女1 天前
MySQL--库与表的增删改查基础
java·数据库·mysql
Eyfcom1 天前
〖物流 SaaS 实战 02〗SaaS 租户的计费与订阅模型:从“一锤子买卖”到“按需订阅”
linux·服务器·数据库·快递系统·物流saas实战
打工的小王1 天前
postgresql和mysql对比
数据库·mysql·postgresql
敲上瘾1 天前
Qt核心机制:信号与槽详解
开发语言·c++·qt·ui·qt6.3