在远程服务器上运行 Jupyter Notebook 时，单元格中的 print 或日志往往不会立即显示，而是等到任务结束才一次性刷出。这种现象多由输出缓冲、websocket 通道受阻或代理配置不当引起。下面介绍具体成因与解决办法。
为什么远程环境下输出会延迟
Jupyter 前端通过浏览器与内核建立 websocket 连接，内核产生的 stdout/stderr 会以消息形式经 tornado 服务推送到页面。当代码在远程执行时，若 Python 启用了块缓冲，或者反向代理没有正确转发 ws 请求，输出就会被积压。
常见原因
- Python 标准输出默认带缓冲，特别在非tty环境
- 未调用 flush 强行刷出流
- nginx 等代理未配置 Upgrade 头
- 内核繁忙时消息被合并发送
代码层强制实时刷新
在耗时循环中，应手动 flush 标准输出，或使用 print 的 flush 参数。
import time
for i in range(5):
# 使用 flush=True 立即推送到前端
print("当前进度: %d" % i, flush=True)
time.sleep(1)
# 也可以直接调用 sys.stdout.flush()
import sys
print("完成")
sys.stdout.flush()
关闭 Python 缓冲启动内核
可以通过修改内核启动命令，添加 -u 参数来以无缓冲方式运行。
# 在 jupyter 配置或 kernel 启动脚本中
python -u -m ipykernel_launcher -f {connection_file}
反向代理配置要点
若使用 nginx 暴露远程 Notebook，必须放行 websocket。否则实时消息无法到达浏览器。
location /api/kernels/ {
proxy_pass http://127.0.0.1:8888;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
}
前端验证输出通道
打开浏览器开发者工具的 Network 面板，筛选 ws 类型，确认存在到 /api/kernels/ 的 websocket 连接且状态为 101 Switching Protocols。若连接失败，按上述代理规则修正。
| 检查项 | 正常表现 |
|---|---|
| ws 连接 | 101 状态码 |
| print 输出 | 逐行出现 |
| 代理头 | 含 Upgrade |
小结
远程部署场景实现 Jupyter Notebook 单元格输出实时刷新，核心在于取消输出缓冲、保证 websocket 贯通。按代码 flush、内核无缓冲、代理放行的顺序排查，基本可以解决延迟问题。
Jupyter_Notebook实时输出websocket修改时间：2026-07-28 03:42:17