简介这份资源是《PyQt6实战派》的配套代码包面向正在学习或准备上手PyQt6桌面应用开发的Python开发者尤其适合希望通过真实项目而非零散示例来掌握GUI编程的进阶学习者。包内共787个文件以188个py源码、393个png界面截图、99个pyc编译文件为主另含22个ui设计文件、10个qss样式表、5个qrc资源文件及json、ico、qrc等辅助素材压缩包约26.05MB覆盖窗口控件、事件处理、信号槽、布局管理、模型视图、异步编程与自定义控件等核心主题并配有可执行文件与批处理脚本便于直接运行验证。目前已有884人学习下载。通过这套代码读者可对照完整模块结构逐项调试理解界面与逻辑的分离方式积累样式美化、资源打包与项目部署的实操经验从而在真实项目中更高效地构建功能丰富、交互友好的桌面应用。1. 从一份配套代码说起PyQt6 桌面应用到底该怎么上手很多人第一次接触 PyQt6是被“配套代码”这四个字吸引的——拿到一份能跑的工程比啃三天文档管用。但真正跑起来才发现代码能启动不代表你能改能改不代表你能交付。PyQt6 实战派配套代码的价值不在于它写了多少行而在于它把信号槽、布局管理、多线程、资源打包这些散点串成了一条可复现的路径。这篇文章面向的是想用 PyQt6 做桌面工具、内部管理端、数据采集面板的开发者尤其是那些已经会写 Python 但一碰 GUI 就卡在“界面卡死”“打包报错”“信号连不上”的人。我会按“先跑通最小窗口 → 再拆模块 → 再处理线程和资源 → 最后避坑”的顺序把配套代码里最值得抄的部分讲透参数怎么设、坑在哪、为什么这么选都落到具体命令和代码块上。2. 把配套代码跑起来环境、入口与最小可运行窗口2.1 环境隔离与 PyQt6 安装的版本选择配套代码通常不会把依赖写死到某个小版本但 PyQt6 的安装方式直接决定后面打包会不会翻车。我一般会先建一个干净虚拟环境再装 PyQt6 和 pyqt6-tools如果需要 Designer。注意PyQt6 和 PyQt5 的 API 差异不小尤其是枚举类型全部改成了Qt.AlignmentFlag.AlignCenter这种作用域写法直接抄 PyQt5 代码会报AttributeError。# 创建虚拟环境避免污染系统 Python python -m venv venv_pyqt6 # 激活Windows 用 venv_pyqt6\Scripts\activatemacOS/Linux 用 source venv_pyqt6/bin/activate source venv_pyqt6/bin/activate # 安装 PyQt6 核心包不指定小版本让 pip 选当前稳定版 pip install PyQt6 # 如果需要 Qt Designer 做界面拖拽再装工具包 pip install pyqt6-tools # 验证安装打印版本和平台插件路径 python -c from PyQt6.QtCore import QT_VERSION_STR; print(QT_VERSION_STR)逻辑说明虚拟环境是为了把 PyQt6 的二进制依赖和系统里其他 Qt 程序隔开尤其是 Linux 上系统自带 Qt5 的情况混用会导致xcb插件加载失败。参数说明pip install PyQt6不写是常见做法因为 PyQt6 的次要版本更新通常兼容但如果你要打包给客户建议在requirements.txt里锁到PyQt66.6.*这种粒度避免 Qt 运行时行为漂移。验证命令只打印 Qt 版本不启动窗口适合在 CI 里做冒烟检查。2.2 入口文件与 QApplication 的最小骨架配套代码的入口通常是main.py里面最核心的是QApplication实例和事件循环。很多人把业务逻辑直接写在if __name__ __main__下面结果单元测试没法跑。我一般会把窗口类单独放一个文件入口只做三件事创建应用、实例化主窗口、进入事件循环。# main.py import sys from PyQt6.QtWidgets import QApplication from ui.main_window import MainWindow # 假设窗口类在 ui/main_window.py def main(): # 每个 Qt 应用有且只有一个 QApplication 实例 app QApplication(sys.argv) # 设置应用名影响任务管理器和部分系统对话框标题 app.setApplicationName(PyQt6实战派示例) window MainWindow() window.show() # 进入事件循环阻塞直到所有窗口关闭 sys.exit(app.exec()) if __name__ __main__: main()逻辑说明QApplication(sys.argv)必须在使用任何 QWidget 之前创建否则会直接崩溃。app.exec()返回的是退出码用sys.exit包一层能让脚本在命令行下正确返回状态。参数说明sys.argv传给 Qt 后Qt 会解析自己认识的参数比如-style不认识的会留在QApplication.arguments()里方便你做自定义命令行开关。注意app.setApplicationName不是必须的但在 Windows 上会影响任务管理器里的进程描述打包后尤其明显。2.3 用 .ui 文件还是纯代码写界面配套代码里经常两种方式混用简单窗口用纯代码复杂布局用 Designer 生成.ui再转.py。我的经验是如果界面控件超过 15 个或者需要频繁调整间距就用 Designer否则纯代码更可控。转换命令如下# 把 designer.ui 转成 ui_designer.py注意 -o 指定输出文件 pyqt6-tools designer # 先打开 Designer 画界面并保存为 designer.ui pyuic6 designer.ui -o ui_designer.py逻辑说明pyuic6是 pyqt6-tools 提供的转换器生成的.py文件里是一个Ui_Form类你需要在业务代码里继承它。参数说明-o指定输出路径不写会打印到 stdout。注意每次改完.ui都要重新转换所以建议把转换命令写进Makefile或build.py避免手动漏掉。另外生成的代码不要手动改否则下次转换会被覆盖。3. 信号槽与线程让界面不卡死的核心写法3.1 信号槽的三种连接方式与参数传递PyQt6 的信号槽是桌面应用里最容易“连不上”的地方。常见错误是信号定义在类里但没加pyqtSignal或者槽函数参数个数对不上。配套代码里一般用三种连接方式直接连、带 lambda 连、用partial连。直接连最简单但遇到循环变量会踩坑。from PyQt6.QtCore import pyqtSignal, QObject from PyQt6.QtWidgets import QPushButton, QVBoxLayout, QWidget class DemoWidget(QWidget): # 自定义信号参数是字符串 value_changed pyqtSignal(str) def __init__(self): super().__init__() layout QVBoxLayout(self) for i in range(3): btn QPushButton(f按钮{i}) # 错误写法lambda 里直接用 i最终都变成 2 # btn.clicked.connect(lambda: self.on_click(i)) # 正确写法用默认参数把当前 i 绑进去 btn.clicked.connect(lambda checked, idxi: self.on_click(idx)) layout.addWidget(btn) def on_click(self, idx): # 发射自定义信号传递字符串 self.value_changed.emit(f点击了按钮{idx})逻辑说明clicked信号带一个checked布尔参数所以 lambda 第一个参数必须留出来否则参数个数不匹配会报TypeError。用idxi把循环变量固定住是 Python 闭包的经典解法。参数说明pyqtSignal(str)定义在类级别不能放在__init__里。发射时用emit槽函数用connect注册。注意跨线程发射信号时Qt 默认用队列连接槽函数会在接收者所在线程执行这是后面线程安全的基础。3.2 QThread 与 moveToThread两种多线程方案的取舍界面卡死的根因通常是主线程里跑了耗时操作。PyQt6 里做多线程有两种主流方案继承QThread重写run或者用QObjectmoveToThread。配套代码里如果涉及网络请求或文件解析一般用后者因为信号槽跨线程更干净。from PyQt6.QtCore import QThread, QObject, pyqtSignal, pyqtSlot import time class Worker(QObject): # 定义进度和完成信号 progress pyqtSignal(int) finished pyqtSignal(str) pyqtSlot() def do_work(self): for i in range(1, 101): time.sleep(0.05) # 模拟耗时操作 self.progress.emit(i) self.finished.emit(任务完成) class Controller(QObject): def __init__(self): super().__init__() self.thread QThread() self.worker Worker() # 把 worker 移到子线程 self.worker.moveToThread(self.thread) # 线程启动时触发 do_work self.thread.started.connect(self.worker.do_work) # 完成后退出线程并清理 self.worker.finished.connect(self.thread.quit) self.worker.finished.connect(self.worker.deleteLater) self.thread.finished.connect(self.thread.deleteLater) def start(self): self.thread.start()逻辑说明moveToThread把 worker 的事件循环放到子线程所有槽函数都在子线程执行。thread.started信号连到do_work保证线程起来后才开始干活。参数说明deleteLater是 Qt 的对象延迟删除机制比直接del安全避免在信号发射过程中销毁对象。注意QThread实例本身留在主线程只有 worker 被移走。如果直接继承QThread并在run里写循环也能跑但信号槽的线程归属容易搞混新手更推荐moveToThread。3.3 线程间更新 UI 的正确姿势子线程里直接调label.setText()是经典翻车点Qt 会报QObject::setParent: Cannot set parent, new parent is in a different thread或者直接崩溃。正确做法是子线程发信号主线程的槽函数更新 UI。# 在主窗口里连接 worker 的 progress 信号到更新槽 class MainWindow(QWidget): def __init__(self): super().__init__() self.label QLabel(等待开始) self.controller Controller() # 跨线程信号默认队列连接槽在主线程执行 self.controller.worker.progress.connect(self.update_progress) self.controller.worker.finished.connect(self.on_finished) def update_progress(self, value): # 这个槽在主线程执行可以安全操作 UI self.label.setText(f进度{value}%) def on_finished(self, msg): self.label.setText(msg)逻辑说明progress信号在子线程发射但接收者MainWindow住在主线程Qt 自动用QueuedConnection把槽调用排到主线程事件循环。参数说明value是pyqtSignal(int)传过来的整数槽函数参数类型要匹配。注意如果槽函数里做耗时操作依然会卡主线程所以槽里只做 UI 更新别塞业务逻辑。4. 资源、打包与部署从能跑到能交付4.1 图片和 QSS 的资源管理qrc 文件怎么用配套代码里如果用了图标或样式表通常会有一个resources.qrc文件。直接读文件路径在开发机上没问题打包后路径全变图标就丢了。正确做法是把资源编译进 Python 模块。!-- resources.qrc -- RCC qresource prefix/ fileicons/app.png/file filestyles/main.qss/file /qresource /RCC# 编译 qrc 为 Python 模块 pyrcc6 resources.qrc -o resources_rc.py逻辑说明pyrcc6把二进制资源转成 Python 字节串运行时通过:/icons/app.png这种路径访问。参数说明prefix/是虚拟根目录访问时写:/icons/app.png。注意resources_rc.py要放在能被 import 到的地方并且在入口文件里import resources_rc否则资源不会注册。QSS 文件读取用QFile(:/styles/main.qss)别用open()。4.2 PyInstaller 打包参数与常见报错打包是 PyQt6 交付的最后一道坎。PyInstaller 对 PyQt6 的支持已经比较成熟但插件路径和隐藏导入经常出问题。我一般用--onefile加--windowed再手动指定 Qt 插件目录。# 打包单文件不显示控制台窗口 pyinstaller --onefile --windowed \ --name PyQt6Demo \ --add-data icons:icons \ --hidden-import PyQt6.QtCore \ --hidden-import PyQt6.QtGui \ main.py逻辑说明--add-data把外部资源目录拷进包内Windows 用;分隔macOS/Linux 用:。--hidden-import是防止 PyInstaller 静态分析漏掉 Qt 模块。参数说明--windowed在 Windows 上等价于--noconsolemacOS 上生成.app。注意如果报Could not find the Qt platform plugin windows需要在 spec 文件里加datas把PyQt6/Qt6/plugins/platforms拷进去或者设置环境变量QT_QPA_PLATFORM_PLUGIN_PATH。4.3 版本锁定与依赖清单配套代码要能复现依赖清单不能少。我一般用pip freeze导出但会手动删掉无关包只留 PyQt6、pyqt6-tools、pyinstaller 这几个核心的。# 导出当前环境依赖 pip freeze requirements.txt # 手动编辑后安装时用 pip install -r requirements.txt逻辑说明pip freeze会导出所有包包括间接依赖直接给别人可能装出一堆用不上的东西。参数说明建议在requirements.txt里写PyQt66.6.1这种精确版本避免 Qt 小版本升级导致样式或行为变化。注意pyqt6-tools在部分 Python 版本上依赖pyqt6-plugins如果安装失败可以只装PyQt6和PyQt6-Qt6Designer 单独用系统包。5. 避坑与排查PyQt6 实战里最容易翻车的 5 个点5.1 信号连不上控制台没有任何报错现象按钮点击后槽函数不执行也没有异常。原因信号名拼错或者槽函数被装饰器包了一层导致connect找不到。解决用btn.clicked.connect后加print确认连接成功检查信号名是否和 Qt 文档一致比如clicked不是click。另外如果槽函数用了pyqtSlot参数类型要匹配否则连接会静默失败。5.2 界面启动后一闪而过现象运行python main.py后窗口闪一下就退出。原因QApplication实例被垃圾回收或者window变量在main函数结束后被销毁。解决确保app.exec()被调用并且window是局部变量但show()之后进入事件循环Qt 会持有引用。如果还是闪退检查是否有未捕获异常在main里加try/except打印堆栈。5.3 打包后图标丢失、样式错乱现象开发时图标正常打包后图标变白或 QSS 不生效。原因资源路径用了相对路径打包后工作目录变了。解决统一用:/前缀访问 qrc 资源QSS 里引用图片也用url(:/icons/app.png)。如果必须用外部文件用sys._MEIPASS拼路径但更推荐 qrc。5.4 多线程下程序随机崩溃现象跑一段时间后崩溃堆栈指向QObject或QWidget。原因子线程里直接操作了 UI 对象或者 worker 对象在信号发射过程中被销毁。解决所有 UI 操作只在主线程做worker 的deleteLater连到thread.finished而不是worker.finished避免信号还没处理完对象就没了。5.5 高 DPI 屏幕上界面模糊现象在 4K 屏上字体和图标发虚。原因Qt6 默认启用高 DPI 缩放但部分旧写法没适配。解决在QApplication创建前设置QApplication.setHighDpiScaleFactorRoundingPolicy(Qt.HighDpiScaleFactorRoundingPolicy.PassThrough)并确保图标用 SVG 或高分辨率 PNG。注意这个设置要在QApplication实例化之前调用否则无效。6. 进阶技巧用 QSS 和自定义控件把界面做出产品感配套代码跑通之后下一步就是让界面不像“Demo”。我一般从 QSS 入手把按钮、输入框、表格的默认样式覆盖掉再封装一两个自定义控件。QSS 语法类似 CSS但选择器少一些支持伪状态比如:hover、:pressed。下面是一个最小可用的暗色主题片段直接放在main.qss里通过app.setStyleSheet加载。# 在 main.py 里加载 QSS from PyQt6.QtCore import QFile, QTextStream def load_stylesheet(app, path): file QFile(path) if file.open(QFile.OpenModeFlag.ReadOnly | QFile.OpenModeFlag.Text): stream QTextStream(file) app.setStyleSheet(stream.readAll()) file.close() # 调用load_stylesheet(app, :/styles/main.qss)/* main.qss 片段 */ QPushButton { background-color: #2d2d2d; color: #e0e0e0; border: 1px solid #3c3c3c; border-radius: 4px; padding: 6px 14px; } QPushButton:hover { background-color: #3a3a3a; } QPushButton:pressed { background-color: #1f1f1f; } QLineEdit { background-color: #1e1e1e; color: #e0e0e0; border: 1px solid #3c3c3c; border-radius: 3px; padding: 4px 8px; }逻辑说明QFile读 qrc 资源QTextStream处理编码避免中文乱码。app.setStyleSheet是全局生效所以 QSS 里尽量用具体控件名限定别写*。参数说明border-radius在部分平台需要配合QWidget的setAttribute(Qt.WidgetAttribute.WA_TranslucentBackground)才能圆角透明但普通按钮不需要。注意QSS 会覆盖setStyleSheet之前的样式所以加载顺序要在窗口show()之前。自定义控件方面我习惯从QWidget继承重写paintEvent画背景再用QPainter画文字或图标。比如一个带进度条的卡片可以用QPainterPath画圆角矩形再用QLinearGradient填充。但要注意paintEvent里不要做耗时计算所有数据提前算好存成属性。如果控件需要响应点击重写mousePressEvent并发射自定义信号而不是直接调父窗口的方法这样控件才能复用。验证自定义控件是否正常我一般写一个最小测试脚本单独实例化控件并show()不依赖主窗口。这样排查样式问题时能快速定位是控件本身还是布局的锅。最后QSS 和自定义控件都建议放在ui/目录下按功能分文件别全塞进main.py否则改一个颜色要翻几百行。希望帮到你。本文还有配套的精品资源点击获取