Windows 下 PyQt 在虚拟环境（venv）中报 “Could not find the Qt platform plugin windows” 的完整复盘与避坑指南

环境：Windows 10/11 + Python 3.8–3.11 + PyQt5 + venv
报错：qt.qpa.plugin: Could not find the Qt platform plugin "windows"

---

一、问题现象

在 Windows 下使用 Python venv 虚拟环境运行 PyQt 程序时报错：

qt.qpa.plugin: Could not find the Qt platform plugin "windows" in ""

This application failed to start because no Qt platform plugin could be initialized.

奇怪的是：

• ✅ 全局 Python 能正常运行
• ❌ venv 中必挂
• ❌ 系统 PATH 并未配置 Qt
• ✅ 手动设置 QT_QPA_PLATFORM_PLUGIN_PATH 后可运行

---

二、常见误区排查

1️⃣ PyQt5 安装不完整？

否。qwindows.dll 存在：

venv/Lib/site-packages/PyQt5/Qt5/plugins/platforms/qwindows.dll

2️⃣ venv PATH 未继承？

否。对比发现 全局 Python 和 venv 的 PATH 都没有 Qt 路径。

3️⃣ 单纯是 venv 隔离？

是放大因素，但不是根本原因。

---

三、Qt 在 Windows 如何查找 platform plugin

Qt 不依赖 Python 的 sys.path，而是：

1. 加载 QtCore.dll
2. 以该 DLL 所在目录为锚点
3. 推导 ../plugins/platforms/qwindows.dll

如果 QtCore.dll 不在 Windows DLL 搜索路径中 → 推导失败 → plugin 加载失败

---

四、为什么全局能跑，venv 不能？

• 全局 Python 安装在 纯 ASCII 路径（如 D:\tools\python3_10\）
• venv 的 python.exe 在含 中文目录 的项目路径下：
  E:\workspace*项目*\venv\Scripts\python.exe

👉 Qt5 在 plugin 初始化阶段对 中文路径支持不完整，导致已知路径却被拒绝加载。

Python 验证代码：

from PyQt5.QtCore import QLibraryInfo, QCoreApplication

print(QLibraryInfo.location(QLibraryInfo.PluginsPath))
print(QCoreApplication.libraryPaths())

纯文本

E:/workspace/项目/venv/lib/site-packages/PyQt5/Qt5/plugins
[]

✅ 路径已知
❌ Qt 拒绝加载 → 空列表

---

五、解决方案（推荐顺序）

✅ 方案一（最推荐）：项目路径避免中文

Windows + Qt 第一铁律：工程 / venv / 第三方库路径只用 ASCII
E:\workspace\project\

---

✅ 方案二：代码中显式指定 plugin 路径

Python 代码

import os
import PyQt5

plugin_path = os.path.join(os.path.dirname(PyQt5.__file__), "Qt5", "plugins")
os.environ["QT_QPA_PLATFORM_PLUGIN_PATH"] = plugin_path

from PyQt5.QtWidgets import QApplication

…

✅ 方案三：升级 PyQt6 / PySide6

Qt6 对 Unicode 路径处理更完善，较少踩此坑。

---

六、总结

• venv 不是原罪，是暴露因素
• QLibraryInfo ≠ 实际可用 libraryPaths()
• 中文路径 + Qt5 plugin 加载 = 经典深坑
• 显式设置 QT_QPA_PLATFORM_PLUGIN_PATH 或避免中文路径

希望这篇能帮你少花一下午排查 🙌