NiceGUI本地窗口启动后显示空白问题求助

现象 #

运行代码后，本地弹出的窗口显示空白。

问题描述 #

最初怀疑是代码逻辑错误，于是用最简代码复现问题，但空白问题依然存在。复现代码如下：

from nicegui import ui
ui.label("page with custom title")
ui.run(native=True, window_size=(400, 300), fullscreen=False)

系统环境 #

• Python 3.11.9 64位
• NiceGUI 2.5.0

解决方法 #

1. 检查WebView依赖 #

NiceGUI的原生窗口依赖系统自带的WebView组件，不同系统要求不同：

• Windows：需安装Microsoft Edge WebView2 Runtime，可在系统设置的「可选功能」中查看是否已安装，未安装则手动搜索下载安装。
• macOS：确保Safari为最新版本，或通过系统更新获取最新WebKit组件。
• Linux：安装对应依赖包，Debian/Ubuntu系执行：

  sudo apt install libwebkit2gtk-4.0-dev
  

  Fedora系执行：

  sudo dnf install webkit2gtk3-devel
  

2. 强制指定WebView后端 #

在ui.run()中添加webview_backend参数指定后端，比如Windows下用：

ui.run(native=True, window_size=(400, 300), fullscreen=False, webview_backend="edgechromium")

macOS可指定为"webkit"，Linux可指定为"gtkwebkit2"。

3. 调整NiceGUI版本 #

部分版本存在WebView兼容性问题，尝试降级或升级版本：

# 降级到2.4.8版本
pip install nicegui==2.4.8
# 升级到最新稳定版
pip install --upgrade nicegui

4. 排查网络拦截 #

暂时关闭本地防火墙或代理，测试是否因网络拦截导致服务通信失败。

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