PyQt5 QWebEngineView致Windows10窗口全白问题排查求助

问题背景 #

在Windows 10环境下使用PyQt5 QWebEngineView时出现异常：在pyuic5生成的window_ui.py中保留self.webView = QtWebEngineWidgets.QWebEngineView(self.groupBox_4)代码时，整个窗口变为空白；删除该行代码则应用正常启动。但Ubuntu系统及Ubuntu下VirtualBox中的Windows 10虚拟机里，应用均可正常运行。

窗口空白时，控件功能实际正常（鼠标悬停光标会变化、点击不可见按钮可触发功能），且QWebEngineView已正常加载（能接收HTML页面的JavaScript日志），无任何错误日志输出。

使用的版本固定为：

pyqtwebengine 5.15.6   
pyqt5 5.15.4  

测试环境结果汇总 #

排查思路 #

• 检查显卡驱动与硬件加速：QWebEngineView依赖硬件加速，Windows下旧版或不兼容的显卡驱动可能导致渲染异常。可尝试：

  • 更新显卡驱动至最新版本
  • 代码中强制禁用硬件加速：

    from PyQt5.QtWebEngineWidgets import QWebEngineSettings
    QWebEngineSettings.globalSettings().setAttribute(QWebEngineSettings.Accelerated2dCanvasEnabled, False)
    QWebEngineSettings.globalSettings().setAttribute(QWebEngineSettings.WebGLEnabled, False)
    

  • 启动时添加环境变量禁用GPU：

    import os
    os.environ['QTWEBENGINE_CHROMIUM_FLAGS'] = '--disable-gpu'
    

• 验证父控件布局刷新：确认groupBox_4的布局设置正确，可在初始化webView后手动强制刷新布局：

  self.groupBox_4.update()
  # 或
  self.groupBox_4.layout().update()
  

• 重装依赖包并检查兼容性：Windows下可能存在依赖库冲突，使用干净虚拟环境重新安装指定版本：

  pip uninstall pyqt5 pyqtwebengine -y
  pip install pyqt5==5.15.4 pyqtwebengine==5.15.6
  

• 排查系统权限与沙箱机制：QWebEngineView在Windows下运行可能受权限或沙箱限制，可尝试：

  • 以管理员身份运行应用
  • 代码中添加环境变量禁用沙箱：

    import os
    os.environ['QTWEBENGINE_CHROMIUM_FLAGS'] = '--no-sandbox'
    

  • 若用PyInstaller编译EXE，在spec文件中添加沙箱禁用参数：

    a = Analysis(
        # 其他参数保留
        env={'QTWEBENGINE_CHROMIUM_FLAGS': '--no-sandbox'}
    )
    

• 测试最小示例排除干扰：创建仅包含QWebEngineView的最小窗口，验证是否能正常显示：

  from PyQt5.QtWidgets import QApplication, QMainWindow, QGroupBox, QVBoxLayout
  from PyQt5.QtWebEngineWidgets import QWebEngineView
  import sys
  
  class TestWindow(QMainWindow):
      def __init__(self):
          super().__init__()
          self.groupBox = QGroupBox(self)
          self.setCentralWidget(self.groupBox)
          layout = QVBoxLayout(self.groupBox)
          self.webView = QWebEngineView(self.groupBox)
          self.webView.setHtml("<h1>Test Content</h1>")
          layout.addWidget(self.webView)
          self.show()
  
  if __name__ == "__main__":
      app = QApplication(sys.argv)
      window = TestWindow()
      sys.exit(app.exec_())
  

  若该示例正常，说明问题出在原项目的布局或控件交互；若仍空白，问题偏向系统或库兼容性。

• 启用QT调试日志：开启QT日志获取潜在错误信息，代码开头添加：

  import os
  os.environ['QT_LOGGING_RULES'] = "qt.webengine*=true"
  

  运行后查看控制台输出，可能找到渲染相关的警告或错误。

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