如果你现在去搜索引擎里找 Qt 5.9.9 的下载地址会发现结果一半是社区博客转载一半是提问帖评论区永远有人在问“为什么双击安装包没反应”或者“为什么装完Qt Creator不能编译”。但恰恰是这些讨论热度说明了一件事到现在还有大量的人、大量的教程、大量的学校课程在 Linux 上用 Qt 5.9.9 入门图形界面开发。这个版本虽然老但它稳定、资料多、对新手友好而且作为离线安装包形式的最后一批版本省去了在线安装器和账号登录的麻烦。这篇文章不是简单丢给你一条下载链接就完事而是基于我在 Ubuntu 系 Linux 发行版上安装 Qt 5.9.9 的完整经历把从下载授权、系统依赖、组件选择、编译器配置到第一个程序跑通的整条链路都捋一遍。同时会把我踩过的坑、网上反复出现的报错、以及它们背后的真实原因一起讲清楚。适合三类人参考正在学 Qt 但卡在环境搭建这一关的新手被课本或课程指定用 5.9.9 版本的学生以及想在一台干净的 Linux 机器上把 Qt 开发环境一次配好的人。1. 为什么那么多人还在找 5.9.9一个 LTS 版本的地位与选型逻辑1.1 5.9.9 在 Qt 版本谱系中的位置先给不熟悉版本谱系的朋友补个背景。Qt 5.9 是 2017 年发布的 LTS 版本也就是长期支持版本官方会提供比普通版本更长时间的 bug 修复和维护。5.9.9 是 5.9 分支的最后一个补丁版本发布于 2019 年底。换句话说你拿到的不是最早那个问题多多的 5.9.0而是修修补补了三年多之后最稳定的 5.9 版本。这也是为什么网上几乎所有推荐帖都让你装 5.9.9而不是 5.9.0 或者 5.9.1。对比一下 Qt 5.12、5.15 这些后来的 LTS5.9.9 的经典之处在于它几乎不需要额外适配就能跑通旧教程里的项目。很多高校的实验指导书、经典 C Qt 教材里的示例代码用的 API 都是 Qt 5.9 时代甚至更早的写法。你如果拿新版 Qt 6 去编译会遇到 QRegExp 被移除、qmake 被弱化成可选工具、部分模块合并到其他包之类的问题老代码很容易报错。而 5.9.9 基本开箱即用能让你把精力放在理解信号槽、布局、事件循环这些核心概念上而不是浪费在“为什么这里编译不过”的版本差异里。1.2 选 5.9.9 而不是新版 Qt 的理由之前有个朋友自己装了最新版 Qt然后照着老教程写项目第一行代码就把头文件路径搞懵了。后来发现是教程基于旧版本很多 API 路径和类名都变了。这其实不是他写错了而是新老版本之间的差异太大。对于入门阶段的人来说找资料先找“这个报错有人遇到过”而 5.9 年代的问题在中文互联网上几乎都能搜到答案相比之下新版遇到的问题往往要翻英文论坛或者官方 issue。学习阶段选一个“资料最丰富”的版本比选“最新”的版本效率高得多。还有一个非常现实的原因5.9.9 是 Linux 离线安装包形式.run 文件的最后一批。之后的 Qt 版本官方逐步转向在线安装器下载和安装都需要 Qt 账号而且在线安装器本身依赖网络状态。很多学生因为网络环境差异或者没有账号拿到离线 .run 包就能直接安装省去一堆麻烦。这也是“qt5.9.9 下载”这个搜索词热度常年不降的原因。1.3 先确认你的发行版与系统架构装之前先确认两件事避免下载错包。第一系统架构。现在绝大多数 PC 是 x86_64终端运行uname -m输出x86_64就下载官方 64 位安装包。如果是aarch64之类的 ARM 架构需要找对应的交叉编译包这里不展开。第二发行版。5.9.9 的官方包对 Ubuntu、Debian、Linux Mint 这些 Debian 系发行版支持最好Fedora、openSUSE 也能用但依赖库名称略有差异。本文以 Ubuntu 系为例其他发行版只要把 apt 换成对应的包管理器原理都一样。国产 Linux 发行版大多也是 Debian 系同样可以参考。磁盘空间也要看一眼完整安装大概需要 4 到 6 GB主要花在 Qt Creator、工具链和模块库上。空间紧张的话后面组件选择时少勾几个模块就行。2. 下载与安装前的环境准备镜像选择、依赖库与权限问题2.1 官方地址与国内镜像的选择逻辑Qt 官方历史版本归档在download.qt.io/archive/qt/5.9/5.9.9/页面结构很简单只需要下载一个文件qt-opensource-linux-x64-5.9.9.run这个安装包大概 1GB 左右。官网下载速度慢是常态国内的开源镜像站比如清华、中科大的镜像源会同步 Qt 的 archive 目录路径通常是/qt/archive/qt/5.9/5.9.9/。如果官网打不开或者速度太慢直接换镜像地址下载。下载完成后建议校验一下 MD5 或 SHA256镜像站一般会同步提供校验文件。这一步看着多余但确实有人因为下载包损坏安装到一半报错回头还以为是依赖问题排查半天。2.2 用文件权限与依赖检查排除“装不上”的隐雷很多人第一次会踩这个坑双击.run文件没反应或者在终端运行./qt-opensource-linux-x64-5.9.9.run提示Permission denied。这是因为.run文件下载下来默认没有可执行权限。解决办法chmod x qt-opensource-linux-x64-5.9.9.run ./qt-opensource-linux-x64-5.9.9.run提示Linux 下拿到.run、.sh这类安装脚本先chmod x要形成肌肉记忆。判断一个文件能不能执行用ls -l看权限位输出里有x就是可执行。接下来是依赖库。Qt 的图形界面在 Linux 上默认走 X11 协议安装包本身依赖一批系统库。Ubuntu 20.04、22.04 这种主流版本一般都自带大部分依赖但如果你装的是精简版、服务器版再自己加桌面环境很可能会缺。提前把下面这些包装好省得安装到一半报错sudo apt update sudo apt install build-essential libgl1-mesa-dev libfontconfig1 libdbus-1-3 libegl1-mesa libxkbcommon-x11-0解释一下为什么要这些包build-essential包含 gcc、g、make、ld 等编译 C/C 项目的核心工具链。很多人装完 Qt 发现“编译器没有”就是漏了这个。libgl1-mesa-dev提供 OpenGL 开发头文件。Qt 的很多控件底层走 OpenGL 渲染Qt Creator 本身也依赖 GL 库。缺了它之后项目编译会报GL/gl.h: No such file or directory。libfontconfig1、libdbus-1-3、libegl1-mesa、libxkbcommon-x11-0分别是字体渲染、系统总线、EGL 支持、X11 键盘映射相关的运行库。这些是 Qt 程序启动时可能加载的动态库缺了会出现启动失败或者无法输入中文。如果你用最小化安装的 Ubuntu Server 加桌面环境建议把 xcb 相关的插件依赖也一起装上sudo apt install libxcb-xinerama0 libxcb-icccm4 libxcb-keysyms1 libxcb-shape0 libxcb-render-util0 libxcb-image0这一步不是必须的但如果后面遇到could not find or load the Qt platform plugin xcb这种启动报错再回来补装。2.3 安装路径选哪用户目录还是 /optQt 5.9.9 的离线安装包接近 1GB安装后占用大约 3 到 5GB。安装路径我强烈建议选在用户目录下比如/home/你的用户名/Qt5.9.9而不是/opt。原因是权限。装到/opt需要 sudo之后每次升级组件、写构建缓存都要 sudo非常别扭。装到用户目录完全没有权限问题也不会影响系统其他用户。唯一的缺点是这台机器上其他用户要用的话需要改路径不过学习场景基本是一人一机。安装时如果选了 Qt WebEngine 模块磁盘占用会明显增加下载和解压时间也更长组件选择那一步我会给具体建议。3. 图形安装向导中的组件取舍与目录规划3.1 不需要登录的 5.9.9 安装向导5.9.9 的安装向导比新版在线安装器简单得多。双击运行后按顺序走过欢迎页、许可协议页勾选同意协议点 Next。接下来会出现一个登录界面这里可以直接跳过Open Source 版本不需要填任何账号点击右下角的 Skip 按钮就能继续。新版在线安装器强制登录这就是老版本离线包最大的便利。安装路径页面默认是/home/用户名/Qt5.9.9建议保持默认。如果改到别处后面 Qt Creator 的自动检测会找不到路径手动配置会多几步。3.2 组件选择学习期不用全选组件选择页是最需要花时间的一步。左侧是模块树以 5.9.9 为例比较关键的几项组件作用建议Qt 5.9.9 (Desktop gcc 64-bit)核心库必选必须勾选Qt Charts / Qt Data Visualization图表与 3D 可视化想学图表再勾不占多少空间Qt WebEngine浏览器内核组件体积大初学者不建议装Qt Script / Qt Virtual Keyboard脚本与虚拟键盘用不到可不选Tools Qt CreatorIDE必选Tools CMake / Ninja构建工具建议选上后面有些教程要用学习期的建议是只保留核心库加 Qt Creator再顺手勾一个 Qt Charts。这样安装速度快磁盘占用小出问题的概率也低。Qt Creator 在 5.9.9 里自带的是 4.5.x 版本界面是老布局菜单栏 Tools 下面找选项这种经典结构反而更容易和老教程对上号。多解释一句附加模块是在你勾选后和主库一起解压到安装目录的不是像新版那样随时能在线增删。所以如果中途想加模块只能重新走一遍安装向导或者手动下载模块包挺麻烦。建议先想清楚后面大概率会写报表类界面Qt Charts 可以顺手勾上如果只写 Widgets 和控制台不勾完全没问题。3.3 等待安装期间做点正事同步装好 gdb 和 cmake安装 Qt 本体的过程大概 5 到 15 分钟取决于磁盘速度。这个等待时间不要闲着在另一个终端把调试器和构建工具装上sudo apt install gdb cmakegdb是 Qt Creator 的调试器没有它你点 Debug 运行时 IDE 会一直提示No Debugger。cmake是除了 qmake 之外的另一套构建体系Qt 5.9.9 自带的示例工程里有一部分是 CMake 工程后面如果接触第三方库CMake 几乎绕不开。提前装好省得之后为“装个库还要去配置环境”再折腾一轮。装完之后用以下命令确认工具链都可用gcc --version g --version gdb --version cmake --version如果哪条命令提示command not found就回到上面 apt install 的命令重新装。3.4 安装完成后的目录结构安装完成后主目录下会多出一个Qt5.9.9文件夹。里面值得认一下结构~/Qt5.9.9/ ├── 5.9.9/ │ └── gcc_64/ │ ├── bin/ # qmake、qtdiag、moc、rcc 等工具 │ ├── lib/ # Qt 核心运行库 │ ├── include/ # Qt 头文件 │ ├── plugins/ # 平台插件、图像格式插件等 │ └── qml/ # QML 模块 ├── Tools/ │ └── QtCreator/ # Qt Creator IDE 本体 └── Examples/ # 示例工程如果勾选了理解这个结构很关键。很多环境变量、IDE 配置、报错信息都和路径有关。你之后会反复用到gcc_64/bin/qmake这个路径在 Qt Creator 里它对应“Qt Version”配置在终端里它是编译 Qt 工程的入口。4. 认识 Qt Creator 的 Kits 机制编译器自动检测与手动修正4.1 启动 Qt Creator 与 Kit 的概念安装完成后可以从应用菜单里找到 Qt Creator 图标或者在终端启动~/Qt5.9.9/Tools/QtCreator/bin/qtcreatorQt Creator 启动后第一件事是 Kit 配置。Kit 可以理解成“一套完整的编译运行组合”它把 Qt 版本、编译器、调试器、构建工具打包在一个配置里。同一个 Qt 安装目录可以有多个 Kit但新手只需要一个Desktop Qt 5.9.9 GCC 64bit。正常情况下Qt Creator 会自动检测到安装好的 Qt 5.9.9 和系统 gcc并自动生成这个 Kit不需要手动添加。但如果你前面漏装了build-essentialKit 页面里会显示编译器为空编译时直接报错提示大意是“Qt Creator needs a compiler set up”。这时候你要反应过来这不是 Qt 的问题是系统的 gcc/g 没装。4.2 自动检测失效时的排查与手动添加也可能遇到这种情况系统里明明有 gcc但 Qt Creator 就是检测不到。常见原因有两个一是用了发行版自带的 Qt Creator 或者 snap 版本它的隔离机制看不到/usr/bin下的条目二是 PATH 环境变量被改过不带/usr/bin。这类问题先排查which gcc g gdb cmake如果which能找到但 Creator 检测不到手动添加即可。Qt Creator 4.5 的配置入口是 Tools Options然后左侧 Build Run 分类下有 Compilers、Debuggers、Qt Versions、Kits 四个选项卡。在 Compilers 选项卡里点 Add选择 GCCC 对应系统里的/usr/bin/gC 对应/usr/bin/gcc。然后在 Qt Versions 选项卡里点 Add选择 qmake 路径/home/你的用户名/Qt5.9.9/5.9.9/gcc_64/bin/qmake添加完毕后切到 Kits 选项卡把刚才的编译器、qmake、gdb 组合起来命名类似“Manual Kit”。如果 Kit 页面看到黄色感叹号鼠标放上去会提示缺什么。比如提示No debugger就去 Debuggers 选项卡 Add 一个/usr/bin/gdb。4.3 qmake、Shadow Build、运行目录这些概念一次说清Qt Creator 默认启用 Shadow Build也就是构建目录和源码目录分离。你的源码在~/projects/hello编译生成的临时文件放在~/build-hello-Desktop_Qt_5_9_9_GCC_64bit-Debug下源码目录不会被一堆.o文件和 moc 生成物弄脏。这是做项目的良好习惯保持默认即可。qmake 的作用是根据.pro工程文件生成 Makefile然后由 make 调用 gcc/g 完成编译。在 Qt Creator 里点“构建”按钮本质就是在幕后执行qmake make。理解这个链条后终端编译和 IDE 里编译就不是两个世界了。运行目录默认是构建目录不是源码目录。如果你在程序里用相对路径读取图片、配置文件文件要放到构建目录里。这是一个很多人绕了很久的坑源代码里写了QFile(config.ini)结果运行时找不到因为当前工作目录是 build 目录。5. 第一次编译运行从 qmake 命令行到 IDE 新建项目5.1 用终端跑通第一个 Qt 程序验证安装最直接的方式是用终端不经过 IDE。新建一个目录写一个最简单的 Qt 程序#include QApplication #include QLabel int main(int argc, char *argv[]) { QApplication app(argc, argv); QLabel label(Qt 5.9.9 is running on Linux); label.resize(320, 120); label.show(); return app.exec(); }保存为hello.cpp同目录下生成hello.proQT widgets SOURCES hello.cpp然后依次执行~/Qt5.9.9/5.9.9/gcc_64/bin/qmake hello.pro make -j4 ./hello如果一切正常屏幕上会出现一个窗口显示一段文字。看到窗口的瞬间就说明 Qt 库、编译器、连接器、动态库加载机制全都在正常工作。这一步成功之后再进 Qt Creator心里就有底了。如果./hello报错error while loading shared libraries: libQt5Widgets.so.5说明程序运行时找不到 Qt 动态库需要把 Qt 库路径加入环境变量export LD_LIBRARY_PATH~/Qt5.9.9/5.9.9/gcc_64/lib:$LD_LIBRARY_PATH注意这条export只在当前终端生效。想让每次打开终端都生效就把这行追加到~/.bashrc末尾再source ~/.bashrc。提示用 qmake 生成的 Makefile 默认会写入 rpath正常情况不需要手动设LD_LIBRARY_PATH。这个报错主要出现在你直接用 g 编译、绕过 qmake 构建链的时候。但理解了动态库加载机制出问题时就不会慌。5.2 Qt Creator 里新建项目的完整流程Qt Creator 里的流程是这样菜单 File New File or Project选择 Application Qt Widgets Application。填项目名比如 hello选择创建路径。路径不要带中文和空格5.9.9 的构建链对含空格的路径处理并不友好。构建套件页面确认勾选 Desktop Qt 5.9.9 GCC 64bit。默认生成的类先不管直接点左下角的绿色三角运行。如果 Kit 配置正确底部“编译输出”面板会滚动出 qmake、make 的输出几秒后程序窗口弹出。有一个误区要提醒Qt Creator 的“运行”按钮是构建并运行不是只运行。第一次编译项目尤其用到 Qt Widgets 时链接耗时几十秒到一分钟都正常别以为卡住了就提前关掉。5.3 中文字体、编码与界面显示调优Qt 5.9.9 在 Linux 下的中文字体显示只要系统里装了中文字体就没问题。如果显示成方块装字体sudo apt install fonts-noto-cjkQt Creator 默认使用 UTF-8 编码源码文件包含中文时不要改编码。如果你在 Windows 上用记事本编辑过源码再拿到 Linux可能出现中文乱码或者编译警告原因是 BOM 和 GBK 编码残留。统一用 UTF-8 无 BOM 格式保存即可。高分屏下5.9.9 的界面可能显得字体发虚或者偏小。可以设置缩放export QT_AUTO_SCREEN_SCALE_FACTOR1然后重启 Qt Creator。这个环境变量告诉 Qt 根据屏幕 DPI 自动调整缩放因子能明显改善字体过小的问题。不是所有桌面环境都支持但大多数常见桌面都能受益。6. 安装路上高频坑的完整排查记录6.1 坑一运行安装包没反应或提示缺 xcb现象终端执行./qt-opensource-linux-x64-5.9.9.run后回车命令卡住很久没反应或者双击图标完全没反应。原因分析安装包本身是图形程序需要 X11 图形环境。如果你用的是精简桌面、纯 Wayland 会话或者缺失 xcb 相关库图形程序就无法正常弹出。还有一种常见情况从 SSH 终端执行图形安装程序那当然不会弹窗口。处理步骤按这个顺序试确认你在图形界面的终端里执行不是 SSH 远程。确认权限ls -l看有没有 x没有就chmod x。用ldd查看安装包的动态库依赖这是排查 Linux 动态链接问题的利器ldd qt-opensource-linux-x64-5.9.9.run输出里看到missing字样的行就是缺失的库。根据库名去 apt 搜索安装比如libxcb开头的库缺失就装对应的libxcb-*-dev或libxcb-*运行库libxkbcommon缺失就装libxkbcommon-x11-0。6.2 坑二编译报了 GL/gl.h 找不到现象在 Qt Creator 里构建第一个项目报错fatal error: GL/gl.h: No such file or directory原因分析Qt Widgets 的部分底层渲染依赖 OpenGL 头文件。这个头文件属于 mesa 开发包Ubuntu/Debian 系对应的包是libgl1-mesa-dev。如果你跳过了第 2 章的依赖安装现在补上sudo apt install libgl1-mesa-dev装完回到 Qt Creator在项目菜单里先“清理”再重新“构建”。这一步很重要因为 Makefile 已经生成过了缺头文件的错误信息可能残留在中间状态里直接点运行不会触发重新检查。看到 GL 相关的报错先冷静大部分环境只要把 mesa 开发包装好就能解决不代表你的显卡有问题。6.3 坑三程序能编译但启动就崩溃报 xcb platform plugin现象编译通过一运行就弹出This application failed to start because it could not find or load the Qt platform plugin xcb.原因分析Qt 通过平台插件和底层图形环境通信xcb 是 X11 环境的平台插件。运行时如果找不到这个插件或者插件依赖的 xcb 库不全Qt 就无法创建窗口。这个问题我遇到很多次基本都是系统缺少部分 xcb 扩展库导致的。解决分两步。第一步确认插件本身存在ls ~/Qt5.9.9/5.9.9/gcc_64/plugins/platforms/正常情况下能看到libqxcb.so。如果这个文件不存在说明安装不完整需要重新运行安装向导补组件。如果文件存在那就是它依赖的 xcb 库有问题。继续用ldd定位ldd ~/Qt5.9.9/5.9.9/gcc_64/plugins/platforms/libqxcb.so | grep not found哪一行提示not found就装哪个库。一次性把所有常见 xcb 扩展库补上sudo apt install libxcb-xinerama0 libxcb-icccm4 libxcb-keysyms1 libxcb-shape0 libxcb-render-util0 libxcb-image0 libxkbcommon-x11-0装完重新运行程序。绝大多数 xcb 启动崩溃都能通过这个方案恢复。6.4 一个额外提醒虚拟机与远程桌面场景如果你是在虚拟机里装 Linux 学 Qt会遇到 OpenGL 能力受限的问题。表现为Qt 程序能运行但窗口加载慢、拖动卡顿。这是虚拟机显卡驱动的正常现象不是安装错误。学习阶段完全不影响写代码、调试和编译。如果实在觉得卡可以强制 Qt 走软件渲染export QT_OPENGLsoftware对 Widgets 应用来说软件渲染性能完全够用。QML 动画可能会掉帧但入门阶段主要是 Widgets软件渲染够跑。7. 写在最后安装 Qt 5.9.9 这件事说难其实不难只要按顺序把系统工具链、依赖库、安装包权限这三件事处理好剩下的基本都是自动的。我在不同发行版上装过很多次每次出问题最后都能归到三条缺了build-essential、缺了 mesa 开发库、缺了 xcb 扩展。把这三条提前堵住安装过程基本可以一次通过。如果你在安装过程中遇到没见过的报错我建议养成一个习惯先看终端里完整的报错内容再决定搜索关键词而不是直接把整段报错复制去查。多数时候你查到的第一个答案就是某个社区里的同一个问题翻一翻评论看看有没有人补充“这个方法在某某版本上也适用”往往比只看主楼更有效。Qt 这个圈子用的人多坑早就被踩平了你缺少的只是把“报错信息”翻译成“搜索关键词”的本事。最后再分享一个小技巧装好之后把~/Qt5.9.9/5.9.9/gcc_64/bin和~/Qt5.9.9/Tools/QtCreator/bin加进 PATH。加进去之后qmake、qtdiag、qtcreator这些命令可以直接使用写个小脚本批量编译 Qt 项目也很顺手。环境配好之后接下来就是好好写代码的事了。 
长河君 · 2026/9/18 21:10:32 · 阅读 1.2k Qt 5.9.9 Linux 安装与配置指南：从零搭建 Qt Creator 开发环境
如果你现在去搜索引擎里找 Qt 5.9.9 的下载地址会发现结果一半是社区博客转载一半是提问帖评论区永远有人在问“为什么双击安装包没反应”或者“为什么装完Qt Creator不能编译”。但恰恰是这些讨论热度说明了一件事到现在还有大量的人、大量的教程、大量的学校课程在 Linux 上用 Qt 5.9.9 入门图形界面开发。这个版本虽然老但它稳定、资料多、对新手友好而且作为离线安装包形式的最后一批版本省去了在线安装器和账号登录的麻烦。这篇文章不是简单丢给你一条下载链接就完事而是基于我在 Ubuntu 系 Linux 发行版上安装 Qt 5.9.9 的完整经历把从下载授权、系统依赖、组件选择、编译器配置到第一个程序跑通的整条链路都捋一遍。同时会把我踩过的坑、网上反复出现的报错、以及它们背后的真实原因一起讲清楚。适合三类人参考正在学 Qt 但卡在环境搭建这一关的新手被课本或课程指定用 5.9.9 版本的学生以及想在一台干净的 Linux 机器上把 Qt 开发环境一次配好的人。1. 为什么那么多人还在找 5.9.9一个 LTS 版本的地位与选型逻辑1.1 5.9.9 在 Qt 版本谱系中的位置先给不熟悉版本谱系的朋友补个背景。Qt 5.9 是 2017 年发布的 LTS 版本也就是长期支持版本官方会提供比普通版本更长时间的 bug 修复和维护。5.9.9 是 5.9 分支的最后一个补丁版本发布于 2019 年底。换句话说你拿到的不是最早那个问题多多的 5.9.0而是修修补补了三年多之后最稳定的 5.9 版本。这也是为什么网上几乎所有推荐帖都让你装 5.9.9而不是 5.9.0 或者 5.9.1。对比一下 Qt 5.12、5.15 这些后来的 LTS5.9.9 的经典之处在于它几乎不需要额外适配就能跑通旧教程里的项目。很多高校的实验指导书、经典 C Qt 教材里的示例代码用的 API 都是 Qt 5.9 时代甚至更早的写法。你如果拿新版 Qt 6 去编译会遇到 QRegExp 被移除、qmake 被弱化成可选工具、部分模块合并到其他包之类的问题老代码很容易报错。而 5.9.9 基本开箱即用能让你把精力放在理解信号槽、布局、事件循环这些核心概念上而不是浪费在“为什么这里编译不过”的版本差异里。1.2 选 5.9.9 而不是新版 Qt 的理由之前有个朋友自己装了最新版 Qt然后照着老教程写项目第一行代码就把头文件路径搞懵了。后来发现是教程基于旧版本很多 API 路径和类名都变了。这其实不是他写错了而是新老版本之间的差异太大。对于入门阶段的人来说找资料先找“这个报错有人遇到过”而 5.9 年代的问题在中文互联网上几乎都能搜到答案相比之下新版遇到的问题往往要翻英文论坛或者官方 issue。学习阶段选一个“资料最丰富”的版本比选“最新”的版本效率高得多。还有一个非常现实的原因5.9.9 是 Linux 离线安装包形式.run 文件的最后一批。之后的 Qt 版本官方逐步转向在线安装器下载和安装都需要 Qt 账号而且在线安装器本身依赖网络状态。很多学生因为网络环境差异或者没有账号拿到离线 .run 包就能直接安装省去一堆麻烦。这也是“qt5.9.9 下载”这个搜索词热度常年不降的原因。1.3 先确认你的发行版与系统架构装之前先确认两件事避免下载错包。第一系统架构。现在绝大多数 PC 是 x86_64终端运行uname -m输出x86_64就下载官方 64 位安装包。如果是aarch64之类的 ARM 架构需要找对应的交叉编译包这里不展开。第二发行版。5.9.9 的官方包对 Ubuntu、Debian、Linux Mint 这些 Debian 系发行版支持最好Fedora、openSUSE 也能用但依赖库名称略有差异。本文以 Ubuntu 系为例其他发行版只要把 apt 换成对应的包管理器原理都一样。国产 Linux 发行版大多也是 Debian 系同样可以参考。磁盘空间也要看一眼完整安装大概需要 4 到 6 GB主要花在 Qt Creator、工具链和模块库上。空间紧张的话后面组件选择时少勾几个模块就行。2. 下载与安装前的环境准备镜像选择、依赖库与权限问题2.1 官方地址与国内镜像的选择逻辑Qt 官方历史版本归档在download.qt.io/archive/qt/5.9/5.9.9/页面结构很简单只需要下载一个文件qt-opensource-linux-x64-5.9.9.run这个安装包大概 1GB 左右。官网下载速度慢是常态国内的开源镜像站比如清华、中科大的镜像源会同步 Qt 的 archive 目录路径通常是/qt/archive/qt/5.9/5.9.9/。如果官网打不开或者速度太慢直接换镜像地址下载。下载完成后建议校验一下 MD5 或 SHA256镜像站一般会同步提供校验文件。这一步看着多余但确实有人因为下载包损坏安装到一半报错回头还以为是依赖问题排查半天。2.2 用文件权限与依赖检查排除“装不上”的隐雷很多人第一次会踩这个坑双击.run文件没反应或者在终端运行./qt-opensource-linux-x64-5.9.9.run提示Permission denied。这是因为.run文件下载下来默认没有可执行权限。解决办法chmod x qt-opensource-linux-x64-5.9.9.run ./qt-opensource-linux-x64-5.9.9.run提示Linux 下拿到.run、.sh这类安装脚本先chmod x要形成肌肉记忆。判断一个文件能不能执行用ls -l看权限位输出里有x就是可执行。接下来是依赖库。Qt 的图形界面在 Linux 上默认走 X11 协议安装包本身依赖一批系统库。Ubuntu 20.04、22.04 这种主流版本一般都自带大部分依赖但如果你装的是精简版、服务器版再自己加桌面环境很可能会缺。提前把下面这些包装好省得安装到一半报错sudo apt update sudo apt install build-essential libgl1-mesa-dev libfontconfig1 libdbus-1-3 libegl1-mesa libxkbcommon-x11-0解释一下为什么要这些包build-essential包含 gcc、g、make、ld 等编译 C/C 项目的核心工具链。很多人装完 Qt 发现“编译器没有”就是漏了这个。libgl1-mesa-dev提供 OpenGL 开发头文件。Qt 的很多控件底层走 OpenGL 渲染Qt Creator 本身也依赖 GL 库。缺了它之后项目编译会报GL/gl.h: No such file or directory。libfontconfig1、libdbus-1-3、libegl1-mesa、libxkbcommon-x11-0分别是字体渲染、系统总线、EGL 支持、X11 键盘映射相关的运行库。这些是 Qt 程序启动时可能加载的动态库缺了会出现启动失败或者无法输入中文。如果你用最小化安装的 Ubuntu Server 加桌面环境建议把 xcb 相关的插件依赖也一起装上sudo apt install libxcb-xinerama0 libxcb-icccm4 libxcb-keysyms1 libxcb-shape0 libxcb-render-util0 libxcb-image0这一步不是必须的但如果后面遇到could not find or load the Qt platform plugin xcb这种启动报错再回来补装。2.3 安装路径选哪用户目录还是 /optQt 5.9.9 的离线安装包接近 1GB安装后占用大约 3 到 5GB。安装路径我强烈建议选在用户目录下比如/home/你的用户名/Qt5.9.9而不是/opt。原因是权限。装到/opt需要 sudo之后每次升级组件、写构建缓存都要 sudo非常别扭。装到用户目录完全没有权限问题也不会影响系统其他用户。唯一的缺点是这台机器上其他用户要用的话需要改路径不过学习场景基本是一人一机。安装时如果选了 Qt WebEngine 模块磁盘占用会明显增加下载和解压时间也更长组件选择那一步我会给具体建议。3. 图形安装向导中的组件取舍与目录规划3.1 不需要登录的 5.9.9 安装向导5.9.9 的安装向导比新版在线安装器简单得多。双击运行后按顺序走过欢迎页、许可协议页勾选同意协议点 Next。接下来会出现一个登录界面这里可以直接跳过Open Source 版本不需要填任何账号点击右下角的 Skip 按钮就能继续。新版在线安装器强制登录这就是老版本离线包最大的便利。安装路径页面默认是/home/用户名/Qt5.9.9建议保持默认。如果改到别处后面 Qt Creator 的自动检测会找不到路径手动配置会多几步。3.2 组件选择学习期不用全选组件选择页是最需要花时间的一步。左侧是模块树以 5.9.9 为例比较关键的几项组件作用建议Qt 5.9.9 (Desktop gcc 64-bit)核心库必选必须勾选Qt Charts / Qt Data Visualization图表与 3D 可视化想学图表再勾不占多少空间Qt WebEngine浏览器内核组件体积大初学者不建议装Qt Script / Qt Virtual Keyboard脚本与虚拟键盘用不到可不选Tools Qt CreatorIDE必选Tools CMake / Ninja构建工具建议选上后面有些教程要用学习期的建议是只保留核心库加 Qt Creator再顺手勾一个 Qt Charts。这样安装速度快磁盘占用小出问题的概率也低。Qt Creator 在 5.9.9 里自带的是 4.5.x 版本界面是老布局菜单栏 Tools 下面找选项这种经典结构反而更容易和老教程对上号。多解释一句附加模块是在你勾选后和主库一起解压到安装目录的不是像新版那样随时能在线增删。所以如果中途想加模块只能重新走一遍安装向导或者手动下载模块包挺麻烦。建议先想清楚后面大概率会写报表类界面Qt Charts 可以顺手勾上如果只写 Widgets 和控制台不勾完全没问题。3.3 等待安装期间做点正事同步装好 gdb 和 cmake安装 Qt 本体的过程大概 5 到 15 分钟取决于磁盘速度。这个等待时间不要闲着在另一个终端把调试器和构建工具装上sudo apt install gdb cmakegdb是 Qt Creator 的调试器没有它你点 Debug 运行时 IDE 会一直提示No Debugger。cmake是除了 qmake 之外的另一套构建体系Qt 5.9.9 自带的示例工程里有一部分是 CMake 工程后面如果接触第三方库CMake 几乎绕不开。提前装好省得之后为“装个库还要去配置环境”再折腾一轮。装完之后用以下命令确认工具链都可用gcc --version g --version gdb --version cmake --version如果哪条命令提示command not found就回到上面 apt install 的命令重新装。3.4 安装完成后的目录结构安装完成后主目录下会多出一个Qt5.9.9文件夹。里面值得认一下结构~/Qt5.9.9/ ├── 5.9.9/ │ └── gcc_64/ │ ├── bin/ # qmake、qtdiag、moc、rcc 等工具 │ ├── lib/ # Qt 核心运行库 │ ├── include/ # Qt 头文件 │ ├── plugins/ # 平台插件、图像格式插件等 │ └── qml/ # QML 模块 ├── Tools/ │ └── QtCreator/ # Qt Creator IDE 本体 └── Examples/ # 示例工程如果勾选了理解这个结构很关键。很多环境变量、IDE 配置、报错信息都和路径有关。你之后会反复用到gcc_64/bin/qmake这个路径在 Qt Creator 里它对应“Qt Version”配置在终端里它是编译 Qt 工程的入口。4. 认识 Qt Creator 的 Kits 机制编译器自动检测与手动修正4.1 启动 Qt Creator 与 Kit 的概念安装完成后可以从应用菜单里找到 Qt Creator 图标或者在终端启动~/Qt5.9.9/Tools/QtCreator/bin/qtcreatorQt Creator 启动后第一件事是 Kit 配置。Kit 可以理解成“一套完整的编译运行组合”它把 Qt 版本、编译器、调试器、构建工具打包在一个配置里。同一个 Qt 安装目录可以有多个 Kit但新手只需要一个Desktop Qt 5.9.9 GCC 64bit。正常情况下Qt Creator 会自动检测到安装好的 Qt 5.9.9 和系统 gcc并自动生成这个 Kit不需要手动添加。但如果你前面漏装了build-essentialKit 页面里会显示编译器为空编译时直接报错提示大意是“Qt Creator needs a compiler set up”。这时候你要反应过来这不是 Qt 的问题是系统的 gcc/g 没装。4.2 自动检测失效时的排查与手动添加也可能遇到这种情况系统里明明有 gcc但 Qt Creator 就是检测不到。常见原因有两个一是用了发行版自带的 Qt Creator 或者 snap 版本它的隔离机制看不到/usr/bin下的条目二是 PATH 环境变量被改过不带/usr/bin。这类问题先排查which gcc g gdb cmake如果which能找到但 Creator 检测不到手动添加即可。Qt Creator 4.5 的配置入口是 Tools Options然后左侧 Build Run 分类下有 Compilers、Debuggers、Qt Versions、Kits 四个选项卡。在 Compilers 选项卡里点 Add选择 GCCC 对应系统里的/usr/bin/gC 对应/usr/bin/gcc。然后在 Qt Versions 选项卡里点 Add选择 qmake 路径/home/你的用户名/Qt5.9.9/5.9.9/gcc_64/bin/qmake添加完毕后切到 Kits 选项卡把刚才的编译器、qmake、gdb 组合起来命名类似“Manual Kit”。如果 Kit 页面看到黄色感叹号鼠标放上去会提示缺什么。比如提示No debugger就去 Debuggers 选项卡 Add 一个/usr/bin/gdb。4.3 qmake、Shadow Build、运行目录这些概念一次说清Qt Creator 默认启用 Shadow Build也就是构建目录和源码目录分离。你的源码在~/projects/hello编译生成的临时文件放在~/build-hello-Desktop_Qt_5_9_9_GCC_64bit-Debug下源码目录不会被一堆.o文件和 moc 生成物弄脏。这是做项目的良好习惯保持默认即可。qmake 的作用是根据.pro工程文件生成 Makefile然后由 make 调用 gcc/g 完成编译。在 Qt Creator 里点“构建”按钮本质就是在幕后执行qmake make。理解这个链条后终端编译和 IDE 里编译就不是两个世界了。运行目录默认是构建目录不是源码目录。如果你在程序里用相对路径读取图片、配置文件文件要放到构建目录里。这是一个很多人绕了很久的坑源代码里写了QFile(config.ini)结果运行时找不到因为当前工作目录是 build 目录。5. 第一次编译运行从 qmake 命令行到 IDE 新建项目5.1 用终端跑通第一个 Qt 程序验证安装最直接的方式是用终端不经过 IDE。新建一个目录写一个最简单的 Qt 程序#include QApplication #include QLabel int main(int argc, char *argv[]) { QApplication app(argc, argv); QLabel label(Qt 5.9.9 is running on Linux); label.resize(320, 120); label.show(); return app.exec(); }保存为hello.cpp同目录下生成hello.proQT widgets SOURCES hello.cpp然后依次执行~/Qt5.9.9/5.9.9/gcc_64/bin/qmake hello.pro make -j4 ./hello如果一切正常屏幕上会出现一个窗口显示一段文字。看到窗口的瞬间就说明 Qt 库、编译器、连接器、动态库加载机制全都在正常工作。这一步成功之后再进 Qt Creator心里就有底了。如果./hello报错error while loading shared libraries: libQt5Widgets.so.5说明程序运行时找不到 Qt 动态库需要把 Qt 库路径加入环境变量export LD_LIBRARY_PATH~/Qt5.9.9/5.9.9/gcc_64/lib:$LD_LIBRARY_PATH注意这条export只在当前终端生效。想让每次打开终端都生效就把这行追加到~/.bashrc末尾再source ~/.bashrc。提示用 qmake 生成的 Makefile 默认会写入 rpath正常情况不需要手动设LD_LIBRARY_PATH。这个报错主要出现在你直接用 g 编译、绕过 qmake 构建链的时候。但理解了动态库加载机制出问题时就不会慌。5.2 Qt Creator 里新建项目的完整流程Qt Creator 里的流程是这样菜单 File New File or Project选择 Application Qt Widgets Application。填项目名比如 hello选择创建路径。路径不要带中文和空格5.9.9 的构建链对含空格的路径处理并不友好。构建套件页面确认勾选 Desktop Qt 5.9.9 GCC 64bit。默认生成的类先不管直接点左下角的绿色三角运行。如果 Kit 配置正确底部“编译输出”面板会滚动出 qmake、make 的输出几秒后程序窗口弹出。有一个误区要提醒Qt Creator 的“运行”按钮是构建并运行不是只运行。第一次编译项目尤其用到 Qt Widgets 时链接耗时几十秒到一分钟都正常别以为卡住了就提前关掉。5.3 中文字体、编码与界面显示调优Qt 5.9.9 在 Linux 下的中文字体显示只要系统里装了中文字体就没问题。如果显示成方块装字体sudo apt install fonts-noto-cjkQt Creator 默认使用 UTF-8 编码源码文件包含中文时不要改编码。如果你在 Windows 上用记事本编辑过源码再拿到 Linux可能出现中文乱码或者编译警告原因是 BOM 和 GBK 编码残留。统一用 UTF-8 无 BOM 格式保存即可。高分屏下5.9.9 的界面可能显得字体发虚或者偏小。可以设置缩放export QT_AUTO_SCREEN_SCALE_FACTOR1然后重启 Qt Creator。这个环境变量告诉 Qt 根据屏幕 DPI 自动调整缩放因子能明显改善字体过小的问题。不是所有桌面环境都支持但大多数常见桌面都能受益。6. 安装路上高频坑的完整排查记录6.1 坑一运行安装包没反应或提示缺 xcb现象终端执行./qt-opensource-linux-x64-5.9.9.run后回车命令卡住很久没反应或者双击图标完全没反应。原因分析安装包本身是图形程序需要 X11 图形环境。如果你用的是精简桌面、纯 Wayland 会话或者缺失 xcb 相关库图形程序就无法正常弹出。还有一种常见情况从 SSH 终端执行图形安装程序那当然不会弹窗口。处理步骤按这个顺序试确认你在图形界面的终端里执行不是 SSH 远程。确认权限ls -l看有没有 x没有就chmod x。用ldd查看安装包的动态库依赖这是排查 Linux 动态链接问题的利器ldd qt-opensource-linux-x64-5.9.9.run输出里看到missing字样的行就是缺失的库。根据库名去 apt 搜索安装比如libxcb开头的库缺失就装对应的libxcb-*-dev或libxcb-*运行库libxkbcommon缺失就装libxkbcommon-x11-0。6.2 坑二编译报了 GL/gl.h 找不到现象在 Qt Creator 里构建第一个项目报错fatal error: GL/gl.h: No such file or directory原因分析Qt Widgets 的部分底层渲染依赖 OpenGL 头文件。这个头文件属于 mesa 开发包Ubuntu/Debian 系对应的包是libgl1-mesa-dev。如果你跳过了第 2 章的依赖安装现在补上sudo apt install libgl1-mesa-dev装完回到 Qt Creator在项目菜单里先“清理”再重新“构建”。这一步很重要因为 Makefile 已经生成过了缺头文件的错误信息可能残留在中间状态里直接点运行不会触发重新检查。看到 GL 相关的报错先冷静大部分环境只要把 mesa 开发包装好就能解决不代表你的显卡有问题。6.3 坑三程序能编译但启动就崩溃报 xcb platform plugin现象编译通过一运行就弹出This application failed to start because it could not find or load the Qt platform plugin xcb.原因分析Qt 通过平台插件和底层图形环境通信xcb 是 X11 环境的平台插件。运行时如果找不到这个插件或者插件依赖的 xcb 库不全Qt 就无法创建窗口。这个问题我遇到很多次基本都是系统缺少部分 xcb 扩展库导致的。解决分两步。第一步确认插件本身存在ls ~/Qt5.9.9/5.9.9/gcc_64/plugins/platforms/正常情况下能看到libqxcb.so。如果这个文件不存在说明安装不完整需要重新运行安装向导补组件。如果文件存在那就是它依赖的 xcb 库有问题。继续用ldd定位ldd ~/Qt5.9.9/5.9.9/gcc_64/plugins/platforms/libqxcb.so | grep not found哪一行提示not found就装哪个库。一次性把所有常见 xcb 扩展库补上sudo apt install libxcb-xinerama0 libxcb-icccm4 libxcb-keysyms1 libxcb-shape0 libxcb-render-util0 libxcb-image0 libxkbcommon-x11-0装完重新运行程序。绝大多数 xcb 启动崩溃都能通过这个方案恢复。6.4 一个额外提醒虚拟机与远程桌面场景如果你是在虚拟机里装 Linux 学 Qt会遇到 OpenGL 能力受限的问题。表现为Qt 程序能运行但窗口加载慢、拖动卡顿。这是虚拟机显卡驱动的正常现象不是安装错误。学习阶段完全不影响写代码、调试和编译。如果实在觉得卡可以强制 Qt 走软件渲染export QT_OPENGLsoftware对 Widgets 应用来说软件渲染性能完全够用。QML 动画可能会掉帧但入门阶段主要是 Widgets软件渲染够跑。7. 写在最后安装 Qt 5.9.9 这件事说难其实不难只要按顺序把系统工具链、依赖库、安装包权限这三件事处理好剩下的基本都是自动的。我在不同发行版上装过很多次每次出问题最后都能归到三条缺了build-essential、缺了 mesa 开发库、缺了 xcb 扩展。把这三条提前堵住安装过程基本可以一次通过。如果你在安装过程中遇到没见过的报错我建议养成一个习惯先看终端里完整的报错内容再决定搜索关键词而不是直接把整段报错复制去查。多数时候你查到的第一个答案就是某个社区里的同一个问题翻一翻评论看看有没有人补充“这个方法在某某版本上也适用”往往比只看主楼更有效。Qt 这个圈子用的人多坑早就被踩平了你缺少的只是把“报错信息”翻译成“搜索关键词”的本事。最后再分享一个小技巧装好之后把~/Qt5.9.9/5.9.9/gcc_64/bin和~/Qt5.9.9/Tools/QtCreator/bin加进 PATH。加进去之后qmake、qtdiag、qtcreator这些命令可以直接使用写个小脚本批量编译 Qt 项目也很顺手。环境配好之后接下来就是好好写代码的事了。