Qt 在 Linux 和 Windows 上的安装配置与跨平台开发全攻略

Qt 是一套成熟的跨平台 C++ 图形界面开发框架，很多桌面软件、工业软件、嵌入式界面都用它写。很多人第一次接触时会纠结：Windows 下装起来顺手，Linux 下却一堆依赖；写完代码后两边编译结果不一样，甚至路径分隔符都踩坑。今天这篇就围绕 qt linux windows 这几个关键词，把从零安装、环境配置、差异处理到实际项目落地，一步步讲清楚，适合电脑小白跟着做，也给进阶用户留了命令行和优化细节。

一、先搞清楚 Qt 能干什么

Qt 最大的卖点就是“一次编写，多处编译”。同一套源码，在 Windows 上用 MSVC 或 MinGW 编译，在 Linux 上用 GCC 编译，界面和逻辑基本保持一致。它自带信号槽机制、丰富的控件、网络模块、数据库模块，还支持 QML 做现代化界面。

对新手来说，记住三件事就够：

开发工具推荐 Qt Creator，官方集成开发环境，装好就能写代码。
版本选择：目前稳定主流是 Qt 5.15 LTS 或 Qt 6.x。新手建议先从 5.15 入手，资料多、坑少。
许可证：个人学习用开源版（LGPL/GPL）完全够用，商业闭源项目再考虑商业授权。

二、Windows 上安装 Qt（最详细步骤）

Windows 用户通常从官网下载在线安装器，过程直观。

打开浏览器，搜索 “Qt 官网下载”，进入下载页，选择 “Qt Online Installer”。下载后运行（需要联网）。
登录账号。没有就免费注册一个 Qt 账号，不然无法继续。
选择安装路径，建议不要装到 C 盘根目录，可以选 D:\Qt。路径里别带中文和空格。
组件选择很关键：
- Qt 版本勾选 5.15.2 或 6.5 系列。
- 编译器：Windows 上推荐勾选 “MSVC 2019 64-bit” 和 “MinGW 8.1.0 64-bit”。如果你电脑已经装了 Visual Studio，优先用 MSVC，生成的程序体积小、性能好。
- 工具里勾选 Qt Creator、CMake、Ninja。
- 源码和文档可以先不勾，省空间，后面需要再补。
安装过程可能要半小时到一小时，耐心等待。装完后打开 Qt Creator。
配置环境变量（可选但推荐）：
- 右键“此电脑”→属性→高级系统设置→环境变量。
- 在系统变量 Path 里新增：D:\Qt\5.15.2\msvc2019_64\bin（按你实际路径改）。
- 新建变量 QTDIR，值为 D:\Qt\5.15.2\msvc2019_64。
验证是否成功：
- 打开 Qt Creator，新建项目 → Application → Qt Widgets Application。
- 一路下一步，选好 Kit（编译套件）。
- 点运行，如果弹出一个空窗口，说明安装成功。

常见坑：安装器提示网络错误，多半是被墙了。解决办法是挂代理，或者改用国内镜像（清华、中科大等 Qt 镜像站提供离线包）。

三、Linux 上安装 Qt（以 Ubuntu 为例，CentOS 类似）

Linux 下安装方式更多，apt 源简单，但版本偏旧；官方安装器版本新；源码编译最灵活。新手优先用官方安装器，和 Windows 体验接近。

方法一：官方在线安装器（推荐）

下载 Linux 版 Online Installer（.run 文件）。

终端进入下载目录，执行：

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

后续步骤和 Windows 几乎一样：登录、选路径（建议 ~/Qt）、勾选 GCC 64-bit 编译器、Qt Creator。

装完后可能需要安装依赖：

sudo apt update
sudo apt install build-essential libgl1-mesa-dev libxcb-xinerama0

打开 Qt Creator：在终端输入 ~/Qt/Tools/QtCreator/bin/qtcreator，或者把路径加入 PATH。

方法二：系统包管理器（快速尝鲜）

Ubuntu/Debian：

sudo apt install qtcreator qtbase5-dev qt5-qmake

CentOS/RHEL：

sudo yum install qt5-qtbase-devel qt-creator

这种方式装出来的版本较旧，适合练手，不适合正式开发。

方法三：源码编译（进阶）

适合需要自定义模块或最新补丁的用户。下载源码后：

./configure -prefix /opt/qt5 -opensource -confirm-license
make -j$(nproc)
sudo make install

编译时间长，对机器性能要求高，小白先跳过。

验证方法同样是新建 Widgets 项目并运行。Linux 下如果出现 “could not find platform plugin xcb”，就执行上面的 libxcb 依赖安装命令。

四、Windows 与 Linux 开发差异及避坑

同一个 Qt 项目在两边跑，主要差异集中在这几处：

路径分隔符
Windows 用反斜杠 \，Linux 用正斜杠 /。Qt 自己提供了 QDir::separator() 和 QDir::toNativeSeparators()，写代码时永远用这些函数，不要硬编码。
文件系统大小写
Windows 不区分大小写，Linux 严格区分。资源文件、图片路径一定保持一致大小写，否则 Linux 下加载失败。

编译器与 ABI
Windows 常用 MSVC，Linux 用 GCC/Clang。跨平台项目建议统一用 CMake 管理，而不是 qmake。CMakeLists.txt 示例：

cmake_minimum_required(VERSION 3.16)
project(MyApp)
set(CMAKE_CXX_STANDARD 17)
find_package(Qt5 REQUIRED COMPONENTS Widgets)
add_executable(MyApp main.cpp)
target_link_libraries(MyApp Qt5::Widgets)

界面字体和 DPI
Windows 高分屏缩放默认比较完善，Linux 某些桌面环境（GNOME/KDE）需要手动设置 QT_SCALE_FACTOR=1.5 环境变量，或者在代码里调用 QApplication::setAttribute(Qt::AA_EnableHighDpiScaling)。
打包发布
- Windows：用 windeployqt 工具自动拷贝依赖 dll。
  命令：windeployqt MyApp.exe
- Linux：用 linuxdeployqt 或自己写 AppImage。依赖库多，注意 libstdc++、libxcb 等。

五、手把手做一个跨平台小项目

目标：写一个窗口，点击按钮弹出“Hello from Qt”。

打开 Qt Creator，新建 Qt Widgets Application，项目名 HelloCross。

主窗口代码（mainwindow.cpp）：

#include "mainwindow.h"
#include <QPushButton>
#include <QMessageBox>
#include <QVBoxLayout>

MainWindow::MainWindow(QWidget *parent)
   : QMainWindow(parent)
{
   QWidget *central = new QWidget(this);
   setCentralWidget(central);
   QVBoxLayout *layout = new QVBoxLayout(central);

   QPushButton *btn = new QPushButton("点我", this);
   layout->addWidget(btn);

   connect(btn, &QPushButton::clicked, this, [](){
       QMessageBox::information(nullptr, "提示", "Hello from Qt on Linux and Windows!");
   });
}

分别在 Windows 和 Linux 的 Kit 下编译运行。两边界面几乎一致。
如果要做成可执行文件：
- Windows：构建 → 发布，再用 windeployqt。
- Linux：构建后，用 ldd HelloCross 查看依赖，打包进 AppImage 或 deb。

六、常见问题快速排查

编译报错 “No Qt platform plugin”：检查 plugins/platforms 目录是否完整，环境变量 QT_QPA_PLATFORM_PLUGIN_PATH 是否设置。
中文乱码：源文件统一 UTF-8 无 BOM，代码里加 QTextCodec::setCodecForLocale(QTextCodec::codecForName("UTF-8"));（Qt5）。
信号槽连接失败：Qt5 用函数指针语法 connect(btn, &QPushButton::clicked, ...)，比字符串宏更安全。
Linux 下权限问题：可执行文件记得 chmod +x，安装路径不要放在需要 root 的目录。
版本冲突：系统自带 Qt 和官方安装的 Qt 混用，导致库加载错误。解决办法是用 qtchooser 或明确指定 qmake 路径。

七、性能与进阶优化建议

发布时关闭调试信息，选择 Release 模式，体积能小一半。
静态编译可以减少依赖，但体积会变大，适合嵌入式。
用 Qt Quick / QML 做界面，比传统 Widgets 更流畅，尤其在 Linux 高分屏上。
多线程别直接操作界面，用信号槽把结果传回主线程。
定期用 Qt Creator 的分析工具看内存泄漏和性能瓶颈。

把 Windows 和 Linux 两套环境都搭好后，你会发现 Qt 真正省心的地方：改一处代码，两边同步验证。遇到具体报错，把完整错误信息、Qt 版本、系统版本记下来，基本都能快速定位。按照上面的步骤，从安装到跑通第一个程序，新手半天内就能搞定。后续做更复杂的网络、数据库、串口项目，也是同一套思路。