在 Ubuntu 上装 Qt 这件事我前前后后折腾过很多回。第一回是在刚接触 Linux 的时候以为装个 Qt Creator 就等于装完了 Qt结果编译一个小窗口程序直接报“找不到 platform plugin”第二回是在给嵌入式板子交叉编译 Qt 的时候才发现光装一个桌面版编译器根本不够使再后来在 Ubuntu 服务器上用 Docker 跑 Qt 自动化编译又跟 linuxfb 这种平台插件打了一轮交道。装 Qt 这个操作的弹性非常大简单的一行 apt install 就能搞定复杂的要手动配交叉工具链和完整依赖最麻烦的其实是装完之后的各种运行时报错。这篇文章就把我在 Ubuntu 上从零到一安装和配置 Qt 环境的完整经验整理出来按使用场景分清楚免得后面没人再踩同样的坑。1. 安装 Qt 之前先把需求摸清楚1.1 先想清楚你拿 Qt 做什么很多教程一上来就让你上官网下安装包我反而建议先花五分钟想一个问题你用 Qt 是跑在哪个环境里的这个答案直接决定了安装方案。假如是做桌面应用开发比如写个跨平台的工具软件、上位机、行业客户端那么你的重点就是装一套完整的 Qt 开发环境包含 Qt Creator、对应版本的库文件、CMake 和编译器。这种情况下推荐用官方安装包或者用系统仓库里的稳定版本根据项目需求来定。假如是给嵌入式设备做界面比如树莓派、RK3588 这类 Linux 开发板那你光装一个桌面版 Qt 是不够的还要准备交叉编译工具链和目标设备的 sysroot。这种情况下重点不是“装”而是“配”——把 qmake 指向交叉编译的配置把编译产物丢到板子上跑。qt 的下载和安装倒是最不起眼的部分。假如只是想在 Ubuntu 上写点命令行工具或者带界面的小脚本那直接用 apt 装系统自带的 Qt 版本就够了没必要折腾离线包。系统仓库的 Qt 通常和 Ubuntu 的桌面环境集成得很好性能也够用。不同的用途决定了安装成本和后续排查方向这一步想清楚能省掉后面至少一半的折腾。1.2 看准 Ubuntu 版本、架构和 Qt 版本接着看系统本身。在终端里执行两条命令lsb_release -a uname -alsb_release -a能告诉你当前 Ubuntu 版本号、桌面版本多少uname -a能看到架构信息最常见的是 x86_64树莓派等板子上则是 aarch64。这个信息之所以重要是因为 Qt 的离线安装包、apt 仓库的包版本和交叉编译工具链都是跟架构绑死的。再说 Qt 版本选择。Ubuntu 22.04 LTS 的官方源里Qt 5.15.x 是老牌稳定版Ubuntu 24.04 则提供了 Qt 6.x 的包。Qt 5 和 Qt 6 的 API 有差异QML 模块变化也比较大。一般来说如果是维护老项目优先 Qt 5.15.2LTS 版本第三方库兼容性最好如果是新项目或想用较新的 QML/Quick 特性优先 Qt 6.2 以上如果是嵌入式还要看目标板子的 BSP 里带的 Qt 版本这个往往是定死的。有一点要提醒你不要在同一台机器上同时使用系统仓库的 Qt 5 和官网的 Qt 6Python 或者第三方库调用 Qt 时很容易混淆版本编译时头文件和运行时库对不上就会冒出一堆奇怪的错误。我后面会专门讲那个“cannot mix incompatible Qt library”的报错就是典型的版本混用问题。2. 两条安装路径系统仓库和官方安装包2.1 最省事的方式apt 直接装如果只是做桌面开发或者想快速跑起来验证一下用 apt 是最省事的。以 Ubuntu 22.04 为例执行sudo apt update sudo apt install qt6-base-dev qt6-tools-dev qtcreator cmake g需要 Qt 5 的话sudo apt install qtbase5-dev qttools5-dev qtcreator这里qtbase5-dev提供 Qt 的核心模块和开发头文件qttools5-dev提供 uic、moc、rcc 等辅助工具qtcreator就是那个集成开发环境。cmake和g是 Qt6 项目默认的编译工具链缺一个都会在建 Kit 的时候卡住。安装完成后你可以直接运行qtcreator启动 IDE在“工具 - 选项 - Kits”里确认编译器已经被自动识别。apt 装的 Qt 有一个很大的好处它由系统包管理器统一管理卸载干净不会留下手动安装时的残留文件。缺点也很明显版本更新慢官方源里的 Qt 往往落后于官网几个小版本对某些新特性要求高的项目可能不够。另外如果你发现sudo apt install qtcreator之后编译 Qt 连GL/gl.h都找不到那是缺了 OpenGL 开发库。Qt 的窗口渲染底层依赖 OpenGL所以推荐把这些包也装上sudo apt install libgl1-mesa-dev libglu1-mesa-dev libxkbcommon-x11-dev libxcb-xkb1 libxcb-icccm4-dev libxcb-image0-dev libxcb-keysyms1-dev libxcb-render-util0-dev这些包看起来不起眼实际上很多运行时报错都是因为它们没装全导致的。就算你用 apt 能打开 Qt Creator缺了这些库也可能会在运行动态库时报错到时候定位半天其实只是少装了一个 xcb 插件依赖。2.2 更可控的方式官方离线安装包对于需要特定 Qt 版本、特殊模块或者嵌入式定制版 Qt 的场景推荐去 Qt 官网下载离线安装包。在下载页面里找到qt-opensource-linux-x64-5.15.2.run一类的文件注意区分 Linux 那个版本号。下载完记得授权执行chmod x qt-opensource-linux-x64-5.15.2.run sudo ./qt-opensource-linux-x64-5.15.2.run执行之后进入图形化安装界面需要登录 Qt 账号组件列表里选择你要的版本和模块。这里有个经验点只勾需要的组件别贪多安装 Qt 的组件越多硬盘占用越大而且不同模块之间的依赖越复杂。最典型的组合是Qt 5.15.2主库Qt CreatorIDEDevelopment and Designer tools里面的 Qt Designer 单独运行工具如果你要交叉编译还可以在安装器里勾上对应平台的 qmake。不过离线安装包有个很坑的地方它默认装到/opt/Qt5.15.2这类目录下普通用户对该目录只有读权限安装完成之后生成的临时文件和缓存在~/.config里一般不会有权限问题。但编译项目的时候如果项目工程文件里自动写了绝对路径建议检查一下路径是不是真的指向了你安装的目录。我碰上过好几回明明装的是 5.15.2工程文件里却写的是 5.15.0 的构建目录结果编译时各种找不到头文件。这个问题早期特别容易忽略。2.3 装完第一件事检查编译器、qmake 和 CMake 是否在同一个“同步轨道”不管用哪条安装路径装完之后推荐立刻在终端里检查三条命令qmake -v cmake --version g --version如果qmake -v弹出来的版本跟你预期的不一致比如你在/opt里装了 Qt 5.15.2但qmake指向的却是/usr/bin/qmake那说明 PATH 里系统包的优先级更高。这时候要么重设 PATH要么在权限设置里面明确指定 qmake 的路径。这个问题很常见尤其在同时使用 apt 和官方包的时候。cmake 也要注意版本Qt6 要求 CMake 3.16 以上某些早期版本 Ubuntu 自带的 cmake 太老会编译失败。如果版本不够可以先sudo apt upgrade cmake或者用官方 pip 安装的 cmake 作为替代。实际工作中我发现如果项目是能选择 QMake 来构建通常直接用 Qt 自带的 QMake 就能解决很多问题因为 CMake 处理不好时出错信息极其难排查。3. 配置 Qt Creator、Qt Designer 和环境变量3.1 Kit 配置里到底发生了什么Qt Creator 里的“Kit”是把编译器、调试器、Qt 版本和 CMake 工具都合并成一个构建环境。如果你只安装了一个 Qt 版本它通常能自动识别但当你手动离线安装后在 Qt Creator 的“工具 - 选项 - Kits”里可能看不到新安装的 Qt 版本是因为没有把它注册进去。具体操作在“Qt Versions”标签页添加/opt/Qt5.15.2/5.15.2/gcc_64/bin/qmake让它扫描到这个 Qt 库。然后在“Kits”标签页新建一个 Kit把编译器、调试器和 Qt 版本都选到对应的项。这里有一个经常被忽略的地方编译器不是“选一个就行”C编译器要选gccC编译器要选g如果只填了 C 编译器有些项目在解析 C 源文件时候就会报找不到头文件。还有一点如果你做的是 QML 开发建议额外安装qml-module-qtquick2这类模块否则在 Qt Creator 里打开 QML 文件会提示各种模块缺失。桌面 Ubuntu 下系统源里可以安装一部分但如果你用官方包则直接下载对应的源模块进行编译也没问题。3.2 想单独用 Qt Designer 的话Qt 官方把 UI 设计工具叫 Qt Designer在 Qt Creator 里虽然也有集成但很多人不知道它还可以单独跑。单独跑的好处是可以脱离整个 IDE快速设计.ui文件然后直接交给同事或者脚本去构建。在 apt 安装的路径下运行designer启动之后就是独立的界面编辑器左上角是控件面板中间是画布右下角是属性编辑器。如果你是从官网安装的designer在/opt/Qt5.15.2/Tools/QtCreator/bin里也带一个但那个版本通常跟 IDE 绑定的比较紧独立运行时反而会遇到平台插件的问题。要我说真正高效的用法是UI 复杂的时候单独开 designer 来拖控件保存.ui文件进工程这样比在 Creator 里切来切去顺畅得多。尤其在你需要做批量界面调整的时候独立 designer 可以开多个窗口对比观察方便不少。开发过程中生成.ui文件后一般不需要手动跑 uic编译项目时 qmake 或 cmake 会自动把.ui文件转换成ui_xxx.h头文件。新手容易犯的错误是改了.ui之后没有重新编译导致代码里引用的控件已经改名了但编译后还是找不到对应控件。这个问题的解决办法就一个改完.ui一定重新make clean或者rm -rf build再重新构建一次。3.3 PATH 和 LD_LIBRARY_PATH 的坑装完 Qt 之后把 Qt 的 bin 目录加进 PATH 是常规操作。编辑~/.bashrc加入export PATH/opt/Qt5.15.2/5.15.2/gcc_64/bin:$PATH如果安装目录不是你的家目录还要考虑LD_LIBRARY_PATH的问题。Qt 运行的时候需要加载 Qt 的动态库系统默认搜索路径里往往没有/opt/Qt5.15.2/5.15.2/gcc_64/lib所以可以export LD_LIBRARY_PATH/opt/Qt5.15.2/5.15.2/gcc_64/lib:$LD_LIBRARY_PATH这里我必须把丑话说在前面依赖LD_LIBRARY_PATH作为长期的解决方案是一个很隐蔽的坑。很多临时变量会导致系统其它软件产生莫名的链接冲突比如你某天运行系统的 Python 或 PyQt5 程序发现它开始报 Qt 版本混乱很可能就是这个变量把系统的库搜索路径带偏了。所以如果只是开发用可以接受如果是部署到生产环境建议使用 Qt 自带的qt.conf文件或者直接在程序目录配置好 RPATH而不是依赖全局环境变量。qt.conf的做法是在可执行文件旁边放一个文本文件写入[Paths] Prefix/opt/Qt5.15.2/5.15.2/gcc_64这样程序启动时会自动根据这个 Prefix 找到对应的 Qt 库不污染系统环境。这个技巧对部署特别管用但实际项目里见到有人用的人很少。4. 创建第一个项目并验证环境4.1 在 Qt Creator 里创建 Widgets 项目打开 Qt Creator菜单“文件 - New Project”选择“Qt Widgets Application”填上项目名比如hello_qt。在构建系统一栏如果你用的是 Qt5.15 且没有特别需求选 qmake 比较友好用 Qt6 的新项目则可以直接选 CMake。后续向导会让你选 Kit如果你前面已经注册好直接选对应的 Kit 就行。创建完项目默认会把main.cpp和一个mainwindow.ui给你生成好你点击底部的“构建”按钮看着进度条跑完再点运行。不出意外的话一个带菜单栏的窗口会出现在你的桌面上。这个验证过程不是走个过场。之前我见过一种情况Qt Creator 能正常构建但运行时报 “could not find the Qt platform plugin xcb” —— 这类问题跟 Creator 没关是系统库里缺少 xcb 相关的零散包。出现这种错误就按照前面 2.1 里我列的那串libxcb-*包从头装一遍基本能解决。4.2 不用 IDE命令行动手走一遍除了用 IDE我更推荐你手动跑一遍命令行构建流程这样才能真正理解 Qt 的构建机制。在项目目录里创建CMakeLists.txt或使用.pro文件。以 qmake 的方式举例写一个最小的hello.proQT widgets SOURCES main.cpp TARGET hello_qt然后执行qmake hello.pro make -j$(nproc)如果一切正常同目录下会生成hello_qt可执行文件。运行./hello_qt一个小问题如果你是 X11 桌面环境窗口可能一闪而过控制台也没输出。这不是错误只是程序本身没有阻塞式逻辑。为了确认它有没有跑起来可以直接在 main.cpp 里加一行输出到终端验证但其实没必要你能看到窗口就说明环境正常。如果你在无桌面的服务器上测试运行后终会报错因为找不到 Linuxfb 平台插件这就是我后面要专门说的嵌入式场景问题。在桌面上运行则不需要特别指定平台插件。4.3 验证 Qt 动态库是否匹配命令行构建成功后还可以用 ldd 检查可执行文件到底链接了哪里的 Qt 库ldd ./hello_qt | grep Qt如果你明明装了官网的 Qt却看到输出里出现/usr/lib/x86_64-linux-gnu/libQt5Core.so.5说明它链接的是系统 apt 源里的库不是官网的库。这种错乱会造成版本不匹配运行时会报很难查的错。要强制让程序使用某套库一个是在构建时指定-rpath另一个就是写qt.conf。对小程序来说直接用LD_LIBRARY_PATH排在最前面试一次也能看效果但最终方案还是要做到库路径可移植。5. 常见问题排查与避坑手册5.1 一张表先解决一半问题下面这张表我在每次记笔记时都会想起来整理成速查表分享给大家。适用最常见的桌面 Ubuntu 装 Qt 的报错报错信息典型原因处理方式cannot mix incompatible Qt library (version ex50601) with this library编译时链接的 Qt 版本和运行时加载的 Qt 版本不一致统一 LD_LIBRARY_PATH确认 qmake 和运行库路径一致could not find the Qt platform plugin linuxfb系统没有 plugins/platforms 目录下的 libqlinuxfb.so或没有指定平台插件路径在可执行文件旁设置 qt.conf或安装/拷贝对应插件无桌面时设置QT_QPA_PLATFORMlinuxfbcannot find -lpublic链接器找不到名为 public 的库文件libpublic.so确认库文件路径用-L/path/to/lib指定搜索目录GL/gl.h: No such file or directory缺少 OpenGL 开发库安装libgl1-mesa-dev libglu1-mesa-devQXcbConnection: Could not connect to display程序连接到 X 服务失败常见于无图形界面环境确保 DISPLAY 变量正确用xvfb-run或者 SSH 启用 X11 转发:-1: error: Unknown module(s) in QT: xxx缺少对应 Qt 模块开发包安装对应模块如sudo apt install qtdeclarative5-dev5.2 最糟心的 “cannot mix incompatible Qt library” 是怎么回事这个词我是真正见识过才能体会的。某次我帮朋友查一个项目程序编译一把过运行时立刻报这种“版本不兼容”。这里的version ex50601是指编译时用的 Qt 版本内部表示5.6.1会编码成类似 0x50601 的数值5.15.2则会编码成更大的一个数值。报错的本质是程序在加载一个动态库的时候它头文件里记录的 Qt 版本和运行时暴露的 Qt 版本集合对不上。为什么会这样因为编译时qmake指示的是/opt/Qt5.15.2/.../lib里的库而运行时动态链接库搜索顺序却先找到/usr/lib/x86_64-linux-gnu/libQt5Core.so.5也就是系统自带的库。两边版本不一致Qt 内部的 version marker 拼起来对不上程序就拒绝加载。排查的方向很简单先ldd看动态库指向再看看qmake -v指向最后看LD_LIBRARY_PATH和qt.conf。我最终是把 /opt 的 bin 目录加到了 PATH同时给程序目录写了一版 qt.conf彻底屏蔽了系统库的干扰。5.3 在无桌面的服务器或嵌入式板子上跑 Qtlinuxfb 插件缺了怎么办这个报错在纯命令行服务器、Docker 容器和嵌入式板子上几乎天天见。Qt 的抽象其实早就准备好了它支持 xcb桌面环境、linuxfb直接写 framebuffer、eglfs基于 EGL等多种平台插件。默认QT_QPA_PLATFORMxcb如果你的环境中没有 X serverQt 就会尝试回退到其它插件但此时插件目录里如果没有libqlinuxfb.so就会报 this 错误。解决方式有两层。第一层在环境变量里指定用 linuxfbexport QT_QPA_PLATFORMlinuxfb ./hello_qt但前提是程序编译时启用了linuxfb插件否则依然报错。Qt 默认源码编译时会包含该插件但在某些精简版安装里可能没有。第二层确认插件存在后再指定。可以在 Qt 安装目录里搜索find /opt/Qt5.15.2 -name *linuxfb*如果插件不存在就需要你重新编译 Qt或者在构建 Qt 时通过-plugin-linuxfb选项让它生成。这里还要注意权限问题使用 linuxfb 时程序往往需要能访问/dev/fb0如果权限不足运行会直接 Segmentation fault 或没有反应。排查时可以先用ls -l /dev/fb0看看这个设备节点是否存在并确认当前用户有没有权限。5.4 链接器报 “cannot find -lpublic” 的排查思路这个报错看起来其实和“无法找到对应 Qt 模块”很像但根本原因是你在链接参数里通过-lpublic指定了一个名为public的库。某些第三方项目或自研库会把公共部分汇总成一个叫libpublic.so或libpublic.a的文件实际开发中我见过一些团队这么组织代码。如果你的LIBS -lpublic但链接器没找到说明libpublic.so不在链接器的默认搜索路径下。解决办法是明确指定库路径LIBS -L/path/to/lib -lpublic也可以用INCLUDEPATH来指定头文件目录避免头文件搜索不到。这里最容易被忽略的是如果你用的是 CMake那么应该用target_link_libraries(your_target PUBLIC /path/to/libpublic.so)直接把.so的完整路径传进去这样就不会牵扯到-l搜索顺序的问题。5.5 中文输入法在 Qt Creator 里用不了这个问题不是 Qt 的 bug而是输入法框架和前端的对接问题。在 Ubuntu 桌面环境下常见输入法有 fcitx5 和 ibusQt 程序需要通过对应的输入法插件访问输入法服务。如果你发现 Qt Creator 里能输入英文但不能切换中文优先检查有没有安装输入法前端库。以 fcitx5 为例需要安装sudo apt install fcitx5-frontend-qt5装完重启 Qt Creator输入法就正常了。如果是 ibus检查环境变量GTK_IM_MODULE、QT_IM_MODULE、XMODIFIERS是否配置正确。这个问题的排查方式和普通 GTK / Qt 应用几乎一样所以你在网上搜到的“Ubuntu 中文输入法怎么设置”教程原理是相通的。6. 进阶玩法交叉编译和 Docker 容器里的 Qt6.1 交叉编译给树莓派这类 ARM 板子准备 Qt 环境交叉编译是很多 Linux 下 Qt 应用真正要面对的核心挑战。拿最常见的树莓派举例你在 Ubuntu x86_64 电脑上交叉编译一个 ARM 版本的 Qt 程序需要三样东西交叉编译工具链、目标板的 sysroot、编译好的 Qt for ARM 库。完整流程一般是先在树莓派上装同版本 Ubuntu 系统拷出根目录/的一部分作为 sysroot然后在电脑上下载交叉编译器比如aarch64-linux-gnu-g最后用 Qt 源码配合脚本配置交叉编译参数指定目标平台架构、sysroot 路径和编译选项。这是一套工程量庞大的流程主要难点在于处理 sysroot 的依赖库问题以及 Qt 的 configure 选项能不能和你手上的编译器版本匹配。这里我给你一条务实的建议不是每个项目都需要自己编译 Qt 库。如果你的板子厂商已经提供了 Qt 二进制包或者 SDK直接用它的库来交叉编译你的应用程序就行没必要从源码把整个 Qt 重新编译一遍。只有当你需要修改 Qt 源码或者对平台插件有特殊定制需求时才值得去重新源码编译 Qt。交叉编译时一个常见的坑是“run on target”配置错误。在 Qt Creator 里新增一个 Kit把“Device”配置成一个 SSH 连接到树莓派的设备编译时它能自动把编译产物部署到板子上。但如果你不配置 Device只改编译器为交叉编译器程序虽然在 x86 上能编译但运行前就会直接在板子上缺失库文件。6.2 在 Docker 容器里跑 Qt 程序CI 和二进制部署在持续集成流程里用 Docker 容器编译 Qt 应用是个很常见的需求。在容器里装 Qt 和宿主机上一样但要注意的是你想在容器内显示 GUI 的时候容器默认是没有 X server 的。该怎样处理呢常见做法是把宿主的 X11 socket 挂到容器内docker run -e DISPLAY$DISPLAY \ -v /tmp/.X11-unix:/tmp/.X11-unix \ your_qt_image ./hello_qt这种方案在本地跑没问题布局也非常直观。但它依赖宿主机的 X 服务在 CI 环境里不一定可用。CI 环境里通常用两种方式一种是设置QT_QPA_PLATFORMoffscreen用离屏渲染模式测试程序逻辑另一种是安装 Xvfb 作为假 X server。单独要跑图形测试还会用到 OpenGL 相关的虚拟驱动这时候追根到底又是一堆依赖问题。我在 CI 里最常用的指令其实很简单xvfb-run -a ./hello_qt如果还需要启用 linuxfb 做一些 framebuffer 层面的验证再配合QT_QPA_PLATFORMlinuxfb来运行。平常在本地桌面 Ubuntu 上装 Qt 之后这种容器化的经验虽然用不上但一旦你接入自动化编译和发布流程就是刚需。我个人的实操体会是装 Qt 这个动作本身并不复杂真正花我时间最多的是那些“装完过后的错误处理”和“编译路径的选择”。与其在各个论坛上搜索报错信息不如一开始就把版本、库路径和依赖装齐。如果大家在实际配置过程中还遇到其它没见过的问题也建议先拿ldd和qmake -v这两个命令定位它们能带你少走至少一半的弯路。