PyQt6 客户端编程从入门到实战 第 1 讲 | 环境搭建与第一个 PyQt6 窗口本讲目标把环境搭好理解 QApplication / QWidget / 事件循环这三个最基础也最容易被跳过的概念跑出你的第一个窗口。配套代码cases/c01_hello_window.py一、先回答一个问题为什么选 PyQt6做 Python 桌面的路只有三条先花两分钟把选型说清楚免得写到一半推倒重来。方案优势代价适合Tkinter标准库自带零安装界面停留在 2005 年控件少、样式难调只给自己用的小工具PyQt6 / PySide6控件齐全、样式可控、跨平台、性能好学习曲线比 Tkinter 陡要做能交付给别人用的软件Electron / WebView前端技术栈、UI 漂亮一个空窗口就占 100MB 内存团队里有前端选 PyQt6 的核心原因Qt 这个框架已经活了三十多年你遇到的所有问题几乎都有人问过。表控件、树控件、图表、数据库绑定、打印、拖拽、多线程全都是框架内置的不需要自己造。PyQt6 和 PySide6 怎么选两者 API 几乎一模一样PySide6 是 Qt 官方绑定PyQt6 是 Riverbank 公司出的。唯一要注意的是授权PyQt6 是 GPL 授权。自己用、开源项目、公司内部工具都没问题如果你要做闭源商业软件对外销售要么买 PyQt 的商业授权要么改用 LGPL 的 PySide6。本课程用 PyQt6代码改成 PySide6 基本只改 import 那一行。二、环境搭建5 分钟1. Python 版本建议3.10 及以上。PyQt6 从 6.0 起就不支持 Python 3.6/3.7 了。命令行确认一下python--version# Python 3.13.122. 用 PyCharm 建项目File → New Project位置随便选关键是下面这一栏勾选Create a virtualenv解释器类型选Virtualenv。为什么要用虚拟环境因为 Qt 的版本依赖很敏感。你电脑上可能同时有别的项目在用 PySide2、PyQt5全局安装会互相打架。虚拟环境让每个项目各自一套依赖互不影响。3. 装依赖打开 PyCharm 底部的 Terminal执行pipinstallPyQt6 PyQt6-ChartsPyQt6-Charts是图表模块它不在 PyQt6 主包里第 15、16 讲要用建议现在一起装上。装完验证一下python-cfrom PyQt6.QtCore import QT_VERSION_STR; print(Qt, QT_VERSION_STR)# Qt 6.7.3看到版本号就说明环境好了。4. 国内网络加速如果pip install卡着不动PyQt6 的运行时包接近 80MB换镜像pipinstallPyQt6 PyQt6-Charts-ihttps://pypi.tuna.tsinghua.edu.cn/simple三、第一个窗口完整代码新建c01_hello_window.py把下面这段敲进去建议手敲不要复制importsysfromPyQt6.QtCoreimportQtfromPyQt6.QtGuiimportQFontfromPyQt6.QtWidgetsimportQApplication,QLabel,QVBoxLayout,QWidgetclassHelloWindow(QWidget):最小可用窗口继承 QWidget往里面塞一个居中标签def__init__(self):super().__init__()# ---- 1. 窗口自身的属性 ----self.setWindowTitle(我的第一个 PyQt6 程序)self.resize(480,300)# ---- 2. 创建控件 ----self.labelQLabel(Hello, PyQt6!,self)self.label.setAlignment(Qt.AlignmentFlag.AlignCenter)fontQFont()font.setPointSize(22)font.setBold(True)self.label.setFont(font)# ---- 3. 把控件交给布局管理 ----rootQVBoxLayout(self)root.addWidget(self.label)if__name____main__:appQApplication(sys.argv)windowHelloWindow()window.show()sys.exit(app.exec())在 PyCharm 里右键 →Run c01_hello_window你会看到一个白底窗口中间写着大号加粗的Hello, PyQt6!。窗口可以拖拽缩放 —— 注意文字始终居中这就是布局的功劳后面第 2 讲细讲。四、三个必须搞懂的类代码只有二十来行但有三层概念一层没搞清后面就会一直困惑。1. QApplication整个程序的总管appQApplication(sys.argv)它做了三件事初始化 Qt 的底层资源字体、绘图上下文、平台插件解析命令行参数sys.argv传给它Qt 会识别一些自带参数维护事件循环铁律任何控件在被创建之前QApplication 必须已经存在。这是新手第一个高频崩溃点——把QApplication写在控件创建之后程序会直接崩掉QWidget: Must construct a QApplication before a QWidget另外一个程序只能有一个 QApplication 实例。想开第二个窗口不要新建 QApplication再new一个窗口类就行。2. QWidget所有可视控件的祖宗QWidget既是窗口也是控件的基类。QLabel、QPushButton、QTableWidget全都继承自它。所以QWidget直接实例化 → 得到一个空窗口class MyWindow(QWidget)→ 自定义窗口QLabel(文字, self)里的self→ 这个标签的父控件父控件决定了三件事子控件显示在谁身上、子控件随父控件一起销毁、子控件的坐标相对谁。3. 布局别用 setGeometry新手最容易写的是这个labelQLabel(文字,self)label.setGeometry(100,120,200,40)# 坐标 尺寸硬编码能跑但窗口一放大控件还钉在原地右边一大片留白换台不同 DPI 的电脑位置就错乱了。正确做法是把控件交给布局管理器rootQVBoxLayout(self)# 创建一个竖向布局装到 self 上root.addWidget(self.label)# 控件加进去QVBoxLayout(self)这一行的含义是给 self 设一个竖向布局之后所有加进来的控件Qt 会自动算位置、自动算尺寸、缩放时自动重排。这一条是本课程后面所有界面的基础。五、事件循环为什么最后一行那么奇怪sys.exit(app.exec())很多人的疑问是window.show()之后窗口不是已经显示了吗为什么还要app.exec()因为窗口显示出来只是画了一帧。你要让它活起来——能响应鼠标、能打字、能重绘——必须有一个循环不停地在跑while True: 从操作系统取出一个事件点击/按键/重绘 找到应该处理它的控件 调用对应的处理函数app.exec()就是这个循环。它阻塞在那里直到你关闭所有窗口或调用quit()才返回。所以写了exec()程序进入循环界面响应关闭窗口后循环结束程序退出 ✔不写exec()程序执行完最后一行直接退出窗口一闪而过 ✘这就是窗口闪一下就没了的原因sys.exit(...)是把exec()的返回值退出码传给系统让退出状态规范。不写也不影响运行但写了更规范。六、四个新手必踩的坑坑 1窗口一闪而过多半是漏了app.exec()或者把window写成了局部变量被提前回收。还有一个可能你加过QTimer.singleShot(xxx, app.quit)忘了删。坑 2QLabel建了但看不见忘了传父控件也没加进布局。控件没有父窗口时是独立窗口不会出现在你的窗口里。要么QLabel(文字, self)要么layout.addWidget(label)。坑 3中文显示成方框Windows 上极少见。Linux 下装中文字体即可Ubuntusudo apt install fonts-wqy-microhei。坑 4PyCharm 里运行报ModuleNotFoundError: No module named PyQt6装到了系统 Python 而不是项目虚拟环境。检查右下角解释器是不是项目那个 venv或者干脆在 Terminal 里pip install PyQt6再跑。七、小结这一讲只做了三件事但都是地基环境PyCharm 虚拟环境 PyQt6和PyQt6-Charts三个类QApplication总管 事件循环、QWidget一切控件的基类、布局管理器一个循环app.exec()让界面活起来现在你的窗口里只有一个居中的标签。真实软件的界面是十几个控件一层层排出来的——按钮在哪一行、输入框占多宽、窗口缩放时谁跟着变这些全靠布局管理。下一讲把布局彻底讲清做出一个像模像样的登录界面顺便把为什么我的控件位置全乱了这个最高频问题一次性解决。本讲是《PyQt6 客户端编程从入门到实战》专栏的第 1 讲免费试读。专栏共 22 讲、22 个可运行案例配套完整 PyCharm 工程涵盖自动化办公、数据库、数据可视化、文件自动化与打包发布。