1. 装了三四十次Qt之后我想先说说安装方式怎么选先把结论放前面Ubuntu 装 Qt没有任何一种安装方式能通吃所有场景。apt 装省事但版本老官方在线安装器灵活但对网络要求高离线安装包最稳但文件大。我见过太多人一上来就sudo apt install qt5-default装完才发现 Qt Creator 打不开、OpenGL 模块缺失、交叉编译工具链根本不匹配白白浪费一下午。这篇教程我会把我常用的、验证过多次的完整流程拆开讲顺便把那些安装完成后才会暴露的坑提前给你排掉。先说一个很反直觉的事实**Qt 安装本身并不难难的是装完之后的环境一致性。**很多人装完 Qt 能打开但项目一编译就报GL/gl.h: No such file or directory或者运行程序时提示cannot find -lGL这些十有八九不是 Qt 本身的问题而是系统里缺少图形、字体、编译相关的底层依赖库。所以这篇教程的重点不止是把 Qt 装上去而是把 Qt 装到一个能正常开发、能正常编译、能正常跑起来的环境里。这篇内容适合这几类人刚接触 Ubuntu想在 Linux 下做 Qt 开发的新手从 Windows 转到 Ubuntu被 Qt 安装方式搞晕的开发者需要用 Qt 做嵌入式交叉编译却搞不清环境怎么配的人装了 Qt 但运行报各种诡异错误想彻底排查一遍的老手如果你属于其中任何一类这篇教程应该能让你少走不少弯路。2. 系统环境准备Qt 能不能安稳装上七成取决于这一步2.1 先确认 Ubuntu 版本和系统架构很多教程一上来就让你装依赖但我的习惯是先确认系统底子。不同版本的 UbuntuQt 的兼容性和可用的依赖源差别很大。你可以用两行命令快速确认lsb_release -a uname -m我目前的主力环境是 Ubuntu 22.04 LTS搭配 Qt 5.15.2 和 Qt 6.2 LTS 两套版本。如果你用的是 20.04走下面的流程基本没问题如果是 24.04需要注意 Qt 5 的部分组件可能要从源码编译apt 源里的 qt5 相关包已经逐渐减少。uname -m返回x86_64是正常的 64 位系统如果是aarch64比如树莓派、飞腾开发板很多在线安装器都不支持只能走 apt 或者手动交叉编译这个后面第 7 节会单独说。2.2 更新软件源顺手把编译工具链装齐在安装任何东西之前先把 apt 源刷新一遍然后把编译 Qt 项目必需的底层工具链装上sudo apt update sudo apt upgrade -y sudo apt install -y build-essential g make cmakebuild-essential这个包会带上 gcc、g、make 等一堆基础编译工具是你后面用 qmake 或 CMake 编译 Qt 项目的地基。cmake 最好单独确认一下版本Qt 6 对 CMake 版本有硬性要求3.16Ubuntu 22.04 默认的 cmake 是 3.22够用20.04 默认的是 3.16.3刚好卡线。如果你在 20.04 上装 Qt 6建议先把 CMake 升级到 3.21 以上。2.3 OpenGL 和图形相关依赖最容易漏掉的一环这是我要单独拿出来强调的部分。Qt 的 GUI 模块底层依赖 OpenGL 相关的开发库尤其是 Qt 6默认渲染后端就是 OpenGL。很多人装完 Qt 后程序一运行就崩溃报错里带着libGL.so、GL/gl.h之类的关键词基本就是缺了下面这些包sudo apt install -y libgl1-mesa-dev libglu1-mesa-dev freeglut3-dev mesa-common-devlibgl1-mesa-dev提供libGL.so和GL/gl.h是 Qt GUI 模块能否链接成功的关键。如果你打算做 OpenGL 相关的三维渲染功能比如 Qt 的 QOpenGLWidgetlibglu1-mesa-dev和freeglut3-dev也得装上。另外机器上如果是 NVIDIA 显卡建议把显卡驱动也提前搞定否则 Qt 程序在 X11 下可能会退回到软件渲染界面卡顿不说部分硬件加速功能也会失效。不过驱动安装是个大话题这里先不展开只要记住 Qt 程序跑得卡就和驱动、渲染后端有关系就够了。2.4 中文显示与输入法Ubuntu 下 Qt 开发的隐藏痛点如果你要在 Ubuntu 上做中文界面的 Qt 开发或者你本人需要中文输入有两个包必须提前装sudo apt install -y fontconfig libfontconfig1-dev sudo apt install -y fcitx-frontend-qt5 fcitx-frontend-qt6第一个fontconfig负责字体管理缺了它 Qt 界面容易出现字体发虚、中文显示成方块的问题。第二个是输入法前端模块网上搜ubuntu 中文输入法怎么设置能找到一大堆教程但很少有人提起 Qt 程序输入法无法切换的解决方案。Ubuntu 下装 fcitx或者搜狗输入法之后Qt 程序必须依赖fcitx-frontend-qt5这类桥接库才能正常启用输入法。没有它你在 Qt 的文本框里根本无法调用出搜狗输入法只能在终端里打中文再粘过来。注意fcitx-frontend-qt6只在 Ubuntu 22.04 的较新源里才有20.04 如果找不到这个包需要自己编译或者用输入法框架的兼容版本。我在 22.04 上实测下来安装fcitx-frontend-qt5后 Qt 5 程序输入法正常但 Qt 6 程序偶尔还是不行后来装了fcitx5-frontend-qt5才算稳定。这里有个环境变量也值得记住export QT_IM_MODULEfcitx把这个写进/etc/environment或~/.profile可以让 Qt 程序默认走 fcitx 输入法框架。2.5 老生常谈的缺包问题一次性规避除了上面这些还有几个包是 Qt 开发中高频用到的基础库建议顺手装掉省得后面编译某个功能模块时再回来补sudo apt install -y libxkbcommon-x11-dev libxcb-xinerama0 libxcb-xinerama0-dev libxcb-cursor0 sudo apt install -y libdbus-1-dev libx11-xcb-dev libxi-dev libxtst-devlibxcb-cursor0是 Qt 6.5 之后必须的缺了它 Qt 程序直接报xcb-cursor0相关错误。libxtst-dev是做键盘鼠标事件模拟比如热词里提到的 qt 模拟鼠标点击事件时需要的 XTest 扩展库。这些包体积都不大一次装齐能省掉后面很多逐个排查的时间。3. 核心安装流程在线安装还是离线安装我给出明确建议3.1 三种安装方式的对比为什么我推荐离线包安装方式优点缺点适用场景sudo apt install qt5-default命令简单、完全自动化版本旧、组件不全、难以定制临时跑个小 demo官方在线安装器组件可选、版本最新、支持 Qt 6需要注册账号、依赖网络稳定性有官方账号、网络条件好离线安装包版本固定、可离线重装、组件可控安装包体积大1~3GB生产开发主力推荐我的主力推荐是离线安装包。原因很实际Qt 的在线安装器在 Ubuntu 上的体验不如 Windows时不时会卡在登录或者下载组件的环节而且它需要你先注册一个 Qt 账号。离线包则完全绕开这两点下载完解压就能装。Qt 官方提供了所有历史版本的离线安装包放在qt.io/archive里但直接访问下载速度不稳定。国内用户建议直接用清华镜像wget https://mirrors.tuna.tsinghua.edu.cn/qt/official_releases/qt/5.15/5.15.2/qt-opensource-linux-x64-5.15.2.run注意 Qt 5.15.2 是最后一个开源版本提供官方离线二进制包的 LTS 版本之后的 5.15 系列只有源码这也是它被广泛使用的原因之一。如果你需要 Qt 6.x镜像路径类似wget https://mirrors.tuna.tsinghua.edu.cn/qt/official_releases/qt/6.2/6.2.4/qt-opensource-linux-x64-6.2.4.run还有 Qt 6.5.3 LTS 版本路径里的版本号替换即可。这些镜像路径建议收藏以后下载 Qt 离线包基本都用得上。3.2 给安装脚本执行权限然后启动图形化向导下载完成后先给安装文件加执行权限然后运行chmod x qt-opensource-linux-x64-5.15.2.run ./qt-opensource-linux-x64-5.15.2.run这里有个常见的坑如果你当前的 shell 用户不是 root运行时会提示安装目录不可写。我的建议是不要用sudo直接装 Qt因为 root 用户安装的 Qt 目录属主是 root后面你编译项目或者添加编译器套件时会因为权限问题报错还得手动chown很麻烦。正确做法是把 Qt 安装到一个属于你自己的目录比如/home/你的用户名/Qt或者/opt/qt先sudo mkdir /opt/qt sudo chown -R 你的用户名 /opt/qt把目录属主改掉。安装向导界面本身没什么可说的一直 Next 就行到组件选择界面需要留意一下。Qt 5.15.2 的离线包默认自带 Qt Creator 和一些基础模块。如果你硬盘空间充足建议把Sources组件也勾上后面想调试 Qt 内部实现或者排查一些诡异 bug 时有源码可以跳转会舒服得多。等进度条走完安装过程就结束了。装完后 Qt 默认在/home/你的用户名/Qt/5.15.2/gcc_64这个路径下我用gcc_64指代桌面版 Qt 库后面配置构建套件时会用到。3.3 没有图形界面的服务器环境静默安装法有人是在无桌面环境的 Ubuntu Server 上装 Qt这时上面的图形化向导跑不起来。Qt 离线包支持命令行静默安装网上知道这个技巧的人不多./qt-opensource-linux-x64-5.15.2.run --helpinstaller 会列出可用的命令行参数。实际静默安装命令是./qt-opensource-linux-x64-5.15.2.run --install-dir /opt/qt -y --accept-licenses --accept-obligations --default-answer --confirm-command但要注意这种方式装的是默认组件可能不包含你需要的 Qt Charts、Qt WebEngine 等附加模块。服务器环境如果只是用 Qt 做无界面的后端服务或者交叉编译主机的 Qt 库默认组件通常够用但如果要跑 GUI 程序服务器上还得装 X 服务和图形驱动那是另一个话题了。我个人的经验是无桌面环境优先用 apt 安装 Qt 基础库或者干脆在本地桌面环境装好后再把 Qt 目录整个同步到服务器这样能保证组件一致性。3.4 在线安装器和离线包在组件选择上的差别在线安装器qt-unified-linux-x64-x.x.x-online.run和离线包在安装向导上的最大区别是在线安装器可以自由选择任意 Qt 版本、任意组件组合包括 Qt Charts、Qt Data Visualization、Qt WebEngine 这些附加模块而且可以同时装 Qt 5 和 Qt 6 的多套版本。离线包则只能装某一个版本预先打包好的那部分组件。如果你确定自己只用一个 Qt 版本离线包足够了如果你经常需要多版本切换比如公司的旧项目用 Qt 5.12新项目用 Qt 6.5在线安装器反而更方便。不管用哪种方式装完后都需要清楚自己装的 Qt 路径、qmake 路径和编译器路径分别是什么这是第 4 节配置构建套件的基础。4. 构建套件的配置装好了不等于能编译4.1 Qt Creator 里 Kit 的核心作用Qt 安装完成后如果你直接打开 Qt Creator 写代码大概率会发现在构建套件里自动识别出了Desktop Qt 5.15.2 GCC 64bit这个套件。但如果没识别出来或者你装的是多版本 Qt你需要理解 Kit 到底在做什么。一个构建套件Kit本质上是四样东西的组装编译器CompilerC/C 编译器通常是系统自带的 gcc/g调试器Debugger通常是 gdbCMake 或 qmake构建系统的驱动工具Qt 版本具体的 Qt 库路径这四样只要有一个对不上编译就会出问题。比如你系统里既有 gcc 11 又有 clangQt Creator 自动检测时选错了编译器Qt 库是用 gcc ABI 编译的你用 clang 链接就会报一堆莫名其妙的符号错误。4.2 手动添加 Qt 版本的完整操作如果你打开工具菜单下的选项再进入Kits页面发现 Tools 列表里没有 Qt 版本不用慌手动加一遍也就两分钟打开 Qt Creator菜单栏进入 工具 - 选项 - Kits切到Qt Versions标签页点击Add...浏览到你 Qt 安装目录下的gcc_64/bin/qmake比如/home/user/Qt/5.15.2/gcc_64/bin/qmake版本信息会自动解析点击 OK再切到Compilers标签页确认 gcc/g 路径指向/usr/bin/gcc和/usr/bin/g回到Kits标签页如果还没有自动生成就点Add选择编译器和 Qt 版本这里有个容易忽略的细节**CMake 的路径也必须在 Kits 里指定。**在CMake标签页里添加/usr/bin/cmake。默认情况下 Qt Creator 会自动搜索但如果你装了多个版本的 CMake比如通过 pip 或者源码编译的方式自动搜索可能会选到一个版本过旧的建议手动检查一下。4.3 系统里同时装了 Qt 5 和 Qt 6怎么切换默认版本很多人会遇到这种需求Qt 5.15 跑旧项目Qt 6.5 跑新项目。两个版本完全可以共存关键是切换逻辑。Qt 官方提供了qtchooser工具但 apt 装的 qtchooser 默认只认识系统里的 Qt通常是/usr/lib/x86_64-linux-gnu/qt5不认识你手动装的/home/user/Qt/5.15.2。你需要手动配置sudo apt install -y qtchooser创建一个配置文件把自定义 Qt 路径告诉 qtchoosersudo tee /usr/share/qtchooser/myqt515.conf EOF /home/user/Qt/5.15.2/gcc_64/bin /home/user/Qt/5.15.2/gcc_64/lib EOF然后就能通过环境变量随时切换export QT_SELECTmyqt515 qmake --version这个方式在终端里切换 qmake 版本非常方便。不过在 Qt Creator 里多套 Qt 版本靠的是 Kits 管理不需要依赖 qtchooser直接在构建套件里给每个项目选择对应的 Kit 就行。我个人的经验是终端编译用 qtchooserIDE 开发用 Kits两边互不干扰。4.4 环境变量LD_LIBRARY_PATH 到底要不要配网上很多教程会让你把 Qt 库路径写进LD_LIBRARY_PATHexport LD_LIBRARY_PATH/home/user/Qt/5.15.2/gcc_64/lib:$LD_LIBRARY_PATH我的建议是**开发阶段可以配但发布程序时不要依赖这个变量。**原因很简单Qt Creator 在编译运行程序时会自动把 Qt 库路径传给运行环境你不需要手动配。但如果你在终端里直接跑编译出来的可执行文件比如交叉编译的产物拿到目标板上跑就需要配LD_LIBRARY_PATH或者用ldd查依赖库的路径。发布程序时正确做法是把 Qt 运行库复制到程序同目录下或者用linuxdeployqt打包而不是依赖目标机器上的LD_LIBRARY_PATH。这句话值得每一个用 Qt 做 Linux 开发的人记住**开发环境和发布环境的库加载策略是两套逻辑不要混为一谈。**开发时为了方便可以在.bashrc里加export LD_LIBRARY_PATH...但生产环境里这种全局变量往往就是各种诡异运行问题的根源。5. 装完必做的四步验证流程5.1 验证 qmake 和编译器版本对齐装完 Qt 后我做的第一件事不是打开 Qt Creator而是先在终端里验证工具链是否一致qmake --version g --versionqmake --version应该显示类似QMake version 3.1 Using Qt version 5.15.2 in /home/user/Qt/5.15.2/gcc_64/lib的信息。如果提示qmake: command not found说明 qmake 不在 PATH 里需要手动加或者直接使用绝对路径。这里有个小技巧如果你的系统里同时存在/usr/bin/qmakeapt 装的旧版和 Qt 安装目录里的 qmakeqmake --version可能显示的是系统旧版本导致后面编译时出现Qt 版本不匹配的诡异错误。排查方法是用绝对路径调用 Qt 自己的 qmake/home/user/Qt/5.15.2/gcc_64/bin/qmake --version如果两者版本不同你需要确认终端里用的是哪一个或者在 Qt Creator 的 Kit 里显式指定 qmake 路径。5.2 命令行编译一个最小 Qt 程序我推荐的验证方法是绕过 Qt Creator直接在终端里编译一个最小 GUI 程序。这样能快速排除 IDE 配置干扰确认 Qt 库本身能不能正常工作。新建一个文件main.cpp#include QApplication #include QLabel int main(int argc, char *argv[]) { QApplication app(argc, argv); QLabel label(Qt works on Ubuntu!); label.show(); return app.exec(); }然后按顺序执行qmake -project qmake make ./你生成的可执行文件名如果一切顺利屏幕上会弹出一个写着 Qt works on Ubuntu! 的小窗口。这个过程走通说明 Qt 库、编译器、链接器、X11/OpenGL 依赖这些都是正常的。如果在这一步报错基本可以确定是系统依赖问题而不是 Qt Creator 的配置问题。5.3 用 Qt Creator 新建一个带界面的项目命令行验证通过后再打开 Qt Creator 新建一个 Widgets Application选 Qt Widgets Application 模板构建套件选择 Desktop Qt 5.15.2 GCC 64bit直接点运行。Qt Creator 会自动完成编译、构建、运行的完整链路。这个验证的意义在于确认 Qt Creator 的构建套件配置没有问题确保你后续可以正常进行界面设计、信号槽连接这些日常开发操作。5.4 给 Qt Creator 添加桌面快捷方式安装目录下的 Qt Creator 可执行文件路径通常是/home/user/Qt/Tools/QtCreator/bin/qtcreator。默认安装不会自动创建桌面快捷方式每次从终端启动有点烦。手动创建一个qtcreator.desktop文件放到~/.local/share/applications/下[Desktop Entry] NameQt Creator CommentQt IDE Exec/home/user/Qt/Tools/QtCreator/bin/qtcreator Icon/home/user/Qt/Tools/QtCreator/share/icons/hicolor/512x512/apps/QtProject-qtcreator.png Terminalfalse TypeApplication CategoriesDevelopment;IDE;保存后在应用程序菜单里就能找到 Qt Creator 了。注意把路径替换成你自己的实际安装路径。6. Qt 运行时的典型报错与定位思路到了这一步Qt 已经能正常使用了。但开发过程中难免会遇到运行时问题我把高频报错和排查思路整理一下每个都是我实际踩过的坑。6.1 xcb 相关错误Qt 图形界面打不开的元凶错误形态通常是这样qt.qpa.plugin: Could not load the Qt platform plugin xcb in even though it was found.你可能会在网上搜到各种解释但核心原因就两种一是缺少 xcb 运行库二是 Qt 的插件搜索路径不对。先排查运行库sudo apt install -y libxcb-cursor0 libxcb-xinerama0 libxcb-icccm4 libxcb-keysyms1 libxcb-shape0 libxcb-render-util0如果还不行再用ldd查看 xcb 插件依赖的库是否齐全ldd /home/user/Qt/5.15.2/gcc_64/plugins/platforms/libqxcb.so | grep not foundldd会列出所有找不到的动态库看到哪个缺哪个就装哪个。这是排查 Qt 运行时错误最核心的手段比在网上乱搜有效得多。如果ldd没有任何输出说明库都正常那多半是插件搜索路径的问题。Qt 程序会按编译时的路径搜索插件目录如果你把 Qt 安装目录移动过位置或者写死了某个路径就会报这个错。解决方法是在运行程序前设置环境变量export QT_QPA_PLATFORM_PLUGIN_PATH/home/user/Qt/5.15.2/gcc_64/plugins6.2cannot find -lGL链接器找不到 OpenGL 库这个错误信息非常经典/usr/bin/ld: cannot find -lGL collect2: error: ld returned 1 exit status这个-lGL是链接器的参数表示链接名为libGL.so的库。找不到它安装libgl1-mesa-dev即可sudo apt install -y libgl1-mesa-dev装完后可以确认一下库文件是否生成ls -l /usr/lib/x86_64-linux-gnu/libGL.so如果你做的是 Qt 6 开发可能还会遇到找不到libEGL的问题安装libegl1-mesa-dev可以解决。6.3 程序运行时的权限和输入法问题还有两个不报错但表现很诡异的场景。第一个是 Qt 程序启动后在任务栏有图标但窗口不显示这通常和窗口管理器有关检查一下你是否在 Wayland 环境下运行 Qt 5。Qt 5 对 Wayland 的支持不如 X11 成熟建议在 Wayland 桌面环境下强制 Qt 走 XWaylandexport QT_QPA_PLATFORMxcb如果你不想每次都手动敲这个可以把它写进 Qt Creator 的运行环境变量设置里工具 - 选项 - Kits - 环境。第二个是前面提到过的输入法问题。如果你安装了搜狗输入法或者其他基于 fcitx 的输入法但 Qt 程序里怎么都调不出来除了安装fcitx-frontend-qt5之外建议在程序启动前确认环境变量export QT_IM_MODULEfcitx export GTK_IM_MODULEfcitx export XMODIFIERSimfcitx把这三行加入/etc/environment后重启系统输入法问题才能彻底稳定。6.4 常见报错快速对照表错误信息核心原因解决方案Could not load the Qt platform plugin xcbxcb 运行库缺失或插件路径错误ldd查缺库设置QT_QPA_PLATFORM_PLUGIN_PATHcannot find -lGL缺 OpenGL 开发库sudo apt install libgl1-mesa-devGL/gl.h: No such file or directory缺 OpenGL 头文件同上装libgl1-mesa-dev程序能编译但运行直接崩溃Qt 库路径不匹配或多版本冲突检查LD_LIBRARY_PATH用ldd确认加载路径Qt 程序里无法激活中文输入法缺输入法前端模块装fcitx-frontend-qt5设置QT_IM_MODULE程序界面字体发虚/中文方块缺字体管理库sudo apt install fontconfig装中文字体6.5 Docker 容器里跑 Qt 程序的两个额外注意点很多人现在用 Docker 做 Qt 开发环境在容器里跑 GUI 程序时会遇到额外的问题。如果你用 Docker 跑 Qt 程序注意两点需要挂载 X11 的 socket 到容器docker run -e DISPLAY$DISPLAY -v /tmp/.X11-unix:/tmp/.X11-unix宿主机要执行xhost local:允许容器访问 X 服务即便这样容器里依然可能报No protocol specified错误或者出现字体渲染问题。我的建议是开发环境尽量用宿主机直接跑 Qt Creator容器只做编译验证和打包。在容器里做 GUI 开发调试体验确实不太好。7. 交叉编译环境的额外补课7.1 为什么聚焦交叉编译如果你做嵌入式开发比如用 Ubuntu 开发 ARM 板的 Qt 程序环境准备和桌面环境完全不同。热词里反复出现的ubuntu-20.04 安装 qt 交叉编译环境说明很多人卡在这一步。交叉编译不是一个单纯安装 Qt 的过程它需要三样东西交叉编译工具链在 x86 的 Ubuntu 上编译出 ARM 架构可执行文件的编译器和链接器目标系统的 sysroot目标板上的库文件、头文件的镜像目录让编译器知道目标系统有哪些库为 ARM 编译的 Qt 库在目标板上运行的 Qt 运行时库这三个缺一个都不行。很多人所谓Qt 交叉编译环境没配好其实往往是只装了工具链没有为目标平台编译 Qt 库或者 sysroot 里的依赖库不完整。7.2 在 Qt Creator 里配置交叉编译 Kit假设你已经有了编译好的 ARM Qt 库比如/opt/arm-qt以及工具链/usr/bin/arm-linux-gnueabihf-g在 Qt Creator 里配置交叉编译 Kit 的步骤是Compilers标签页里添加arm-linux-gnueabihf-gcc和arm-linux-gnueabihf-g注意 C 和 C 编译器要分别添加Qt Versions标签页里添加/opt/arm-qt/bin/qmakeDebuggers标签页里确保指向对应的 gdb 版本新建 Kit选择上述三样CMake 用系统的版本即可构建时选择这个 Kit生成的可执行文件就是 ARM 架构的配置完成后编译 Qt 程序/opt/arm-qt/bin/qmake your_project.pro make file ./your_appfile命令输出中如果显示ARM架构说明交叉编译成功。7.3 交叉编译最痛的两个坑第一个坑是sysroot 缺库。你在 x86 上编译 Qt 程序时链接器可能会寻找目标系统的某些基础库如果你的 sysroot 不完整编译会报类似cannot find -lts的错误。排查方式是arm-linux-gnueabihf-g -print-sysroot确认 sysroot 里的/usr/lib/arm-linux-gnueabihf目录存在且包含目标库的.so文件。第二个坑是Qt 库本身编译时未开启某些功能。比如你想用 Qt 的 WebEngine 或 Charts 模块但交叉编译 Qt 库时没有指定-opensource -confirm-license -nomake examples -prefix /opt/arm-qt之类的参数编译链接会在最后阶段报找不到模块。如果你拿到的 ARM Qt 库是别人编译的一定要确认模块是否齐全。我个人的做法是交叉编译的 Qt 库尽量自己编译一遍虽然耗时较长ARM 上编译一次 Qt 5.15 大概需要 1~2 小时但模块和参数完全可控。7.4 没有 Qt Creator 时的命令行交叉编译有些工程师不习惯用 Qt Creator主力开发环境是 VSCode 加命令行交叉编译也可以通过 qmake 指定-spec参数完成/opt/arm-qt/bin/qmake -spec /opt/arm-qt/mkspecs/linux-arm-gnueabi-g your_project.pro makeQt 的 mkspecs 目录里预置了多种目标平台的编译规格说明文件你也可以在项目.pro文件里通过QMAKE_CC、QMAKE_CXX变量指定编译器这样每次编译不需要手动传-spec项目自身就携带了交叉编译配置。这个做法在团队协作时很实用不同成员用不同的 Qt 环境也能编译出统一的 ARM 可执行文件。8. 最后几个实际操作中的细节体会装过太多次 Qt踩过太多坑之后我形成了一个习惯**每次装完 Qt先写一个最小 GUI 程序跑通再开始配项目工程。**这个习惯帮我节省了大量排查时间。你看这篇教程前半部分讲环境、讲安装、讲配置本质上都是在为一件事服务——让那个最小 GUI 程序顺利跑起来。关于 Qt 版本选择我个人的建议是如果你是刚接触 Ubuntu 和 Qt直接装 Qt 5.15.2 离线包教程多、坑少、社区资源丰富如果你要开发新项目且没有历史包袱可以考虑 Qt 6.5 LTS但要做好遇到新坑的心理准备——比如 Qt 6 去掉了QTextCodec、QRegExp等旧 API迁移老代码时需要改不少东西。最后再分享一个小技巧。在 Ubuntu 上做 Qt 开发即使你的项目里没有用 CMake我也建议装一个cmake包。很多第三方库比如 OpenCV、PCL在 Ubuntu 下编译时依赖 CMake 构建而 Qt Creator 的项目向导也偏好 CMake 工程格式。装了它你的开发环境对任何 Qt 项目的适配能力都会强很多。而且 Qt 官方对 CMake 的支持力度明显高于 qmake从 Qt 6 开始新功能基本只给 CMake 了。早点习惯 CMake长远看是划算的。 Ubuntu 安装 Qt 完全指南：从环境配置到交叉编译避坑实践
1. 装了三四十次Qt之后我想先说说安装方式怎么选先把结论放前面Ubuntu 装 Qt没有任何一种安装方式能通吃所有场景。apt 装省事但版本老官方在线安装器灵活但对网络要求高离线安装包最稳但文件大。我见过太多人一上来就sudo apt install qt5-default装完才发现 Qt Creator 打不开、OpenGL 模块缺失、交叉编译工具链根本不匹配白白浪费一下午。这篇教程我会把我常用的、验证过多次的完整流程拆开讲顺便把那些安装完成后才会暴露的坑提前给你排掉。先说一个很反直觉的事实**Qt 安装本身并不难难的是装完之后的环境一致性。**很多人装完 Qt 能打开但项目一编译就报GL/gl.h: No such file or directory或者运行程序时提示cannot find -lGL这些十有八九不是 Qt 本身的问题而是系统里缺少图形、字体、编译相关的底层依赖库。所以这篇教程的重点不止是把 Qt 装上去而是把 Qt 装到一个能正常开发、能正常编译、能正常跑起来的环境里。这篇内容适合这几类人刚接触 Ubuntu想在 Linux 下做 Qt 开发的新手从 Windows 转到 Ubuntu被 Qt 安装方式搞晕的开发者需要用 Qt 做嵌入式交叉编译却搞不清环境怎么配的人装了 Qt 但运行报各种诡异错误想彻底排查一遍的老手如果你属于其中任何一类这篇教程应该能让你少走不少弯路。2. 系统环境准备Qt 能不能安稳装上七成取决于这一步2.1 先确认 Ubuntu 版本和系统架构很多教程一上来就让你装依赖但我的习惯是先确认系统底子。不同版本的 UbuntuQt 的兼容性和可用的依赖源差别很大。你可以用两行命令快速确认lsb_release -a uname -m我目前的主力环境是 Ubuntu 22.04 LTS搭配 Qt 5.15.2 和 Qt 6.2 LTS 两套版本。如果你用的是 20.04走下面的流程基本没问题如果是 24.04需要注意 Qt 5 的部分组件可能要从源码编译apt 源里的 qt5 相关包已经逐渐减少。uname -m返回x86_64是正常的 64 位系统如果是aarch64比如树莓派、飞腾开发板很多在线安装器都不支持只能走 apt 或者手动交叉编译这个后面第 7 节会单独说。2.2 更新软件源顺手把编译工具链装齐在安装任何东西之前先把 apt 源刷新一遍然后把编译 Qt 项目必需的底层工具链装上sudo apt update sudo apt upgrade -y sudo apt install -y build-essential g make cmakebuild-essential这个包会带上 gcc、g、make 等一堆基础编译工具是你后面用 qmake 或 CMake 编译 Qt 项目的地基。cmake 最好单独确认一下版本Qt 6 对 CMake 版本有硬性要求3.16Ubuntu 22.04 默认的 cmake 是 3.22够用20.04 默认的是 3.16.3刚好卡线。如果你在 20.04 上装 Qt 6建议先把 CMake 升级到 3.21 以上。2.3 OpenGL 和图形相关依赖最容易漏掉的一环这是我要单独拿出来强调的部分。Qt 的 GUI 模块底层依赖 OpenGL 相关的开发库尤其是 Qt 6默认渲染后端就是 OpenGL。很多人装完 Qt 后程序一运行就崩溃报错里带着libGL.so、GL/gl.h之类的关键词基本就是缺了下面这些包sudo apt install -y libgl1-mesa-dev libglu1-mesa-dev freeglut3-dev mesa-common-devlibgl1-mesa-dev提供libGL.so和GL/gl.h是 Qt GUI 模块能否链接成功的关键。如果你打算做 OpenGL 相关的三维渲染功能比如 Qt 的 QOpenGLWidgetlibglu1-mesa-dev和freeglut3-dev也得装上。另外机器上如果是 NVIDIA 显卡建议把显卡驱动也提前搞定否则 Qt 程序在 X11 下可能会退回到软件渲染界面卡顿不说部分硬件加速功能也会失效。不过驱动安装是个大话题这里先不展开只要记住 Qt 程序跑得卡就和驱动、渲染后端有关系就够了。2.4 中文显示与输入法Ubuntu 下 Qt 开发的隐藏痛点如果你要在 Ubuntu 上做中文界面的 Qt 开发或者你本人需要中文输入有两个包必须提前装sudo apt install -y fontconfig libfontconfig1-dev sudo apt install -y fcitx-frontend-qt5 fcitx-frontend-qt6第一个fontconfig负责字体管理缺了它 Qt 界面容易出现字体发虚、中文显示成方块的问题。第二个是输入法前端模块网上搜ubuntu 中文输入法怎么设置能找到一大堆教程但很少有人提起 Qt 程序输入法无法切换的解决方案。Ubuntu 下装 fcitx或者搜狗输入法之后Qt 程序必须依赖fcitx-frontend-qt5这类桥接库才能正常启用输入法。没有它你在 Qt 的文本框里根本无法调用出搜狗输入法只能在终端里打中文再粘过来。注意fcitx-frontend-qt6只在 Ubuntu 22.04 的较新源里才有20.04 如果找不到这个包需要自己编译或者用输入法框架的兼容版本。我在 22.04 上实测下来安装fcitx-frontend-qt5后 Qt 5 程序输入法正常但 Qt 6 程序偶尔还是不行后来装了fcitx5-frontend-qt5才算稳定。这里有个环境变量也值得记住export QT_IM_MODULEfcitx把这个写进/etc/environment或~/.profile可以让 Qt 程序默认走 fcitx 输入法框架。2.5 老生常谈的缺包问题一次性规避除了上面这些还有几个包是 Qt 开发中高频用到的基础库建议顺手装掉省得后面编译某个功能模块时再回来补sudo apt install -y libxkbcommon-x11-dev libxcb-xinerama0 libxcb-xinerama0-dev libxcb-cursor0 sudo apt install -y libdbus-1-dev libx11-xcb-dev libxi-dev libxtst-devlibxcb-cursor0是 Qt 6.5 之后必须的缺了它 Qt 程序直接报xcb-cursor0相关错误。libxtst-dev是做键盘鼠标事件模拟比如热词里提到的 qt 模拟鼠标点击事件时需要的 XTest 扩展库。这些包体积都不大一次装齐能省掉后面很多逐个排查的时间。3. 核心安装流程在线安装还是离线安装我给出明确建议3.1 三种安装方式的对比为什么我推荐离线包安装方式优点缺点适用场景sudo apt install qt5-default命令简单、完全自动化版本旧、组件不全、难以定制临时跑个小 demo官方在线安装器组件可选、版本最新、支持 Qt 6需要注册账号、依赖网络稳定性有官方账号、网络条件好离线安装包版本固定、可离线重装、组件可控安装包体积大1~3GB生产开发主力推荐我的主力推荐是离线安装包。原因很实际Qt 的在线安装器在 Ubuntu 上的体验不如 Windows时不时会卡在登录或者下载组件的环节而且它需要你先注册一个 Qt 账号。离线包则完全绕开这两点下载完解压就能装。Qt 官方提供了所有历史版本的离线安装包放在qt.io/archive里但直接访问下载速度不稳定。国内用户建议直接用清华镜像wget https://mirrors.tuna.tsinghua.edu.cn/qt/official_releases/qt/5.15/5.15.2/qt-opensource-linux-x64-5.15.2.run注意 Qt 5.15.2 是最后一个开源版本提供官方离线二进制包的 LTS 版本之后的 5.15 系列只有源码这也是它被广泛使用的原因之一。如果你需要 Qt 6.x镜像路径类似wget https://mirrors.tuna.tsinghua.edu.cn/qt/official_releases/qt/6.2/6.2.4/qt-opensource-linux-x64-6.2.4.run还有 Qt 6.5.3 LTS 版本路径里的版本号替换即可。这些镜像路径建议收藏以后下载 Qt 离线包基本都用得上。3.2 给安装脚本执行权限然后启动图形化向导下载完成后先给安装文件加执行权限然后运行chmod x qt-opensource-linux-x64-5.15.2.run ./qt-opensource-linux-x64-5.15.2.run这里有个常见的坑如果你当前的 shell 用户不是 root运行时会提示安装目录不可写。我的建议是不要用sudo直接装 Qt因为 root 用户安装的 Qt 目录属主是 root后面你编译项目或者添加编译器套件时会因为权限问题报错还得手动chown很麻烦。正确做法是把 Qt 安装到一个属于你自己的目录比如/home/你的用户名/Qt或者/opt/qt先sudo mkdir /opt/qt sudo chown -R 你的用户名 /opt/qt把目录属主改掉。安装向导界面本身没什么可说的一直 Next 就行到组件选择界面需要留意一下。Qt 5.15.2 的离线包默认自带 Qt Creator 和一些基础模块。如果你硬盘空间充足建议把Sources组件也勾上后面想调试 Qt 内部实现或者排查一些诡异 bug 时有源码可以跳转会舒服得多。等进度条走完安装过程就结束了。装完后 Qt 默认在/home/你的用户名/Qt/5.15.2/gcc_64这个路径下我用gcc_64指代桌面版 Qt 库后面配置构建套件时会用到。3.3 没有图形界面的服务器环境静默安装法有人是在无桌面环境的 Ubuntu Server 上装 Qt这时上面的图形化向导跑不起来。Qt 离线包支持命令行静默安装网上知道这个技巧的人不多./qt-opensource-linux-x64-5.15.2.run --helpinstaller 会列出可用的命令行参数。实际静默安装命令是./qt-opensource-linux-x64-5.15.2.run --install-dir /opt/qt -y --accept-licenses --accept-obligations --default-answer --confirm-command但要注意这种方式装的是默认组件可能不包含你需要的 Qt Charts、Qt WebEngine 等附加模块。服务器环境如果只是用 Qt 做无界面的后端服务或者交叉编译主机的 Qt 库默认组件通常够用但如果要跑 GUI 程序服务器上还得装 X 服务和图形驱动那是另一个话题了。我个人的经验是无桌面环境优先用 apt 安装 Qt 基础库或者干脆在本地桌面环境装好后再把 Qt 目录整个同步到服务器这样能保证组件一致性。3.4 在线安装器和离线包在组件选择上的差别在线安装器qt-unified-linux-x64-x.x.x-online.run和离线包在安装向导上的最大区别是在线安装器可以自由选择任意 Qt 版本、任意组件组合包括 Qt Charts、Qt Data Visualization、Qt WebEngine 这些附加模块而且可以同时装 Qt 5 和 Qt 6 的多套版本。离线包则只能装某一个版本预先打包好的那部分组件。如果你确定自己只用一个 Qt 版本离线包足够了如果你经常需要多版本切换比如公司的旧项目用 Qt 5.12新项目用 Qt 6.5在线安装器反而更方便。不管用哪种方式装完后都需要清楚自己装的 Qt 路径、qmake 路径和编译器路径分别是什么这是第 4 节配置构建套件的基础。4. 构建套件的配置装好了不等于能编译4.1 Qt Creator 里 Kit 的核心作用Qt 安装完成后如果你直接打开 Qt Creator 写代码大概率会发现在构建套件里自动识别出了Desktop Qt 5.15.2 GCC 64bit这个套件。但如果没识别出来或者你装的是多版本 Qt你需要理解 Kit 到底在做什么。一个构建套件Kit本质上是四样东西的组装编译器CompilerC/C 编译器通常是系统自带的 gcc/g调试器Debugger通常是 gdbCMake 或 qmake构建系统的驱动工具Qt 版本具体的 Qt 库路径这四样只要有一个对不上编译就会出问题。比如你系统里既有 gcc 11 又有 clangQt Creator 自动检测时选错了编译器Qt 库是用 gcc ABI 编译的你用 clang 链接就会报一堆莫名其妙的符号错误。4.2 手动添加 Qt 版本的完整操作如果你打开工具菜单下的选项再进入Kits页面发现 Tools 列表里没有 Qt 版本不用慌手动加一遍也就两分钟打开 Qt Creator菜单栏进入 工具 - 选项 - Kits切到Qt Versions标签页点击Add...浏览到你 Qt 安装目录下的gcc_64/bin/qmake比如/home/user/Qt/5.15.2/gcc_64/bin/qmake版本信息会自动解析点击 OK再切到Compilers标签页确认 gcc/g 路径指向/usr/bin/gcc和/usr/bin/g回到Kits标签页如果还没有自动生成就点Add选择编译器和 Qt 版本这里有个容易忽略的细节**CMake 的路径也必须在 Kits 里指定。**在CMake标签页里添加/usr/bin/cmake。默认情况下 Qt Creator 会自动搜索但如果你装了多个版本的 CMake比如通过 pip 或者源码编译的方式自动搜索可能会选到一个版本过旧的建议手动检查一下。4.3 系统里同时装了 Qt 5 和 Qt 6怎么切换默认版本很多人会遇到这种需求Qt 5.15 跑旧项目Qt 6.5 跑新项目。两个版本完全可以共存关键是切换逻辑。Qt 官方提供了qtchooser工具但 apt 装的 qtchooser 默认只认识系统里的 Qt通常是/usr/lib/x86_64-linux-gnu/qt5不认识你手动装的/home/user/Qt/5.15.2。你需要手动配置sudo apt install -y qtchooser创建一个配置文件把自定义 Qt 路径告诉 qtchoosersudo tee /usr/share/qtchooser/myqt515.conf EOF /home/user/Qt/5.15.2/gcc_64/bin /home/user/Qt/5.15.2/gcc_64/lib EOF然后就能通过环境变量随时切换export QT_SELECTmyqt515 qmake --version这个方式在终端里切换 qmake 版本非常方便。不过在 Qt Creator 里多套 Qt 版本靠的是 Kits 管理不需要依赖 qtchooser直接在构建套件里给每个项目选择对应的 Kit 就行。我个人的经验是终端编译用 qtchooserIDE 开发用 Kits两边互不干扰。4.4 环境变量LD_LIBRARY_PATH 到底要不要配网上很多教程会让你把 Qt 库路径写进LD_LIBRARY_PATHexport LD_LIBRARY_PATH/home/user/Qt/5.15.2/gcc_64/lib:$LD_LIBRARY_PATH我的建议是**开发阶段可以配但发布程序时不要依赖这个变量。**原因很简单Qt Creator 在编译运行程序时会自动把 Qt 库路径传给运行环境你不需要手动配。但如果你在终端里直接跑编译出来的可执行文件比如交叉编译的产物拿到目标板上跑就需要配LD_LIBRARY_PATH或者用ldd查依赖库的路径。发布程序时正确做法是把 Qt 运行库复制到程序同目录下或者用linuxdeployqt打包而不是依赖目标机器上的LD_LIBRARY_PATH。这句话值得每一个用 Qt 做 Linux 开发的人记住**开发环境和发布环境的库加载策略是两套逻辑不要混为一谈。**开发时为了方便可以在.bashrc里加export LD_LIBRARY_PATH...但生产环境里这种全局变量往往就是各种诡异运行问题的根源。5. 装完必做的四步验证流程5.1 验证 qmake 和编译器版本对齐装完 Qt 后我做的第一件事不是打开 Qt Creator而是先在终端里验证工具链是否一致qmake --version g --versionqmake --version应该显示类似QMake version 3.1 Using Qt version 5.15.2 in /home/user/Qt/5.15.2/gcc_64/lib的信息。如果提示qmake: command not found说明 qmake 不在 PATH 里需要手动加或者直接使用绝对路径。这里有个小技巧如果你的系统里同时存在/usr/bin/qmakeapt 装的旧版和 Qt 安装目录里的 qmakeqmake --version可能显示的是系统旧版本导致后面编译时出现Qt 版本不匹配的诡异错误。排查方法是用绝对路径调用 Qt 自己的 qmake/home/user/Qt/5.15.2/gcc_64/bin/qmake --version如果两者版本不同你需要确认终端里用的是哪一个或者在 Qt Creator 的 Kit 里显式指定 qmake 路径。5.2 命令行编译一个最小 Qt 程序我推荐的验证方法是绕过 Qt Creator直接在终端里编译一个最小 GUI 程序。这样能快速排除 IDE 配置干扰确认 Qt 库本身能不能正常工作。新建一个文件main.cpp#include QApplication #include QLabel int main(int argc, char *argv[]) { QApplication app(argc, argv); QLabel label(Qt works on Ubuntu!); label.show(); return app.exec(); }然后按顺序执行qmake -project qmake make ./你生成的可执行文件名如果一切顺利屏幕上会弹出一个写着 Qt works on Ubuntu! 的小窗口。这个过程走通说明 Qt 库、编译器、链接器、X11/OpenGL 依赖这些都是正常的。如果在这一步报错基本可以确定是系统依赖问题而不是 Qt Creator 的配置问题。5.3 用 Qt Creator 新建一个带界面的项目命令行验证通过后再打开 Qt Creator 新建一个 Widgets Application选 Qt Widgets Application 模板构建套件选择 Desktop Qt 5.15.2 GCC 64bit直接点运行。Qt Creator 会自动完成编译、构建、运行的完整链路。这个验证的意义在于确认 Qt Creator 的构建套件配置没有问题确保你后续可以正常进行界面设计、信号槽连接这些日常开发操作。5.4 给 Qt Creator 添加桌面快捷方式安装目录下的 Qt Creator 可执行文件路径通常是/home/user/Qt/Tools/QtCreator/bin/qtcreator。默认安装不会自动创建桌面快捷方式每次从终端启动有点烦。手动创建一个qtcreator.desktop文件放到~/.local/share/applications/下[Desktop Entry] NameQt Creator CommentQt IDE Exec/home/user/Qt/Tools/QtCreator/bin/qtcreator Icon/home/user/Qt/Tools/QtCreator/share/icons/hicolor/512x512/apps/QtProject-qtcreator.png Terminalfalse TypeApplication CategoriesDevelopment;IDE;保存后在应用程序菜单里就能找到 Qt Creator 了。注意把路径替换成你自己的实际安装路径。6. Qt 运行时的典型报错与定位思路到了这一步Qt 已经能正常使用了。但开发过程中难免会遇到运行时问题我把高频报错和排查思路整理一下每个都是我实际踩过的坑。6.1 xcb 相关错误Qt 图形界面打不开的元凶错误形态通常是这样qt.qpa.plugin: Could not load the Qt platform plugin xcb in even though it was found.你可能会在网上搜到各种解释但核心原因就两种一是缺少 xcb 运行库二是 Qt 的插件搜索路径不对。先排查运行库sudo apt install -y libxcb-cursor0 libxcb-xinerama0 libxcb-icccm4 libxcb-keysyms1 libxcb-shape0 libxcb-render-util0如果还不行再用ldd查看 xcb 插件依赖的库是否齐全ldd /home/user/Qt/5.15.2/gcc_64/plugins/platforms/libqxcb.so | grep not foundldd会列出所有找不到的动态库看到哪个缺哪个就装哪个。这是排查 Qt 运行时错误最核心的手段比在网上乱搜有效得多。如果ldd没有任何输出说明库都正常那多半是插件搜索路径的问题。Qt 程序会按编译时的路径搜索插件目录如果你把 Qt 安装目录移动过位置或者写死了某个路径就会报这个错。解决方法是在运行程序前设置环境变量export QT_QPA_PLATFORM_PLUGIN_PATH/home/user/Qt/5.15.2/gcc_64/plugins6.2cannot find -lGL链接器找不到 OpenGL 库这个错误信息非常经典/usr/bin/ld: cannot find -lGL collect2: error: ld returned 1 exit status这个-lGL是链接器的参数表示链接名为libGL.so的库。找不到它安装libgl1-mesa-dev即可sudo apt install -y libgl1-mesa-dev装完后可以确认一下库文件是否生成ls -l /usr/lib/x86_64-linux-gnu/libGL.so如果你做的是 Qt 6 开发可能还会遇到找不到libEGL的问题安装libegl1-mesa-dev可以解决。6.3 程序运行时的权限和输入法问题还有两个不报错但表现很诡异的场景。第一个是 Qt 程序启动后在任务栏有图标但窗口不显示这通常和窗口管理器有关检查一下你是否在 Wayland 环境下运行 Qt 5。Qt 5 对 Wayland 的支持不如 X11 成熟建议在 Wayland 桌面环境下强制 Qt 走 XWaylandexport QT_QPA_PLATFORMxcb如果你不想每次都手动敲这个可以把它写进 Qt Creator 的运行环境变量设置里工具 - 选项 - Kits - 环境。第二个是前面提到过的输入法问题。如果你安装了搜狗输入法或者其他基于 fcitx 的输入法但 Qt 程序里怎么都调不出来除了安装fcitx-frontend-qt5之外建议在程序启动前确认环境变量export QT_IM_MODULEfcitx export GTK_IM_MODULEfcitx export XMODIFIERSimfcitx把这三行加入/etc/environment后重启系统输入法问题才能彻底稳定。6.4 常见报错快速对照表错误信息核心原因解决方案Could not load the Qt platform plugin xcbxcb 运行库缺失或插件路径错误ldd查缺库设置QT_QPA_PLATFORM_PLUGIN_PATHcannot find -lGL缺 OpenGL 开发库sudo apt install libgl1-mesa-devGL/gl.h: No such file or directory缺 OpenGL 头文件同上装libgl1-mesa-dev程序能编译但运行直接崩溃Qt 库路径不匹配或多版本冲突检查LD_LIBRARY_PATH用ldd确认加载路径Qt 程序里无法激活中文输入法缺输入法前端模块装fcitx-frontend-qt5设置QT_IM_MODULE程序界面字体发虚/中文方块缺字体管理库sudo apt install fontconfig装中文字体6.5 Docker 容器里跑 Qt 程序的两个额外注意点很多人现在用 Docker 做 Qt 开发环境在容器里跑 GUI 程序时会遇到额外的问题。如果你用 Docker 跑 Qt 程序注意两点需要挂载 X11 的 socket 到容器docker run -e DISPLAY$DISPLAY -v /tmp/.X11-unix:/tmp/.X11-unix宿主机要执行xhost local:允许容器访问 X 服务即便这样容器里依然可能报No protocol specified错误或者出现字体渲染问题。我的建议是开发环境尽量用宿主机直接跑 Qt Creator容器只做编译验证和打包。在容器里做 GUI 开发调试体验确实不太好。7. 交叉编译环境的额外补课7.1 为什么聚焦交叉编译如果你做嵌入式开发比如用 Ubuntu 开发 ARM 板的 Qt 程序环境准备和桌面环境完全不同。热词里反复出现的ubuntu-20.04 安装 qt 交叉编译环境说明很多人卡在这一步。交叉编译不是一个单纯安装 Qt 的过程它需要三样东西交叉编译工具链在 x86 的 Ubuntu 上编译出 ARM 架构可执行文件的编译器和链接器目标系统的 sysroot目标板上的库文件、头文件的镜像目录让编译器知道目标系统有哪些库为 ARM 编译的 Qt 库在目标板上运行的 Qt 运行时库这三个缺一个都不行。很多人所谓Qt 交叉编译环境没配好其实往往是只装了工具链没有为目标平台编译 Qt 库或者 sysroot 里的依赖库不完整。7.2 在 Qt Creator 里配置交叉编译 Kit假设你已经有了编译好的 ARM Qt 库比如/opt/arm-qt以及工具链/usr/bin/arm-linux-gnueabihf-g在 Qt Creator 里配置交叉编译 Kit 的步骤是Compilers标签页里添加arm-linux-gnueabihf-gcc和arm-linux-gnueabihf-g注意 C 和 C 编译器要分别添加Qt Versions标签页里添加/opt/arm-qt/bin/qmakeDebuggers标签页里确保指向对应的 gdb 版本新建 Kit选择上述三样CMake 用系统的版本即可构建时选择这个 Kit生成的可执行文件就是 ARM 架构的配置完成后编译 Qt 程序/opt/arm-qt/bin/qmake your_project.pro make file ./your_appfile命令输出中如果显示ARM架构说明交叉编译成功。7.3 交叉编译最痛的两个坑第一个坑是sysroot 缺库。你在 x86 上编译 Qt 程序时链接器可能会寻找目标系统的某些基础库如果你的 sysroot 不完整编译会报类似cannot find -lts的错误。排查方式是arm-linux-gnueabihf-g -print-sysroot确认 sysroot 里的/usr/lib/arm-linux-gnueabihf目录存在且包含目标库的.so文件。第二个坑是Qt 库本身编译时未开启某些功能。比如你想用 Qt 的 WebEngine 或 Charts 模块但交叉编译 Qt 库时没有指定-opensource -confirm-license -nomake examples -prefix /opt/arm-qt之类的参数编译链接会在最后阶段报找不到模块。如果你拿到的 ARM Qt 库是别人编译的一定要确认模块是否齐全。我个人的做法是交叉编译的 Qt 库尽量自己编译一遍虽然耗时较长ARM 上编译一次 Qt 5.15 大概需要 1~2 小时但模块和参数完全可控。7.4 没有 Qt Creator 时的命令行交叉编译有些工程师不习惯用 Qt Creator主力开发环境是 VSCode 加命令行交叉编译也可以通过 qmake 指定-spec参数完成/opt/arm-qt/bin/qmake -spec /opt/arm-qt/mkspecs/linux-arm-gnueabi-g your_project.pro makeQt 的 mkspecs 目录里预置了多种目标平台的编译规格说明文件你也可以在项目.pro文件里通过QMAKE_CC、QMAKE_CXX变量指定编译器这样每次编译不需要手动传-spec项目自身就携带了交叉编译配置。这个做法在团队协作时很实用不同成员用不同的 Qt 环境也能编译出统一的 ARM 可执行文件。8. 最后几个实际操作中的细节体会装过太多次 Qt踩过太多坑之后我形成了一个习惯**每次装完 Qt先写一个最小 GUI 程序跑通再开始配项目工程。**这个习惯帮我节省了大量排查时间。你看这篇教程前半部分讲环境、讲安装、讲配置本质上都是在为一件事服务——让那个最小 GUI 程序顺利跑起来。关于 Qt 版本选择我个人的建议是如果你是刚接触 Ubuntu 和 Qt直接装 Qt 5.15.2 离线包教程多、坑少、社区资源丰富如果你要开发新项目且没有历史包袱可以考虑 Qt 6.5 LTS但要做好遇到新坑的心理准备——比如 Qt 6 去掉了QTextCodec、QRegExp等旧 API迁移老代码时需要改不少东西。最后再分享一个小技巧。在 Ubuntu 上做 Qt 开发即使你的项目里没有用 CMake我也建议装一个cmake包。很多第三方库比如 OpenCV、PCL在 Ubuntu 下编译时依赖 CMake 构建而 Qt Creator 的项目向导也偏好 CMake 工程格式。装了它你的开发环境对任何 Qt 项目的适配能力都会强很多。而且 Qt 官方对 CMake 的支持力度明显高于 qmake从 Qt 6 开始新功能基本只给 CMake 了。早点习惯 CMake长远看是划算的。