# 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 了。
命令行确认一下：

```bash
python --version
# Python 3.13.12
```

### 2. 用 PyCharm 建项目

`File → New Project`，位置随便选，关键是下面这一栏：

**勾选 `Create a virtualenv`，解释器类型选 `Virtualenv`。**

为什么要用虚拟环境？因为 Qt 的版本依赖很敏感。你电脑上可能同时有别的项目在用 PySide2、
PyQt5，全局安装会互相打架。虚拟环境让每个项目各自一套依赖，互不影响。

### 3. 装依赖

打开 PyCharm 底部的 Terminal，执行：

```bash
pip install PyQt6 PyQt6-Charts
```

`PyQt6-Charts` 是图表模块，**它不在 PyQt6 主包里**，第 15、16 讲要用，建议现在一起装上。

装完验证一下：

```bash
python -c "from PyQt6.QtCore import QT_VERSION_STR; print('Qt', QT_VERSION_STR)"
# Qt 6.7.3
```

看到版本号就说明环境好了。

### 4. 国内网络加速

如果 `pip install` 卡着不动（PyQt6 的运行时包接近 80MB），换镜像：

```bash
pip install PyQt6 PyQt6-Charts -i https://pypi.tuna.tsinghua.edu.cn/simple
```

---

## 三、第一个窗口：完整代码

新建 `c01_hello_window.py`，把下面这段敲进去（建议手敲，不要复制）：

```python
import sys
from PyQt6.QtCore import Qt
from PyQt6.QtGui import QFont
from PyQt6.QtWidgets import QApplication, QLabel, QVBoxLayout, QWidget


class HelloWindow(QWidget):
    """最小可用窗口：继承 QWidget，往里面塞一个居中标签"""

    def __init__(self):
        super().__init__()

        # ---- 1. 窗口自身的属性 ----
        self.setWindowTitle("我的第一个 PyQt6 程序")
        self.resize(480, 300)

        # ---- 2. 创建控件 ----
        self.label = QLabel("Hello, PyQt6!", self)
        self.label.setAlignment(Qt.AlignmentFlag.AlignCenter)

        font = QFont()
        font.setPointSize(22)
        font.setBold(True)
        self.label.setFont(font)

        # ---- 3. 把控件交给布局管理 ----
        root = QVBoxLayout(self)
        root.addWidget(self.label)


if __name__ == "__main__":
    app = QApplication(sys.argv)
    window = HelloWindow()
    window.show()
    sys.exit(app.exec())
```

在 PyCharm 里右键 → `Run 'c01_hello_window'`，你会看到一个白底窗口，中间写着大号加粗的 `Hello, PyQt6!`。
![在这里插入图片描述](https://developer.qcloudimg.com/http-save/yehe-12820837/a28d2c60ed8c9f56d18d33dd6322d137.png)




窗口可以拖拽缩放 —— 注意文字**始终居中**，这就是布局的功劳，后面第 2 讲细讲。

---

## 四、三个必须搞懂的类

代码只有二十来行，但有三层概念，一层没搞清后面就会一直困惑。

### 1. QApplication：整个程序的"总管"

```python
app = QApplication(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

新手最容易写的是这个：

```python
label = QLabel("文字", self)
label.setGeometry(100, 120, 200, 40)      # 坐标 + 尺寸，硬编码
```

能跑，但窗口一放大，控件还钉在原地，右边一大片留白；换台不同 DPI 的电脑，位置就错乱了。

正确做法是把控件交给**布局管理器**：

```python
root = QVBoxLayout(self)      # 创建一个竖向布局，装到 self 上
root.addWidget(self.label)    # 控件加进去
```

`QVBoxLayout(self)` 这一行的含义是"给 self 设一个竖向布局"，之后所有加进来的控件，
Qt 会自动算位置、自动算尺寸、缩放时自动重排。**这一条是本课程后面所有界面的基础。**

---

## 五、事件循环：为什么最后一行那么奇怪

```python
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)` 忘了删。

**坑 2：`QLabel` 建了但看不见**
忘了传父控件，也没加进布局。控件没有父窗口时是独立窗口，不会出现在你的窗口里。
要么 `QLabel("文字", self)`，要么 `layout.addWidget(label)`。

**坑 3：中文显示成方框**
Windows 上极少见。Linux 下装中文字体即可（Ubuntu：`sudo apt install fonts-wqy-microhei`）。

**坑 4：PyCharm 里运行报 `ModuleNotFoundError: No module named 'PyQt6'`**
装到了系统 Python 而不是项目虚拟环境。检查右下角解释器是不是项目那个 venv，
或者干脆在 Terminal 里 `pip install PyQt6` 再跑。

---

## 七、小结

这一讲只做了三件事，但都是地基：

1. **环境**：PyCharm + 虚拟环境 + `PyQt6` 和 `PyQt6-Charts`
2. **三个类**：`QApplication`（总管 + 事件循环）、`QWidget`（一切控件的基类）、布局管理器
3. **一个循环**：`app.exec()` 让界面"活"起来

现在你的窗口里只有一个居中的标签。真实软件的界面是十几个控件一层层排出来的——
按钮在哪一行、输入框占多宽、窗口缩放时谁跟着变，这些全靠布局管理。

**下一讲**：把布局彻底讲清，做出一个像模像样的登录界面，顺便把"为什么我的控件位置全乱了"这个
最高频问题一次性解决。

---

> 本讲是《PyQt6 客户端编程从入门到实战》专栏的第 1 讲（免费试读）。
> 专栏共 22 讲、22 个可运行案例，配套完整 PyCharm 工程，涵盖自动化办公、数据库、
> 数据可视化、文件自动化与打包发布。

PyQt6 客户端编程从入门到实战 第 1 讲 | 环境搭建与第一个 PyQt6 窗口 本讲目标：把环境搭好，理解 QApplication / QWidget / 事件循环这三个最基础也最容易被跳过的概念，跑出你的第一个窗口。 配套代码：cases/c01hellowindow.py 一、先回答一个问题：为什么选 PyQt6 做 Python 桌面的路只有三条，先花两分钟把选型说清楚，免得写到一

PyQt6-第01讲-环境搭建与第一个窗口

人工智能

PyQt6客户端编程入门教程，详解环境搭建与第一个窗口创建。涵盖Python虚拟环境配置、PyQt6与PySide6选型对比、QApplication/QWidget/事件循环三大核心概念，通过实战案例演示布局管理器使用，并提供新手常见坑解决方案。适合Python桌面开发初学者快速上手。

数据可视化

数据库

解释器

Windows

Python

Ubuntu

Linux

2026上云采购 | AI焕新·智启新局

ecdn

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

PyQt6-第01讲-环境搭建与第一个窗口-腾讯云开发者社区-腾讯云

PyQt6-第01讲-环境搭建与第一个窗口

PyQt6-第01讲-环境搭建与第一个窗口

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐