Debian12升级后Poetry虚拟环境中PyQt5 QWebEngineView空白问题

问题概述 #

系统从Debian 11升级至Debian 12后，Poetry管理的虚拟环境内，PyQt5的QWebEngineView组件显示空白白屏，应用其余功能正常，且已将环境内所有包更新至最新版本。

测试用例 #

以下代码在Debian 12原生包环境运行正常，但在虚拟环境中无任何输出或报错，仅显示空白：

#!/usr/bin/env python3
import sys
from PyQt5.QtWidgets import QApplication
from PyQt5.QtWebEngineWidgets import QWebEngineView
from PyQt5.QtCore import QUrl

html = """
<!DOCTYPE html>
<html>
<body>
    <h1>Test</h1>
</body>
</html>
"""

app = QApplication(sys.argv)

web = QWebEngineView()

web.setHtml(html)

web.show()

sys.exit(app.exec_())

排查进展 #

为测试用例添加加载信号监听后发现：

• 正常环境：触发完整加载信号流程（含loadFinished）
• 虚拟环境：仅触发加载开始、0%和100%进度信号，未触发loadFinished信号

解决方案尝试 #

1. 补全系统级Qt WebEngine依赖 #

QWebEngineView依赖系统库，虚拟环境中的PyQt5可能无法正确链接Debian 12的系统组件，执行以下命令安装缺失依赖：

sudo apt install libqt5webengine5 libqt5webenginecore5 libqt5webenginewidgets5

2. 链接系统PyQt5至虚拟环境 #

卸载虚拟环境中的PyQt5，直接使用系统安装的版本：

# 移除虚拟环境内的PyQt包
poetry remove pyqt5 pyqtwebengine

# 创建软链接指向系统PyQt路径（路径需根据本地Python版本调整）
ln -s /usr/lib/python3/dist-packages/PyQt5 $(poetry env info --path)/lib/python3.11/site-packages/PyQt5
ln -s /usr/lib/python3/dist-packages/PyQtWebEngine $(poetry env info --path)/lib/python3.11/site-packages/PyQtWebEngine

3. 设置Qt WebEngine环境变量 #

Debian 12的Qt WebEngine在虚拟环境中可能需要特定变量才能运行，启动应用前执行：

export QTWEBENGINE_DISABLE_SANDBOX=1
export QT_QPA_PLATFORM_PLUGIN_PATH=/usr/lib/x86_64-linux-gnu/qt5/plugins/platforms

4. 重建Poetry虚拟环境 #

旧版本Poetry可能与Debian 12存在兼容性问题，更新并重建环境：

poetry self update
poetry env remove python3.11
poetry install

5. 启用Qt调试日志排查 #

添加日志输出规则，查看隐藏的加载错误：

# 在测试代码开头插入
import os
os.environ['QT_LOGGING_RULES'] = 'qt.webengine.*=true'

运行后查看终端输出，定位具体失败原因。

内容的提问来源于stack exchange，提问作者backseat