必须先调用pygame.init()且在主线程执行，再调用pygame.display.set_mode()；否则因视频子系统未初始化而失败，需检查环境、版本及display初始化状态。
Pygame.init() 调用顺序不对，导致 pygame.display.set_mode() 失败
这个错误几乎总是因为 pygame.display.set_mode() 在 pygame.init() 之前被调用，或者 pygame.init() 根本没被调用。Pygame 的视频子系统（video system）必须显式初始化后才能创建窗口或操作显示表面。
- 确保
pygame.init()是整个程序最早执行的 Pygame 相关调用之一（通常紧跟在import pygame后） - 不要把
pygame.display.set_mode()写在pygame.init()之前 —— 即使只差一行也会触发该错误 - 如果用了
pygame.mixer.init()或其他子系统初始化，pygame.init()仍需先调用；它负责全局初始化，包括 video system - 注意：
pygame.init()返回一个元组（已初始化/未初始化的模块数），但不抛异常；即使返回(6, 0)也不代表 display 模块一定就绪 —— 它依赖底层 SDL 初始化成功
在多线程环境里误在非主线程调用 pygame.display.set_mode()
SDL（Pygame 底层）要求所有视频相关操作（包括 set_mode、flip、blit）必须在主线程执行。如果你在子线程里创建窗口或刷新画面，就会报 “Video system not initialized”，哪怕 pygame.init() 已在主线程调用过。
yuanfang-skills 的共享设计系统，提供 token CSS 变量、12+ 主题以及可复用的布局类型 HTML 块，供 yuanfang-html-image（以及 fu...）使用。
- 确认你的游戏主循环（含
pygame.display.flip()和事件循环）完全运行在主线程 - 避免在
threading.Thread或concurrent.futures子线程中调用任何pygame.display.*函数 - 如需后台加载资源，用线程加载数据（如图像字节、音频文件），但把 surface 创建和 blit 留给主线程
- Python 的
asyncio也不能替代主线程 —— 即使你在事件循环里调用set_mode，只要不是 OS 主线程，SDL 仍会拒绝
使用了 headless 环境（如服务器、CI）却没禁用显示
在无图形界面的 Linux 环境（比如 Docker 容器、GitHub Actions runner、SSH 远程服务器）直接运行 pygame.display.set_mode() 会失败，并可能表现为 “Video system not initialized” —— 实际是 SDL 找不到可用的显示驱动，初始化 display 子系统失败。
- 运行前检查环境变量：
os.environ.get('DISPLAY')是否为空（Linux/macOS）或os.name == 'nt'（Windows） - 若确定无显示设备，改用
pygame.display.set_mode((1,1), pygame.HIDDEN)或更稳妥地，先设置os.environ['SDL_VIDEODRIVER'] = 'dummy'再pygame.init() - 注意：
pygame.HIDDEN仅在部分平台生效；dummy驱动需 SDL2 支持，且不能用于实际渲染 —— 适合单元测试或资源预加载 - CI 中常见做法：安装
xvfb并用xvfb-run python game.py模拟 X11 显示
Pygame 版本与 SDL 兼容问题引发静默初始化失败
某些旧版 Pygame（如 1.9.x）或非官方二进制包，在较新系统上可能因 SDL2 库缺失/版本错配，导致 pygame.init() 不报错但 display 子系统实际未启动。这种情况下 pygame.display.get_init() 返回 False，但错误信息仍是模糊的 “Video system not initialized”。
- 运行后立即检查：
print(pygame.display.get_init())—— 如果输出False，说明 display 模块压根没起来 - 升级到 Pygame 2.x（
pip install --upgrade pygame），它默认绑定 SDL2，兼容性更好 - Linux 上若用系统包管理器安装（如
apt install python3-pygame），常因 SDL 库版本太老而失效；优先用 pip 安装 wheel 包 - macOS 上如果用 conda，注意
conda-forge的 Pygame 构建比默认 channel 更稳定
pygame.init() 成功返回，pygame.display.get_init() 仍可能为 False，得单独验证。Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
