Qt5.1.1与MinGW 4.8环境搭建：从安装到Hello World的完整指南

简介《C Qt5 范例开发大全》中文版面向希望系统掌握 Qt5 框架的 C 开发者从零基础入门到有经验的程序员均可对照实践。内容以实例驱动覆盖开发环境搭建与 Hello World 起步、窗体基类与窗口大小位置背景色控制、无边框窗体移动及多窗体调用再到 QPushButton、QLabel、QLineEdit、QComboBox、QSpinBox、QListView、QTreeView、QTableView 等常用控件与 QHBoxLayout、QGridLayout 布局管理并延伸至 QPainter 图形绘制和 QSslSocket、QCryptographicHash 加解密应用目录模块划分清晰便于按章节检索查阅。资源包共 1 个 PDF 文件大小约 2.83MB轻量便携适合随时翻阅与对照编码。目前已有 257 人学习可作为 Qt5 控件用法速查与范例参考的实用手册。1. 从一台干净机器开始Qt5.1.1 与 MinGW 4.8 的安装现场上周帮一位做嵌入式的朋友配机器他拿到一份 Qt5 范例代码双击.pro文件Qt Creator 弹窗报错“No valid kits found”折腾一下午没跑起来。这不是代码问题是环境没搭对。Qt5 范例开发这类资料价值全在“能编译、能运行、能看到效果”环境差一个组件后面几百个例子全是死代码。这篇笔记按我自己的装机习惯走一遍Windows 下装 Qt5.1.1 离线包MinGW 4.8 32 位配环境变量跑通 Hello World再把后面控件、文件、网络、打包各章依赖的模块补齐。适合刚拿到这份范例、准备照着敲一遍的开发者也适合想复现老版本 Qt5 项目、被新版 Qt6 迁移问题卡住的人。2. 装前定版Qt5.1.1 离线包与 MinGW 4.8 的取舍2.1 为什么锁定 Qt5.1.1 而不是追新这份范例的代码基线是 Qt5.1.1配套编译器是 MinGW 4.832 位OpenGL 版本。很多人第一反应是去装最新的 Qt5.15 或 Qt6结果一编译就翻车QTextCodec在 Qt6 里被移出核心模块QRegExp被QRegularExpression取代范例里大量setStyleSheet(background:red)这类写法虽然还能用但信号槽的旧式SIGNAL/SLOT宏在新版本里编译告警一堆。更关键的是范例第十三章讲QByteArray加密、AES、MD5第十四章讲 FilePacker 和 Inno Setup 打包这些示例对 Qt 版本敏感跨大版本复现成本极高。我一般会跟人说学范例版本跟着书走做新项目版本跟着需求走。这两件事别混。Qt5.1.1 的离线安装包文件名是qt-windows-opensource-5.1.1-mingw48_opengl-x86-offline.exe体积约 666 MB自带 Qt Creator、MinGW 4.8 编译器和 Qt 库装完即用不需要单独配编译器。这是它最大的好处——离线包把工具链捆在一起省掉“装完 IDE 发现没有编译器”这种低级坑。2.2 环境对照表装之前先核对机器项目要求说明操作系统Windows 7 / 8 / 10 32 位或 64 位64 位系统可跑 32 位 Qt反之不行磁盘空间至少 3 GB 空闲安装包 666 MB装完约 2 GB内存2 GB 以上编译大项目时 4 GB 更稳安装路径纯英文、无空格例如D:\Qt\Qt5.1.1别放“桌面”“我的文档”用户权限管理员写环境变量、装组件需要杀毒软件临时关闭或加白名单MinGW 的make.exe常被误杀路径带中文或空格是血泪经验里排第一的坑。Qt 的 qmake 在生成 Makefile 时对空格处理不干净路径里有空格编译到一半报No such file or directory你还以为是代码问题。我习惯统一装到D:\Qt\Qt5.1.1后面所有命令都按这个路径写你换成自己的盘符即可。2.3 下载与校验别拿到半截包就装官方下载页给的是离线安装器下载完先看文件大小666 MB 左右算正常。如果只有几十 MB多半是下载中断或拿到的是在线安装器。校验方式很简单右键属性看大小或者用 PowerShell 算一下哈希# 计算安装包 SHA256和官方页面公布的值比对 Get-FileHash .\qt-windows-opensource-5.1.1-mingw48_opengl-x86-offline.exe -Algorithm SHA256这一步不是形式主义。离线包一旦损坏安装过程可能不报错但装完 Qt Creator 打不开或者编译时缺libstdc-6.dll。我遇到过两次都是重新下载解决。校验通过再双击安装别急着点下一步。3. 安装与首次配置从安装向导到 Hello World 跑通3.1 安装向导里真正要留意的三个页面双击安装包后欢迎页、许可协议页直接下一步。真正要停一下的是这三个地方第一安装目录页。默认路径可能是C:\Qt\Qt5.1.1如果你 C 盘紧张改成D:\Qt\Qt5.1.1。注意这里填的是 Qt 根目录安装器会自动在其下建5.1.1\mingw48_32子目录。第二组件选择页。离线包默认勾选 Qt 5.1.1 的 MinGW 4.8 32 位版本和 Qt Creator。保持默认即可不要额外勾选源码包Sources除非你要调试 Qt 内部实现那会多占 1 GB 多空间对跑范例没帮助。第三开始菜单页。默认就行。点安装后等几分钟看到完成页说明主程序装好了。装完先别急着建项目打开D:\Qt\Qt5.1.1\5.1.1\mingw48_32\bin看一眼里面应该有qmake.exe、mingw32-make.exe、Qt5Core.dll等文件。如果这个目录是空的说明组件没装全回安装器补装。3.2 环境变量Path 里加一条少走一半弯路范例第一章明确要求配环境变量目的是让系统在任何目录下都能找到 Qt 的 DLL 和工具。操作路径右键“此电脑” → 属性 → 高级系统设置 → 环境变量 → 系统变量里找到Path→ 编辑 → 新建一行填入D:\Qt\Qt5.1.1\5.1.1\mingw48_32\bin注意两点一是路径按你实际安装位置改二是 Windows 10 以后的编辑器是列表式直接新建条目不需要手动加分号老系统是字符串式条目之间用分号隔开别把分号加在末尾。配完关掉所有已打开的终端和 Qt Creator重新打开才生效。验证方式# 打开 cmd 或 PowerShell执行 qmake -v正常输出类似QMake version 3.0和Using Qt version 5.1.1 in D:/Qt/Qt5.1.1/5.1.1/mingw48_32/lib。如果提示“不是内部或外部命令”说明 Path 没生效检查路径拼写和是否重启了终端。3.3 新建 Hello World基类选择与代码落点打开 Qt Creator文件 → 新建文件或项目 → 应用程序 → Qt Gui 应用 → 选择。项目名填QtOne路径选一个纯英文目录比如D:\QtCode。基类选择页会出现三个选项QMainWindow、QWidget、QDialog。范例用的是QMainWindow因为它带菜单栏、工具栏、状态栏后面第二章窗体应用、第三章控件应用都基于它展开。选QMainWindow类名保持MainWindow继续下一步直到完成。在mainwindow.cpp里写显示文字的代码#include mainwindow.h #include ui_mainwindow.h #include QLabel // 引用标签控件类 MainWindow::MainWindow(QWidget *parent) : QMainWindow(parent), ui(new Ui::MainWindow) { ui-setupUi(this); QLabel *label new QLabel(this); // 创建标签父对象为当前窗体 label-setText(Hello World); // 设置显示内容 label-setGeometry(QRect(50, 50, 200, 30)); // x50, y50, 宽200, 高30 } MainWindow::~MainWindow() { delete ui; }setGeometry四个参数依次是 X 坐标、Y 坐标、控件宽度、控件高度坐标原点是窗体左上角。new QLabel(this)里的this很关键它把标签挂到窗体对象树上窗体销毁时标签自动释放不需要手动delete。这就是 Qt 的对象树内存管理范例里反复用到新手容易漏写this导致内存泄漏。点左下角绿色三角编译运行。第一次编译会慢一些MinGW 要生成中间文件。如果弹出窗口显示 Hello World环境就算通了。如果报错cannot find -lQt5Core回看 3.2 的 Path 配置如果报错No valid kits found进 工具 → 选项 → 构建和运行检查 Kit 里的编译器是否指向D:\Qt\Qt5.1.1\Tools\mingw48_32\bin\g.exe。3.4 项目目录结构debug 与 release 别搞混编译成功后项目目录下会多出debug和release两个文件夹具体生成哪个取决于 Qt Creator 左下角的构建配置Debug 或 Release。debug里的 exe 带调试符号体积大、运行慢适合断点调试release里的 exe 经过优化适合分发。范例代码在两种模式下都能跑但第十四章打包部署时要用 release 版本别拿 debug 的 exe 去打包否则用户机器上缺调试 DLL 直接闪退。.pro文件是 qmake 的工程描述里面QT core gui表示链接核心和界面模块。后面章节用到网络、数据库、多媒体时要在这里追加QT network sql multimedia否则编译报头文件找不到。这是 Qt5 范例开发里最常见的“代码没错但编不过”的原因之一。4. 按范例章节补模块控件、文件、网络、数据库的依赖配置4.1 控件与布局章节不需要额外模块但要注意头文件第三章控件应用覆盖QPushButton、QLabel、QLineEdit、QComboBox、QListView、QTreeView、QTableView以及QHBoxLayout、QGridLayout。这些类都在QtWidgets模块里Qt5 默认的QT core gui在 Qt5 中已自动包含 widgets所以不用改.pro。但每个类要单独 include比如用表格控件#include QTableView #include QStandardItemModel // 表格数据模型 QTableView *table new QTableView(this); QStandardItemModel *model new QStandardItemModel(3, 2, this); // 3行2列 model-setHeaderData(0, Qt::Horizontal, 姓名); model-setHeaderData(1, Qt::Horizontal, 年龄); model-setItem(0, 0, new QStandardItem(张三)); table-setModel(model); table-setGeometry(20, 20, 300, 200);QStandardItemModel构造参数是行数、列数、父对象。setHeaderData第一个参数是列索引第二个是方向水平或垂直第三个是显示文本。setItem的行列索引从 0 开始。这套模型/视图结构是 Qt 控件应用的核心范例里QListView、QTreeView也是同样的套路换模型类即可。布局管理器不需要手动算坐标把控件塞进布局布局再挂到窗体上QHBoxLayout *hLayout new QHBoxLayout; hLayout-addWidget(new QPushButton(确定)); hLayout-addWidget(new QPushButton(取消)); QWidget *central new QWidget(this); central-setLayout(hLayout); setCentralWidget(central); // QMainWindow 必须设 centralWidgetQMainWindow不能直接setLayout必须通过setCentralWidget挂一个中心部件。这是第二章窗体应用里容易翻车的点直接setLayout会编译报错或运行无效果。4.2 文件操作与 XMLQFile、QTextStream、QDomDocument 的用法第五章文件操作涉及创建文件夹、写文件、改内容、删文件、改文件名、INI 读写、XML 创建与读取。这些类分布在QtCore模块默认已链接。写文件的标准写法#include QFile #include QTextStream QFile file(D:/QtCode/test.txt); if (file.open(QIODevice::WriteOnly | QIODevice::Text)) { QTextStream out(file); out 第一行 \n 第二行; file.close(); }QIODevice::WriteOnly表示只写QIODevice::Text表示文本模式Windows 下会自动处理换行符转换。不加Text标志写入的\n在记事本里可能显示成一行。INI 文件用QSettings#include QSettings QSettings ini(D:/QtCode/config.ini, QSettings::IniFormat); ini.setValue(user/name, admin); ini.setValue(user/level, 3); ini.sync(); // 立即落盘QSettings的键用斜杠分组user/name在 INI 里对应[user]段下的name。sync()不是必须但范例里改完立即读的场景多加上更稳。XML 用QDomDocument需要QT xml这是少数要改.pro的章节QT core gui xml改完.pro后执行一次“构建 → 执行 qmake”再编译否则新模块不生效。4.3 网络与数据库模块追加与驱动检查第十一章网络开发用到QTcpSocket、QTcpServer、QUdpSocket、QSslSocket第十二章进程线程用到QThread、QRunnable第十章数据库用到QSqlDatabase、QSqlQuery。.pro里要追加QT core gui network sql网络部分范例有点对点聊天服务端/客户端、局域网广播、SMTP 发邮件。QTcpServer监听端口QTcpServer *server new QTcpServer(this); if (!server-listen(QHostAddress::Any, 8888)) { // 端口被占用或权限不足 } connect(server, QTcpServer::newConnection, this, MainWindow::onNewConnection);QHostAddress::Any表示监听所有网卡端口 8888 可改。listen返回 false 时用server-errorString()看原因常见是端口被占。数据库部分范例用 QODBC 连 Access、用 SQLite 做本地库。SQLite 驱动 Qt5 自带直接QSqlDatabase::addDatabase(QSQLITE)即可Access 需要系统装 ODBC 驱动且要QSqlDatabase::addDatabase(QODBC)后设置连接字符串。查可用驱动#include QSqlDatabase #include QDebug qDebug() QSqlDatabase::drivers();输出里没有QSQLITE说明 Qt 安装不完整回安装器补装没有QODBC是系统层面缺驱动和 Qt 无关。4.4 图形图像与多媒体QPainter 与 Phonon 的版本现实第六章图形图像操作全部基于QPainter在QtGui模块里Qt5 中绘图相关类归入QtGui默认链接。绘制文字、线条、椭圆、图片缩放、翻转、模糊、着色、阴影、透明都是QPainter的drawText、drawLine、drawEllipse、drawPixmap配合变换矩阵实现。一个最小绘制示例#include QPainter void MainWindow::paintEvent(QPaintEvent *event) { QPainter painter(this); painter.setPen(Qt::red); // 红色画笔 painter.drawLine(10, 10, 200, 10); // 从(10,10)到(200,10) painter.drawEllipse(50, 50, 100, 60); // 左上角(50,50)宽100高60 }paintEvent是窗体绘制事件所有QPainter绘图必须放在这里或paintEvent调用的函数里放在构造函数里画不出来。这是新手高频坑。第七章多媒体应用在 Qt5.1.1 时代用的是Phonon或QMediaPlayer。QMediaPlayer需要QT multimedia且依赖系统解码器Windows 上装个 K-Lite 或系统自带解码器才能播 mp4。范例里播放 Flash 动画的部分现在 Flash 已停止支持这一节跑不通是正常的跳过即可不影响其他章节。我一般会跟人说老范例里过时的章节知道它为什么过时比硬跑通更有价值。5. 避坑与排查Qt5.1.1 安装配置里最容易翻车的五件事5.1 编译报 “No valid kits found”现象打开.pro项目Qt Creator 提示没有可用 Kit构建按钮灰色。原因Qt Creator 没识别到编译器或 Qt 版本常见于先装 Qt Creator 后装 Qt 库或者安装时组件没勾全。解决工具 → 选项 → 构建和运行 → 编译器看 Auto-detected 下有没有 MinGW 4.8 的g.exe没有就手动添加路径指向D:\Qt\Qt5.1.1\Tools\mingw48_32\bin\g.exe。再到 Qt Versions 页确认qmake.exe路径是D:\Qt\Qt5.1.1\5.1.1\mingw48_32\bin\qmake.exe。最后在 Kits 页把编译器和 Qt 版本组合成一个 Kit点 Apply。5.2 运行 exe 弹窗缺 DLL现象Qt Creator 里能跑双击debug或release里的 exe 报“缺少 Qt5Core.dll”。原因exe 运行时按 Path 找 DLLQt Creator 内部自己设了库路径脱离 IDE 就找不到。解决确认 3.2 的 Path 已配且重启过终端或者用windeployqt把依赖拷到 exe 同目录windeployqt D:\QtCode\build-QtOne-Desktop_Qt_5_1_1_MinGW_32bit-Release\release\QtOne.exewindeployqt在mingw48_32\bin下它会自动分析 exe 依赖并复制对应 DLL 和插件目录。第十四章打包前必须走这一步否则用户机器上跑不起来。5.3 中文乱码源文件编码与运行编码不一致现象代码里写setText(你好)界面显示乱码。原因Qt5 默认按 UTF-8 解析源文件但 MinGW 在 Windows 下可能按 GBK 处理或者源文件本身存成了 GBK。解决Qt Creator 里 工具 → 选项 → 文本编辑器 → 行为确认默认编码是 UTF-8已有文件用“编辑 → 选择编码”另存为 UTF-8。代码里加一行#include QTextCodec QTextCodec::setCodecForLocale(QTextCodec::codecForName(UTF-8));放在main.cpp的QApplication a(argc, argv);之后。Qt5.1.1 还保留QTextCodecQt6 已移除这也是锁版本的原因之一。5.4 改完 .pro 不生效现象.pro里加了QT network编译仍报QTcpSocket: No such file or directory。原因qmake 生成的 Makefile 没更新编译器还在用旧配置。解决Qt Creator 菜单 构建 → 执行 qmake然后再构建。命令行下就是重新跑一次qmake再mingw32-make。我习惯改完.pro就顺手执行 qmake这个动作花两秒能省半小时排查。5.5 杀毒软件拦截 make.exe现象编译到链接阶段突然失败报错指向make.exe或g.exe无法访问。原因部分杀毒软件把 MinGW 的编译工具误判为可疑程序实时防护直接隔离。解决把D:\Qt\Qt5.1.1\Tools\mingw48_32\bin整个目录加入杀毒软件白名单或者编译期间临时关闭实时防护。装完再恢复防护。这个坑隐蔽性强报错信息五花八门但根源就一个。6. 装完怎么验证用一份最小工程把工具链跑穿环境装没装好不看 Qt Creator 能不能打开看一份最小工程能不能从源码走到可执行文件再脱离 IDE 独立运行。我一般按下面四步走一遍全过才算收工。第一步命令行编译验证。不用 IDE纯命令行走 qmake make确认工具链本身没问题# 在项目目录下执行假设 .pro 文件名为 QtOne.pro qmake QtOne.pro mingw32-make -j4-j4表示四线程并行编译机器核少就写-j2或不加。这一步成功会在release或debug目录生成 exe。如果 qmake 报找不到回 3.2 查 Path如果 make 报错看报错行号对应的源文件。第二步独立运行验证。把生成的 exe 复制到一个空文件夹双击运行。如果弹窗缺 DLL说明依赖没拷全用 5.2 的windeployqt处理。这一步模拟的是用户拿到程序后的真实场景比在 IDE 里点运行严格得多。第三步模块覆盖验证。建一个测试工程.pro里写全QT core gui network sql xml multimedia代码里分别 includeQTcpSocket、QSqlDatabase、QDomDocument、QMediaPlayer编译通过说明各模块都装齐了。这一步能提前暴露“装的时候漏勾组件”的问题避免学到第十一章才发现网络模块没装。第四步范例抽样验证。从光盘或资源里挑三个不同章节的例子第二章的窗体大小控制、第五章的 INI 读写、第十章 SQLite 查询。三个都能编译运行说明控件、文件、数据库三条线都通了剩下的章节基本不会有大问题。验证项通过标准失败先查命令行编译生成 exe 无报错Path、qmake 路径独立运行双击 exe 正常显示windeployqt、DLL 缺失模块覆盖全模块 include 编译通过安装组件、.pro 配置范例抽样三个例子均能运行对应章节的模块依赖这套流程我每次配新机器都强制走一遍包括帮别人远程配环境也是让对方先跑这四步再开始看代码。有一次偷懒跳过第三步结果学到网络章节才发现安装时没勾 network 组件回头补装又得重配 Kit反而更费时间。从那以后我每次装完 Qt 都先把模块覆盖验证跑一遍再动范例代码。希望帮到你。本文还有配套的精品资源点击获取