企业官网建设流程全解析

如果你现在去搜索引擎里找 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 这些后来的 LTS，5.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 安装路径选哪：用户目录还是 /opt

Qt 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 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 cmake

gdb是 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/qtcreator

Qt Creator 启动后第一件事是 Kit 配置。Kit 可以理解成“一套完整的编译运行组合”：它把 Qt 版本、编译器、调试器、构建工具打包在一个配置里。同一个 Qt 安装目录可以有多个 Kit，但新手只需要一个：Desktop Qt 5.9.9 GCC 64bit。

正常情况下，Qt Creator 会自动检测到安装好的 Qt 5.9.9 和系统 gcc，并自动生成这个 Kit，不需要手动添加。但如果你前面漏装了build-essential，Kit 页面里会显示编译器为空，编译时直接报错，提示大意是“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，选择 GCC，C++ 对应系统里的/usr/bin/g++，C 对应/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.pro：

QT += 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 里的流程是这样：

1. 菜单 File > New File or Project，选择 Application > Qt Widgets Application。
2. 填项目名，比如 hello，选择创建路径。路径不要带中文和空格，5.9.9 的构建链对含空格的路径处理并不友好。
3. 构建套件页面确认勾选 Desktop Qt 5.9.9 GCC 64bit。
4. 默认生成的类先不管，直接点左下角的绿色三角运行。

如果 Kit 配置正确，底部“编译输出”面板会滚动出 qmake、make 的输出，几秒后程序窗口弹出。有一个误区要提醒：Qt Creator 的“运行”按钮是构建并运行，不是只运行。第一次编译项目，尤其用到 Qt Widgets 时，链接耗时几十秒到一分钟都正常，别以为卡住了就提前关掉。

5.3 中文字体、编码与界面显示调优

Qt 5.9.9 在 Linux 下的中文字体显示，只要系统里装了中文字体就没问题。如果显示成方块，装字体：

sudo apt install fonts-noto-cjk

Qt Creator 默认使用 UTF-8 编码，源码文件包含中文时不要改编码。如果你在 Windows 上用记事本编辑过源码再拿到 Linux，可能出现中文乱码或者编译警告，原因是 BOM 和 GBK 编码残留。统一用 UTF-8 无 BOM 格式保存即可。

高分屏下，5.9.9 的界面可能显得字体发虚或者偏小。可以设置缩放：

export QT_AUTO_SCREEN_SCALE_FACTOR=1

然后重启 Qt Creator。这个环境变量告诉 Qt 根据屏幕 DPI 自动调整缩放因子，能明显改善字体过小的问题。不是所有桌面环境都支持，但大多数常见桌面都能受益。

6. 安装路上高频坑的完整排查记录

6.1 坑一：运行安装包没反应，或提示缺 xcb

现象：终端执行./qt-opensource-linux-x64-5.9.9.run后回车，命令卡住很久没反应，或者双击图标完全没反应。

原因分析：安装包本身是图形程序，需要 X11 图形环境。如果你用的是精简桌面、纯 Wayland 会话，或者缺失 xcb 相关库，图形程序就无法正常弹出。还有一种常见情况：从 SSH 终端执行图形安装程序，那当然不会弹窗口。

处理步骤按这个顺序试：

1. 确认你在图形界面的终端里执行，不是 SSH 远程。
2. 确认权限：ls -l看有没有 x，没有就chmod +x。
3. 用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_OPENGL=software

对 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 项目也很顺手。环境配好之后，接下来就是好好写代码的事了。