Linux Qt开发环境搭建指南：依赖、Kits配置与高频报错排查-开发者社区

我一直觉得，Linux下QT开发环境搭建这件事，看起来是“装个软件”的小事，但真正趟过一次就会明白，它背后牵涉的坑远比想象中多。发行版选哪个、Qt版本用5还是6、装在线版还是apt版、跑起来之后为什么窗口弹不出来、为什么控件全是方块字，这些问题如果没人提前说清，新手往往要花一两天反复折腾。

这篇笔记想做的事，就是把我实际搭建环境的过程完整记录下来，从系统依赖、工具链准备，到Qt安装、环境变量、Qt Creator套件配置，再到第一个测试工程和几个高频报错的排查，尽量做到“照着做就能跑通”。适合刚接触Linux桌面开发的同学，也适合之前只做过Windows下Qt开发、第一次转到Linux上干活的人读。

1. 动手之前先整明白：版本、组件和安装路线

1.1 Ubuntu 22.04 + Qt 6.5 LTS的组合选择

我这边演示环境用的是Ubuntu 22.04，这是目前很常见的LTS发行版，包管理器源成熟，硬件兼容性好，跑Qt开发环境基本不用动驱动。如果你用的是Debian这类Debian系系统，下面这些命令绝大部分也能直接复用；如果是Fedora、Arch，把包管理器对应的改一下即可，思路不变。

Qt版本怎么选？简单说：非特殊需求，优先建议装LTS版本。Qt 5.15.2是维护了很久的稳定版，资料多、兼容旧工程；Qt 6.5之后也进入了LTS状态，整体新特性更舒服，比如QML渲染走RHI、控件风格统一，工具链也更现代。如果你是要学新项目、做跨平台新应用，直接选Qt 6.5 LTS或更新的LTS版本比较好；如果是要接手老项目，那么就得对齐项目原本的Qt版本，这点比“选最新”更重要。

还有一个容易忽略的点：Qt安装包分为开源版（Open Source）和商业版。我们一般用开源版就够了，只要遵守LGPL/GPL相关许可约定即可，学习、个人项目、多数内部项目都走这条路。商业版会多出一些专有模块，但对普通开发者来说性价比不划算，也比较难拿到离线安装包。

1.2 一次性装齐的依赖清单

Linux下Qt不是“装完就能用”的，它要依赖系统中的一堆开发库。很多人就是卡在这一步：Qt装好了，结果一运行就报Failed to load platform plugin xcb，根源往往是系统缺少libxcb相关库。

我的做法是，在装Qt之前，先把编译工具链和基础依赖一次性装齐：

sudo apt update sudo apt install build-essential cmake ninja-build gdb sudo apt install libgl1-mesa-dev libfontconfig1-dev libdbus-1-dev libfreetype6-dev \ libx11-dev libxkbcommon-dev libxcb-*-dev libxcb-xinerama0 libxcb-cursor0

这里每个包其实都有明确用途：build-essential提供gcc/g++和make，是编译C++代码的基础；libgl1-mesa-dev是OpenGL的开发头文件，Qt的widget程序和很多绘图功能都依赖它；libxcb系列是用来跟X11窗口系统通信的插件依赖，Qt在X11里运行动态加载libqxcb.so时需要这些库；libdbus-1、libfontconfig则解决桌面总线和字体渲染问题。

注意：不同Qt版本对依赖的敏感程度不一样，Qt 5.15相对宽松，Qt 6对xcb相关库更“挑剔”。安装完缺什么，后面报错再补，但上面这组基本上是“不会错”的最小集。

1.3 Qt Creator、Qt库和编译工具链，它们仨的关系

很多初次接触的人搞不清：我装的到底是个啥？这里用一个比喻：Qt库是“发动机”，它提供QWidget、QML、网络、数据库这些功能模块；Qt Creator是“驾驶舱”，负责写代码、看界面、断点调试；而gcc/g++、CMake、ninja这些编译链工具，是“传动装置”，负责把源码变成机器能跑的可执行文件。三者缺一不可。

所以搭建环境时，眼光不能只盯着“Qt装没装”这一个软件，而要看成一套工具链。这套工具链里的核心成员包括：

编译器：gcc/g++，在老一些的架构上还有clang可选；
构建工具：qmake（Qt自带）或CMake（通用跨平台构建）；
调试器：gdb，配合Qt Creator左边的调试点按钮使用；
版本控制：git，虽然不是必须，但几乎每个项目都要用。

后面我们在Qt Creator里配置“套件”（Kits），就是把上面这些关联起来。Kits里每一项对应一个具体工具版本，只有当编译器和Qt版本都正常识别，项目才能顺利编译。

2. 新装系统的完整搭建实录：从零开始装环境

2.1 系统依赖与编译工具链安装

接着1.2的清单继续。我实际操作时，通常先跑一遍update，再执行install。这个过程一般五分钟到十分钟，取决于网速和源的质量。

装完后验证三个关键工具：

gcc --version cmake --version gdb --version

只要都能打印出版本号，就说明工具链没问题。注意这里的gdb版本跟Qt Creator需要匹配，过低的老版本会出现调试异常，比如断点无效、变量窗口空白，这时候升级gdb即可。

2.2 下载并执行Qt在线安装器

自己去Qt官网下载在线安装器。这一步唯一要留意的是选择和你发行版对应的安装器（Linux x64），下载回来是一个.run文件。它不是一个完整Qt包，而是一个下载器，后面组件选择都在里面完成。

给执行权限并运行：

chmod +x qt-unified-linux-x64-5.0.0-online.run ./qt-unified-linux-x64-5.0.0-online.run

运行后会要求登录Qt账号，没有就花两分钟注册一个，开源版登录不收费。进来之后先是不用动的“欢迎”页，然后会进入组件选择界面。

组件这块我有固定的取舍习惯。既然做桌面应用，必须勾选：

Qt 6.5.x -> Desktop gcc 64-bit：这是核心运行库和开发头文件；
Qt 6.5.x -> Sources：源码包，调试看堆栈、检索底层实现时很有用；
Developer and Designer Tools -> Qt Creator：IDE本体；
Developer and Designer Tools -> CMake、Ninja：如果2.1已经系统装过，可以交给系统版本，没有的话也顺手勾上。

组件选择时默认会附带Qt Debugger等工具，这部分保持默认即可。不需要刻意勾选Android、iOS或嵌入式组件，按需再加，免得安装包庞大还容易踩依赖坑。

安装路径我习惯放在家目录下的Qt目录，比如/root/Qt/6.5.3/gcc_64。理论上说，路径里包含的字符越简单越好，避免带空格或中文，否则后面有些脚本处理起来会多出不必要的引号问题。

安装完成之后，可以看一眼Qt目录结构：

ls ~/Qt/6.5.3/gcc_64/bin

里面能看到qmake、qml、moc等工具，这些就是和Qt深度绑定的命令行工具了。

2.3 环境变量配置：为什么必须配，怎样配最省心

Qt安装完之后，直接启动Qt Creator是能进的，但命令行里用qmake或Qt相关工具还是会找不到。原因很简单：可执行文件目录没有被shell纳入PATH环境变量里。Windows下装完软件也经常手动加PATH，Linux下同理。

我建议把下面内容追加到~/.bashrc（如果你的shell是zsh，就改~/.zshrc）：

export PATH="$HOME/Qt/6.5.3/gcc_64/bin:$PATH"

保存后执行：

source ~/.bashrc qmake --version

能输出版本信息就说明环境变量生效了。这里有一个需要讲究的地方：编译出来的Qt程序，运行动态链接qt库时，默认会去系统库目录和rpath里找库，为了稳妥，很多人会把Qt的lib目录也加进LD_LIBRARY_PATH。我的经验是：命令行手动运行时如果需要再加，不推荐在全局环境里长期挂着这个变量，因为系统里可能有多个Qt版本或别的软件，乱挂LD_LIBRARY_PATH容易引发“库冲突”这种更隐蔽的问题。

Qt Creator之所以打开就能识别Qt版本，不是靠系统环境变量，而是靠它自己的套件配置，这会告诉Creator：qmake在哪里、Qt库在哪、编译器用哪个。我们在下一节配置。

2.4 在Qt Creator里完成第一套开发套件（Kits）配置

启动Qt Creator后，菜单进入Tools -> Options（在较新版本叫Edit -> Preferences）-> Kits。

Qt Versions选项卡：点击Add，选中qmake路径，比如/root/Qt/6.5.3/gcc_64/bin/qmake。如果Qt库安装在系统默认位置，它也会自动扫描到。
Compilers选项卡：确认C++编译器是g++，对应路径一般是/usr/bin/g++。如果列表是空的，点Add选择编译器。
Debuggers选项卡：确认gdb路径，对应/usr/bin/gdb。
CMake选项卡：确认CMake路径，刚才装了cmake就能识别。

完成之后，回到Kits页面，会看到一条记录，名字类似Desktop Qt 6.5.3 GCC 64bit，标识包括Qt version、C++ compiler、CMake、Debugger都被填上了。新版的Qt Creator其实会自动检测大部分工具，只要系统里装了基本都能识别到，我们要做的主要工作是人工核对版本是否正确——特别是有多个gcc版本时，别认错。

这一步做完，环境搭建就基本收官了，可以进入真正的“从零到跑到第一个窗口”。

3. 第一个测试工程：基线验证与构建流程

3.1 用Qt Creator新建Widgets工程

打开Creator，File -> New Project -> Application -> Qt Widgets Application，然后按向导填写：

项目名称：TestApp
创建路径：比如~/workspace/qt-test
构建系统：这里我建议选CMake或qmake都可以，Qt Creator默认对qmake支持也成熟；但考虑到新项目趋势，选CMake更通用。
基类：QMainWindow，类名MainWindow，勾选“Generate form”（生成.ui界面文件）。

完成后点左下角的构建按钮（绿色小锤子）。第一次构建会跑CMake或qmake两步，之后每次改动源码，它只重新编译变化的文件。构建输出窗口最终出现“Build finished”之类提示，再点右侧绿色箭头运行，就能看到一个空白窗口弹出，标题是TestApp。

这一步看起来简单，但它是整条工具链的“全网通电测试”：编译器、链接器、Qt库、Creator插件、X11显示、gdb调试注册，全部被验证了一遍。窗口能出来，环境基本就是好的。

熟悉以后，你也可以直接命令行创建工程目录和pro文件来建项目，这个留到3.2细说。

3.2 命令行方式编译：验证环境变量的正确姿势

图形界面能跑不算数，因为Creator内部会自己维护环境。为了确认命令行环境变量没问题，我习惯手写一个最小程序再跑一遍。

假设在~/qtcmd目录下创建main.cpp：

#include <QApplication> #include <QLabel> int main(int argc, char *argv[]) { QApplication app(argc, argv); QLabel label("Hello, Qt on Linux"); label.show(); return app.exec(); }

接着生成工程文件。你可以直接自己写一个test.pro：

QT += widgets SOURCES += main.cpp TARGET = qtcmd

然后按顺序执行：

mkdir build && cd build qmake ../test.pro make -j$(nproc) ./qtcmd

窗口能弹出，说明qmake能拿到正确的Qt版本、编译器和系统库。如果在命令行跑出现error while loading shared libraries，先确认是否缺2.3的LD_LIBRARY_PATH设置，或者直接install到系统。这个测试的价值在于：它把“Qt Creator能用”和“工具链能用”区分开，很多环境问题恰恰只在命令行暴露。

3.3 阴影构建、目录选择和Debug/Release的选择

构建配置里有两个概念值得一说。

一个是“阴影构建”（Shadow Build）。默认情况下，Qt Creator会在工程目录的兄弟目录生成一个build-XXX子目录，比如build-TestApp-Desktop_Qt_6_5_3-Debug，源码目录里不会掉入生成的.o和可执行文件。这个设计对保持源码目录干净非常有用，如果用git，就不会有一堆构建产物跑进提交列表；同时想切不同构建模式，比如Debug和Release，也互不干扰。我建议无论用Creator还是命令行，都保持这种“源码目录与构建目录分离”的目录约定。

另一个是Debug/Release的区分。Debug模式会带上调试符号，方便断点和回溯，运行稍慢；Release则优化性能，体积和启动速度更友好。开发前期一直用Debug；要交付、测试性能时再切Release。两个模式都要保留，不要图省事只在Release下开发，否则出了问题没法及时断点排查。

4. Linux下QT开发环境最高频的3个坑

4.1 窗口弹不出来：xcb插件加载失败

这是我见过最多的报错。现象是运行Qt程序后终端输出类似：

qt.qpa.plugin: Could not load the Qt platform plugin "xcb" in "" even though it was found.

然后窗口就是不出现。原因通常是运行Qt程序时，QPA（Qt Platform Abstraction，Qt的跨平台抽象层）要加载X11平台的xcb插件，而这个插件在运行时要动态链接系统里的X11相关库。系统缺了其中某个库，插件加载就会失败。

解决思路不是去“修复”Qt安装包，而是补齐系统依赖。常见的缺失库是libxcb-xinerama0和libxcb-cursor0，直接装上：

sudo apt install libxcb-xinerama0 libxcb-cursor0

如果还不行，可以用ldd查看xcb插件本身依赖哪些库缺失：

ldd ~/Qt/6.5.3/gcc_64/plugins/platforms/libqxcb.so | grep "not found"

每出现一个not found，就在apt里搜对应的libxcb-*包名装齐。这里有个经验：与其一个个试，不如把整个xcb相关包一次安装，省时间。

注意：网上一搜会有人让设置QT_QPA_PLATFORM=offscreen来绕过报错。这只适合无图形界面的服务器环境下截图、跑自动化测试，窗口不会真正显示。桌面开发时用这招属于“治标不治本”，界面照样出不来，别被带偏。

4.2 界面中文变成方块

表现是程序能跑，但窗口里有中文的地方全是方块“口口口”。这是Linux系统缺中文字体的典型表现。Qt不自带字体，它靠fontconfig机制去系统里找字体，系统里面没有支持中文的字体，就只能用替换字体，结果就是方块。

解决：安装一个中文字体包：

sudo apt install fonts-wqy-zenhei fonts-wqy-microhei fc-cache -fv

fc-cache是强制刷新字体缓存，不刷新有时候要重启程序才生效。如果项目里自定义了字体，就把字体文件放进/usr/share/fonts对应目录，同样跑一遍fc-cache即可。

顺带一提：源码文件里的中文注释乱码，多半是编码问题，统一用UTF-8保存就没问题。

4.3 Qt Creator里的Kit是红色/黄色警告

打开Creator的Kit列表，有时会看到类似“Compiler不可用”或“Qt version not found”的警告。这种情况经常发生在系统里存在多个gcc版本、或者Qt安装目录被移动过的情况下。

排查顺序我一般这样来：

确认gcc/g++是真的装了：gcc --version，没有就补build-essential；
确认qmake路径没失效：在Kit列表的Qt Versions里点开，看qmake路径是否存在；如果目录移动过，重新指定路径；
重新运行一次自动检测，很多情况下会自动修复；
如果多版本共存导致识别错乱，把不用版本从列表里Remove掉，减少干扰。

这层的核心原则是：Kits记录的是“工具的具体路径”，系统里工具一变、路径一变，就要手动更新。养成“先看路径是否有效，再看版本是否匹配”的顺序，排查速度会快不少。

4.4 多版本Qt切换混乱

有的项目用Qt 5.15，有的用Qt 6.5，一台机器装两套很正常。麻烦了，命令行qmake指向了A版本，Creator里却用B版本，编译出的程序行为不一致。

我的建议是：命令行工作尽量依赖创建脚本指定qmake完整路径，例如/root/Qt/5.15.2/gcc_64/bin/qmake，而不是只敲一个qmake；Qt Creator里每个Kit配一套固定版本，打开对应项目时切换Kit即可，Kit本身就是版本管理的单位，不用刻意去动全局PATH。这样两套版本共存既独立又清晰。

5. 从环境搭建走向项目实战的几点经验

5.1 依赖管理习惯

开发到中期，最难受的画面就是：换一台机器，代码clone下来，编译却报缺这个缺那个。原因是系统依赖没记录清楚。我一般会在项目仓库里存一个README或脚本文件，把所有apt依赖列表写进去，比如INSTALL_DEPS.md或scripts/install_deps.sh。这样不管是自己在另一台电脑配置，还是队友入职搭环境，都能一条命令恢复，省去反复猜依赖的过程。

另一个建议：能不往系统/usr/lib里手动拷贝Qt库，就不要拷。Qt库跟着Qt安装目录走，编译时用相对稳定的前缀，多平台适配时用CMake的安装逻辑处理，比硬塞到系统路径干净得多。

5.2 版本升级迁移

Qt跨小版本升级通常直接安装新版就行，工程打开后Creator一般会自动匹配。但跨大版本，比如Qt 5到Qt 6，就要留意几个行为差异：

QString::fromStdString、QRegExp等旧接口的迁移；
QML里旧的import模块写法变化；
High-DPI处理从以前手动设置变为默认启用。

这些不是环境的错，是代码层面的适配。环境搭建时不必为此焦虑，遇到了按编译报错逐个解决即可。

5.3 关于交叉编译的简短备忘

有一部分人搭Linux下Qt环境是为了嵌入式开发，比如在Linux主机上编译ARM板子跑的程序。这块我建议明确一个前提：先在本机把桌面Qt环境跑透，再碰交叉编译。交叉编译本身就涉及toolchain、sysroot和Qt库针对目标平台重新编译三层叠加的复杂度，如果再没有一个“能跑通的基础环境”做参照，出错后几乎没法判断问题出在哪一层。

入门思路可以简化为三步：准备目标板的交叉编译工具链；为目标平台编译Qt库（或直接用板子厂商提供的Qt SDK）；在Qt Creator里新增一个自定义Kit，把交叉工具链、目标平台的qmake和sysroot指定清楚。编译出的程序不是在本机跑，而是复制到目标板执行。这一步水比较深，后续有机会单独写一篇。