使用NiceGUI开发Python应用时API调用超时断连的解决方法

核心问题是耗时API调用阻塞了NiceGUI的主线程，导致WebSocket心跳无法正常发送，最终触发断连提示。以下是具体解决方案：

1. 将耗时API调用移到后台线程 #

不要在按钮的回调函数里直接执行阻塞操作，把API调用放到独立线程中，让主线程保持活跃以维持WebSocket连接：

from nicegui import ui
import threading
import requests

def slow_third_party_api():
    # 替换为你的第三方API调用逻辑
    response = requests.get("https://your-slow-api.com/endpoint")
    return response.text

def on_button_click():
    # 显示加载状态，告知用户正在处理
    loading_spinner.visible = True
    result_label.text = ""

    def background_task():
        try:
            api_result = slow_third_party_api()
            result_label.text = f"API返回：{api_result}"
        except Exception as e:
            result_label.text = f"请求失败：{str(e)}"
        finally:
            loading_spinner.visible = False

    # 启动后台守护线程执行API调用
    threading.Thread(target=background_task, daemon=True).start()

with ui.column():
    ui.button("调用第三方API", on_click=on_button_click)
    loading_spinner = ui.spinner(visible=False)
    result_label = ui.label()

ui.run()

2. 用异步方式处理请求 #

如果偏好异步编程，可以用asyncio.to_thread将同步API调用包装为异步任务，同样避免阻塞主线程：

from nicegui import ui
import asyncio
import requests

async def slow_third_party_api():
    # 用asyncio.to_thread把同步请求放到后台线程
    response = await asyncio.to_thread(requests.get, "https://your-slow-api.com/endpoint")
    return response.text

async def on_button_click():
    loading_spinner.visible = True
    result_label.text = ""
    try:
        api_result = await slow_third_party_api()
        result_label.text = f"API返回：{api_result}"
    except Exception as e:
        result_label.text = f"请求失败：{str(e)}"
    finally:
        loading_spinner.visible = False

with ui.column():
    ui.button("调用第三方API", on_click=on_button_click)
    loading_spinner = ui.spinner(visible=False)
    result_label = ui.label()

ui.run()

3. 调整WebSocket心跳参数（辅助优化） #

可以通过修改ui.run()的参数，缩短心跳间隔、延长超时时间，降低被判定为断连的概率：

ui.run(ping_interval=1, ping_timeout=5)

• ping_interval：前端发送心跳包的间隔（秒）
• ping_timeout：等待心跳响应的超时时间（秒）

关键说明 #

NiceGUI的UI更新是线程安全的，在后台线程或异步函数中直接修改UI元素的属性（如label.text、spinner.visible）即可，框架会自动处理更新的同步逻辑。

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