1. 为什么还是5.9.9写在安装之前的大实话先说结论Qt 5.9.9不是我随便挑的版本它是Qt 5.9 LTS系列的最后一个补丁版本发布于2019年支持周期很长直到2020年底官方才结束对这个分支的维护。很多工业生产项目、高校课程教材、嵌入式Linux开发板厂商提供的SDK到现在还在用它。你要是去GitHub上翻老一点的开源项目会发现很多代码里写的还是find_package(Qt5 5.9 REQUIRED)这行CMake指令说明项目的基线就是5.9。在Linux上装Qt和Windows上是完全两码事。Windows下你只需要挂个镜像、双击exe、一路Next最多处理一下杀毒软件误报。但Linux下牵扯到用户权限、动态库依赖、OpenGL支持、编译器版本匹配、qmake路径、环境变量一整套东西任何一个环节出问题都会导致装的Qt打不开、编出来的程序跑不起来或者干脆安装器都没法启动。这篇文章我打算用一个完整的实操流程把Qt 5.9.9在Linux下的安装、配置、验证、排错全部过一遍。我会用Ubuntu 18.04/20.04作为演示环境其他基于Debian的发行版Deepin、Linux Mint、UOS这些国产系统基本都是操作基本一致RPM系的话需要把apt换成yum/dnf核心思路一样。不管你是刚接触Qt的学生还是公司项目要搭Linux开发环境这篇文章都能给你省下至少一个晚上去踩坑的时间。2. 安装前的准备工作搞清楚三件事再动手2.1 系统环境的确认别嫌啰嗦在敲任何安装命令之前先确认三件事CPU架构、操作系统版本、显卡驱动状态。Qt 5.9.9官方提供了x86_64和arm64两种Linux安装包你要是拿一台ARM处理器的机器比如树莓派或者部分国产飞腾CPU去装x86_64的包装完100%跑不起来这一个错误就够你排查半天。用下面的命令确认架构和系统版本uname -m cat /etc/os-release lsb_release -a第一行输出x86_64说明你接下来下载64位Intel架构安装包如果输出aarch64就去Qt官方下载qt-opensource-linux-arm64-5.9.9.run。第二行和第三行用来确认系统版本这个影响的是你后续需要装哪些系统依赖包。2.2 编译器和新手最容易忽略的OpenGL依赖Qt 5.9.9完整安装包自带的是gcc/g对应的Qt库但一个完整的Linux桌面Qt开发环境你还需要在系统层面装好编译工具链和OpenGL开发库。这里说一下为什么Qt的QWidget界面默认走的是OpenGL渲染路径严格说是通过libGL来做窗口合成如果系统里没有libGL.so和对应的开发头文件你之后用Qt Creator打开一个带UI的工程很可能碰到“无法创建QOpenGLContext”的报错严重点连Qt自带的示例程序都会启动崩溃。需要安装的依赖包Ubuntu下我用一条命令都解决sudo apt update sudo apt install build-essential libgl1-mesa-dev libfontconfig1-dev libdbus-1-dev libfreetype6-dev libx11-dev libxext-dev libxfixes-dev libxi-dev libxrender-dev libxcb1-dev libx11-xcb-dev libxcb-glx0-dev这里的逻辑我拆一下build-essential提供gcc/g和makelibgl1-mesa-dev是Mesa的OpenGL开发库后面那些libx开头的包是Qt的xcb平台插件在运行时依赖的X11库。不装全的话后面编译一个最简单的Qt程序链接阶段会报一堆undefined reference而且错误信息非常误导人你根本想不到是少系统包。2.3 下载安装包的渠道与校验一句话说完Qt官方在5.9时代还提供独立的离线安装包.run格式下载地址是download.qt.io/archive/qt/5.9/5.9.9/文件名是qt-opensource-linux-x64-5.9.9.run。官方主站在国内访问速度通常不太行你有三个选择用国内镜像源清华TUNA、中科大USTC都同步了Qt archive、用代理下载、或者用下载工具分段续传。讲一句题外话如果你是项目需要安装包给团队复用我推荐你下载完以后顺手放到内网共享盘上Linux的Qt安装包同时期版本就几百MB到1GB左右放内网大家装起来快很多。下载完以后务必看下文件大小并对一下哈希值。Qt官网每个文件旁边都标注了MD5Linux下用md5sum命令核对md5sum qt-opensource-linux-x64-5.9.9.run3. 安装流程实操从权限到磁盘空间一网打尽3.1 赋予执行权限与静默安装的两种打开方式下载下来的.run文件默认没有执行权限安装之前你要么chmod x要么直接扔给sh去执行。这里有一个我很在意的细节不要用sudo去跑图形安装界面。原因很简单——安装脚本用root权限运行Qt Creator第一次启动时默认会把配置目录写到$HOME下而root和普通用户的$HOME不是同一个路径装完后你用自己的账号打开Qt Creator会发现它一脸茫然找不到安装好的Kit还要重新手动配置很麻烦。两种安装方式看你服务器上有无图形界面来选有桌面环境的直接图形化安装./qt-opensource-linux-x64-5.9.9.run没有图形界面或者想偷懒的用静默安装模式./qt-opensource-linux-x64-5.9.9.run --script qt-installer-script.qs --platform minimal静默模式需要一个Qt安装器脚本.qs文件官方文档里有模板作用是模拟你在图形安装界面上点击“下一步”、勾选组件、同意协议的全部动作。我建议第一次装的读者先走图形界面流程直观能看清每个组件是什么。用图形界面的人启动后跟着向导走即可。3.2 组件的勾选策略什么该装什么千万别碰安装向导走到“Select Components”这一步很多人会犯选择困难症。我的建议是记住一个原则只选你用得上的别追求大而全。Qt 5.9.9的组件树里Qt 5.9.9这一大项下面有Desktop gcc 64-bit这个是必选的对应x86_64桌面开发套件。旁边还有Android ARM64-v8a、Android x86这类移动端套件你不是做手机App开发的千万别勾勾了以后装到一半容易因为Android SDK缺失而中断而且极其占空间。常见需要勾选的组件包括Qt Charts、Qt Data Visualization、Qt Network Auth、Qt WebEngine、Qt Multimedia、Qt Serial Port这些官方附加模块。这里就有一个关键点了——5.9.9默认组件列表里没有一个叫“Qt Serial Port”的独立安装项很多人项目里用了QtSerialPort装完后编译时疯狂报错unknown module(s) in qt: serialport这个问题我放在后面第5章专门讲这里先不展开。我的推荐组合是如果内存8GB以下、磁盘吃紧只勾Desktop gcc 64-bit和Qt Charts其他用到再补。如果按部就班做桌面开发Desktop gcc 64-bit加Qt Charts加Qt Multimedia加Qt Serial Port如果有的话。如果还要做嵌入式交叉编译在Tools下勾选对应版本的Qt Creator以及交叉编译工具链组件。Qt Creator编辑器本身在Tools这一项里默认是在安装路径/opt/Qt/Tools/QtCreator还是在~/Qt/Tools/QtCreator取决于你选的安装目录。这里提醒一下安装目录的选择千万别装在带空格的路径下比如~/My Qt这种后面CMake和qmake解析路径时百分百出幺蛾子。请直接默认/home/你的用户名/Qt5.9.9或者改成一个不带空格的目录。3.3 磁盘空间与依赖库检查安装前确认剩余磁盘空间5.9.9完整装完大概要5-6GB只装Desktop gcc 64-bit加Qt Creator的话2GB左右就够。命令行下快速检查df -h还有一点容易被忽略Qt安装器本身依赖libxcb-xinerama0这个库有些精简版Linux发行版没装安装器一启动就报错xcb missing直接闪退。解决办法就是提前装sudo apt install libxcb-xinerama0上面命令我用的是与系统包管理器一致的名称如果你用的是RPM系对应包名可能叫libxcb-xinerama0的RPM变体或者xcb-util-xinerama搜索一下你就清楚。3.4 图形安装完成之后一定要做的“二次体检”所有组件走完、进度条拉满以后先别急着打开Qt Creator。在终端里做三件事确认安装是完整的。第一确认qmake存在并能打印版本~/Qt5.9.9/5.9.9/gcc_64/bin/qmake -v正常输出会是一段类似QMake version 3.1 Using Qt version 5.9.9 in /home/xxx/Qt5.9.9/5.9.9/gcc_64/lib的信息。如果你的输出提示找不到libQt5Core.so.5那多半是动态库搜索路径没配好这个问题在“环境变量配置”部分马上处理。第二验证Qt Creator版本确认启动正常~/Qt5.9.9/Tools/QtCreator/bin/qtcreator --version第三检查库里关键的Qt模块文件是否在预期位置ls ~/Qt5.9.9/5.9.9/gcc_64/lib | grep -E libQt5(Widgets|Gui|Core|SerialPort)正常应该能看到libQt5Core.so.5、libQt5Core.so.5.9.9、libQt5Widgets.so.5、libQt5SerialPort.so.5这些软链接和实体文件。如果你就是来装SerialPort的却发现没这个文件直接跳去读第5章。4. 环境变量与编译器配置决定Qt能否顺利开发的“隐形开关”4.1 PATH、LD_LIBRARY_PATH、QT_QPA_PLATFORM三个变量的作用安装完Qt不等于马上能用Linux下你需要手动告诉系统“Qt在哪里”。这主要靠三个环境变量PATH让终端能找到qmake、uic、moc这些Qt自带的命令行工具。LD_LIBRARY_PATH让程序运行时能找到libQt5Core.so这些动态库。你不设这个变量编译出的程序双击或命令行启动时会报error while loading shared libraries: libQt5Core.so.5: cannot open shared object file: No such file or directory。QT_QPA_PLATFORM指定Qt程序的窗口渲染后端默认是xcb。在纯命令行服务器环境没有X11/Wayland下你可以临时设成offscreen来无头运行Qt程序。打开你的用户配置文件vim ~/.bashrc在末尾添加export QTDIR/home/你的用户名/Qt5.9.9/5.9.9/gcc_64 export PATH$QTDIR/bin:$PATH export LD_LIBRARY_PATH$QTDIR/lib:$LD_LIBRARY_PATH export QT_PLUGIN_PATH$QTDIR/plugins export QT_QPA_PLATFORMxcb然后让配置立即生效source ~/.bashrc这里我解释一下QT_PLUGIN_PATH的作用Qt的很多功能是靠插件实现的例如不同平台的窗口系统插件、图片格式插件JPEG/GIF、字体引擎插件。插件目录不设好你跑Qt程序时经常看到Could not find the Qt platform plugin xcb的报错非常经典千万别漏。也可以考虑把环境变量写进/etc/profile.d/qt.sh里让全系统生效但个人开发机建议只配置到~/.bashrc避免污染全局环境。4.2 Qt Creator里配置Kits三步定位你的编译器打开Qt Creator以后主界面菜单栏进入Tools工具 -Options选项 -Kits套件。这是Qt Creator核心的配置面板分三栏Qt Versions、Compilers、Kits。Qt Versions这一栏点Add按钮浏览到~/Qt5.9.9/5.9.9/gcc_64/bin/qmake选完以后检测到版本号5.9.9说明ok。如果显示的版本是invalid看一下是不是qmake路径错了或者Qt库本身有缺失。Compilers这一栏Qt Creator可能已经自动检测到系统的gcc/g了。如果没检测到手动添加C编译器指向/usr/bin/gccC编译器指向/usr/bin/g。Kits这一栏点Add创建一个新套件名称随意比如填Qt 5.9.9 GCC在Qt version下拉框选择刚才添加的5.9.9在Compiler下拉框选择对应gcc在CMake Tool下拉框选系统CMake。资源类型页签选Desktop如果版本号显示“default”也没事说明默认配置生效。配好Kits以后任何一个新项目编译时Qt Creator都会优先用你这个Kit。只要编译器名称选对gcc_64对应的Arm交叉编译也在这里另一种选法先不管你的第一个“Hello World”就够跑了。4.3 编译并运行第一个Qt程序验证安装是否彻底成功环境变量和Qt Creator都配好以后下面用一个控制台工程验证安装是否彻底成功。写个最简单的例子新建一个hello.pro工程文件和一个main.cpp文件或者直接在Qt Creator里按“New Project” - “Qt Widgets Application”#include QApplication #include QLabel int main(int argc, char *argv[]) { QApplication a(argc, argv); QLabel label(Hello, Qt 5.9.9 on Linux!); label.resize(320, 120); label.show(); return a.exec(); }命令行编译的方式qmake make ./hello如果你在无桌面的SSH环境上面第4行的label.show()那一步会失败需要用QT_QPA_PLATFORMoffscreen ./hello去跑打印一堆信息但不崩溃说明程序逻辑没问题。如果一切正常会弹出一个窗口显示文字安装工作到此结束。如果你是第一次从头到尾走通恭喜你已经跨过了Qt Linux开发最坑的一道门槛。很多人的进度就卡在这“装好了但跑不起来”的状态折腾几天后灰溜溜换回Windows其实核心就是环境变量和依赖库这两件事。5. 高频问题排查比安装本身更值钱的实战清单5.1unknown module(s) in qt: serialport这个报错的真正原因与两种解法这个报错几乎可以排进Qt 5.x系列Linux用户最常遇到的错误前三名。原因并不神秘Qt官方从5.9开始把SerialPort模块从默认安装组件里移除了你需要单独下载并编译。打开Qt Creator建一个用到QtSerialPort的工程qmake在解析.pro文件时发现你写了QT serialport但从安装目录里找不到对应模块于是直接报Project ERROR: Unknown module(s) in QT: serialport整个工程直接无法生成Makefile。解法一下载对应版本的qt-serialport-everywhere-src-5.9.9.tar.xz源码包进入到源码目录手动编译安装wget https://download.qt.io/archive/qt/5.9/5.9.9/submodules/qtserialport-everywhere-src-5.9.9.tar.xz tar xvf qtserialport-everywhere-src-5.9.9.tar.xz cd qtserialport-everywhere-src-5.9.9 ~/Qt5.9.9/5.9.9/gcc_64/bin/qmake make -j$(nproc) sudo make install这里的make install默认会把编译好的libQt5SerialPort.so*装到~/Qt5.9.9/5.9.9/gcc_64/lib下头文件装到include/QtSerialPort目录之后再编译你的工程就正常了。注意一定要让qmake路径指向你用的那个Qt版本否则可能装到了系统的/usr/lib里结果Qt Creator依然找不到。解法二用Qt安装器重新运行一次图形界面看能不能找到“Serial Port”相关模块选上。但我前面说了5.9.9的安装器组件列表里通常并没有独立的SerialPort项所以这个方法要看运气不推荐作为首选。另外提醒一句如果你后续是从5.9.9升级到5.15.2那就直接不需要手动折腾这个模块了从5.12开始SerialPort回到了默认组件内部。5.2 安装器启动闪退“xcb missing”和“libGL.so.1缺失”你双击qt-opensource-linux-x64-5.9.9.run结果大白话什么东西都没弹出来终端直接消失。这种情况在精简版Ubuntu Server、Deepin、CentOS Stream等系统上极其常见。用命令行方式启动就能看到具体报错./qt-opensource-linux-x64-5.9.9.run --verbose常见的两类报错Failed to load platform plugin xcb对应系统缺libxcb-xinerama0装上即可复现修复sudo apt install libxcb-xinerama0有些系统还缺libxkbcommon-x11-0和libxcb-icccm4一并装掉sudo apt install libxkbcommon-x11-0 libxcb-icccm4 libxcb-image0 libxcb-keysyms1 libxcb-render-util0error while loading shared libraries: libGL.so.1这就是我之前反复强调的OpenGL依赖缺失。装mesa的GL库sudo apt install libgl1-mesa-glx libgl1-mesa-dev不光是安装器Qt Creator和以后你编译的每个带界面的Qt程序都可能因为这个起不来。5.3 编译程序报“找不到Qt头文件”或qmake版本错乱这个问题集中在装过多个Qt版本或者系统里已经有apt装的旧Qt5.2/5.5/5.12等的用户身上。打开终端敲qmake -v结果出来的是系统自带的版本5.2.1而不是你刚装的5.9.9。这就是PATH顺序问题——/usr/bin/qmake在环境变量里排在~/Qt5.9.9/5.9.9/gcc_64/bin/qmake前面终端找命令时先命中系统旧版本。解决办法确保~/.bashrc里那几行export PATH$QTDIR/bin:$PATH被写在文件最后然后重新source或者干脆把旧版本卸载sudo apt remove qtbase5-dev qt5-qmake另外建议你不嫌麻烦的话直接观察头文件缺失时是不是还少装了一个libqt5widgets5之类的运行库前面章节里那个依赖安装命令只要严格执行一般不会漏。5.4 Qt Creator打开工程时无法识别Kit有时候你新建项目后Qt Creator提示“No valid kits found”或者没有可选的编译器。排查顺序先看Compilers里有没有gcc/g没有就手动添加再看Qt Versions里qmake路径对不对若显示红色打叉说明该Qt版本无效最后看Kits里Kit是否勾选了当前Qt版本。还有一种情况是机器上装的CMake版本过老Qt 5.9.9不强依赖新版CMake但如果你的CMake低于3.1建议升级一下sudo apt install cmake cmake-gui这一步不影响qmake工程只影响你用CMake格式管理Qt工程。5.5 中文乱码或字体残缺一个很多人忽略的系统组件Qt程序在Linux上默认使用系统字体如果你的系统连个中文字体都没装界面上的中文几乎全变成豆腐方块。建议顺手装一下字体sudo apt install fonts-wqy-microhei fonts-wqy-zenhei这也解释了搜“linux 解压文件乱码”这类词的人可能Linux桌面中文编码基础都没配好。反正装Qt开发机字体这步提前做省得回头写第一个中文界面的程序就抓瞎。6. 复盘与经验延展Linux下Qt开发的几个后续建议6.1 要不要换更新版本5.9.9、5.15.2和6.x的选择5.9.9装好后你可能会想问是不是该上5.15.2或者Qt 6。我的看法是看项目需求别盲目追新。5.9.9是LTS稳定性有保障老项目的兼容性最好网上资料最全遇到问题搜解决方案命中率最高。你的项目如果是从老仓库迁过来或者要交叉编译到ARM开发板开发板厂商的SDK配套很可能就锁定在5.9.x这时候老老实实待在这个版本就是最优解。5.15.2是Qt 5系列最后的LTS新增了高DPI缩放、改进的Wayland支持、更好的CMake集成但功能上变化不大如果你要新起项目且不需要Qt 6特性比如Quick 3D重写、RHI渲染架构5.15.2是一个不错的折中。而Qt 6直接重构了不少模块比如QML运行时、图形抽象层必要时要学新接口迁移成本比5.x系列高。你在网上看到大量“qt离线安装包下载5.14”“qt 5.15.2下载”相关的搜索词说明很多人也是从5.9开始折腾一路试到后面的这个进阶路径你可以留着备用。6.2 关于交叉编译、串口调试和嵌入式场景的提醒Qt 5.9.9在嵌入式开发里非常常见。你要交叉编译到ARM开发板需要下对应交叉编译工具链比如gcc-linaro-7.5.0-2019.12-x86_64_arm-linux-gnueabihf然后在qmake工程文件里指定交叉编译器前缀再把Qt源码用交叉工具链重编一遍生成ARM架构的libQt5Core.so。这个过程比桌面上安装复杂好几个数量级。如果你在标题搜到“qt5.5.10 arm linux开发”“ubuntu-20.04 安装 qt 交叉编译环境”这类词大概率就是正走在这条路上。我的建议是先在本机把Qt 5.9.9桌面环境用顺编译流程、环境变量、模块机制都吃透了再去碰交叉编译否则连报错都看不懂。用QtSerialPort做串口调试时Linux下权限是个大坑。默认情况下普通用户访问/dev/ttyUSB0、/dev/ttyS0这类设备是没有权限的。解决办法是把用户加入dialout组sudo usermod -aG dialout $USER等号后面换成你的用户名或者直接复制我的命令但必须记得重启一次或者重新登录才能生效。不加入这个组你的Qt串口程序打开串口时只会返回Permission denied。6.3 备份你的Qt安装包和配置这是老司机的习惯最后分享一个我的个人习惯装完Qt、配好环境变量和Kits以后我会把~/.bashrc中有关Qt的四行配置复制一份到~/qt-env.sh同时把Qt安装包和serialport源码压缩包放到一个专门的/opt/software-backup/目录里。以后换新机器、加了新同事直接拿着压箱底的安装包和配置脚本半小时就能复制出一套一模一样的Qt开发环境不用再半夜去挂下载源。我自己踩过的坑里最冤枉的一次就是环境变量里QT_QPA_PLATFORM被误设为offscreen结果Qt Creator倒是启动了但所有窗口都变成隐形的还以为显卡驱动坏了看了一圈都没回想到env。后来凡是查Qt相关的诡异问题第一步先跑env | grep -i qt看看当前环境变量是否被污染过这比翻日志都快得多。如果你读完文章之后还要折腾“qt模拟鼠标点击事件”“qt桌面画线”“用qt左右平滑滑动的卡片列表”这些进阶话题读完这遍安装教程你的Qt环境中把相关的模块补全了后面做起来会顺畅得多。Linux下的Qt开发没有太多花里胡哨的东西核心就是环境干净、版本明确、模块兜齐把一个版本走透比什么都值。
