PyQt5安装需兼顾Python版本兼容、网络加速与工具链匹配：Python 3.10+须指定兼容版本（如5.15.9），国内用户必加清华镜像源；pyqt5-tools须与PyQt5主版本严格对齐，且需正确配置QT_QPA_PLATFORM_PLUGIN_PATH环境变量方可运行GUI。
直接用 pip install PyQt5 就能装，但多数人卡在版本兼容、网络超时或缺 pyqt5-tools 上。
安装命令本身很简单，但得看 Python 版本和网络环境
Python 3.10 及以上用户不能无脑执行 pip install PyQt5 —— 官方 wheel 包从 5.15.7 开始就不再提供 3.10+ 的预编译二进制包（只提供源码 sdist），而编译需要系统已装 Qt 的 qmake 和 sip 工具，普通用户基本跑不通。
- 推荐做法：明确指定一个兼容你 Python 版本的 PyQt5 版本，比如 Python 3.11 用
pip install PyQt5==5.15.9 - 国内用户必加镜像源，否则大概率超时：
pip install PyQt5 -i https://pypi.tuna.tsinghua.edu.cn/simple - 如果提示
ERROR: Could not find a version that satisfies the requirement PyQt5，说明 pip 没有识别到匹配的 wheel，先升级 pip：python -m pip install --upgrade pip
pyqt5-tools（含 Designer）必须单独装，且版本要对齐
pyqt5-tools 不是 PyQt5 的子模块，它独立发布，且和 PyQt5 主版本强绑定。装错版本会导致 designer.exe 找不到 Qt 插件、启动白屏或报 ImportError: DLL load failed。
- 查当前 PyQt5 版本：
python -c "import PyQt5; print(PyQt5.__version__)" - 装对应版本的 tools（例如 PyQt5 是 5.15.9，就装
pyqt5-tools==5.15.4.3.2） - Windows 用户注意：装完后
designer.exe默认在Scripts/目录下，不是site-packages里 - macOS/Linux 用户可能需手动把
designer加入 PATH，否则终端敲designer找不到命令
验证安装是否真正可用，别只看 “Successfully installed”
输出 “Successfully installed” 只代表包下载解压完成，不代表能 import 或启动 GUI 窗口。真实可用要过三关：
- 运行
python -c "from PyQt5.QtWidgets import QApplication; print('OK')"—— 过不去说明 C++ Qt 库没加载成功 - 运行最小窗口代码：
python -c "import sys; from PyQt5.QtWidgets import QApplication, QLabel; app = QApplication(sys.argv); QLabel('test').show(); app.exec_()"—— 黑屏/闪退/报qt.qpa.plugin: Could not load the Qt platform plugin "windows"，说明平台插件路径没设对 - 启动 Designer：
designer（macOS/Linux）或designer.exe（Windows）—— 打不开或界面空白，大概率是pyqt5-tools和PyQt5版本不匹配
最容易被忽略的是：PyQt5 的 wheel 包里自带了精简版 Qt 运行时（LGPL），但它不包含全部插件（比如 Windows 平台插件在 PyQt5/Qt/plugins/platforms/ 下）。一旦环境变量 QT_QPA_PLATFORM_PLUGIN_PATH 没指向这个路径，GUI 就起不来——这问题在虚拟环境、Conda 环境、VSCode 集成终端里高频出现。
