根本原因是SDL2无法找到可用图形后端，常见于无GUI环境、DISPLAY未设置或错误、驱动缺失；解决需提前设置SDL_VIDEODRIVER（如x11/dummy）或正确配置X11/Wayland。
Pygame.init() 报错 No available video device 的根本原因
这个错误不是 Pygame 本身坏了，而是它底层依赖的 SDL2 库完全没找到可用的图形输出后端。常见于无图形界面环境（如 SSH 连接的服务器、Docker 容器、WSL 默认配置）或 DISPLAY 环境变量缺失/错误。SDL 尝试按顺序加载驱动（如 x11、wayland、dummy），全失败就抛出这个错误。
检查并设置 DISPLAY 环境变量（X11 场景）
如果你在 Linux 桌面环境或通过 X11 转发连接（比如 ssh -X），DISPLAY 必须正确指向 X server：
- 运行
echo $DISPLAY—— 正常应输出类似:0或localhost:10.0 - 若为空，先确认 X server 是否运行：
pgrep Xorg或systemctl --user show-environment | grep DISPLAY - 手动设置（仅临时测试）：
export DISPLAY=:0（本地桌面）或export DISPLAY=localhost:10.0（SSH -X） - 注意：WSL1 可直接用
:0；WSL2 需额外配置 X server（如 VcXsrv）并设为export DISPLAY=$(cat /etc/resolv.conf | grep nameserver | awk '{print $2}'):0
强制指定 SDL_VIDEODRIVER（绕过自动探测）
当自动探测失败但你知道可用后端时，跳过探测直接指定驱动更可靠：
macOS UI 自动化技能包 —— 用 Python 控制你的 Mac
下载
让 macOS 自动化像说话一样简单 —— 用代码控制你的 Mac，无需学习 AppleScript 系统要求 macOS 14+ (Sonoma) Python 3.9+ 需要开启：辅助功能 + 屏幕录制权限
- 使用 X11：
export SDL_VIDEODRIVER=x11 - 使用 Wayland（较新桌面）：
export SDL_VIDEODRIVER=wayland - 纯 headless 测试（无真图形）：
export SDL_VIDEODRIVER=dummy—— 此时窗口不显示，但pygame.Surface和逻辑可正常运行 - 必须在
import pygame之前设置，或在 Python 中用os.environ['SDL_VIDEODRIVER'] = 'x11'（早于pygame.init()） - 验证是否生效：运行
python3 -c "import pygame; print(pygame.display.get_driver())"
Docker / 无 GUI 环境下的最小可行方案
容器或 CI 环境中不能也不该启动真实显示服务，硬配 DISPLAY 会失败：
立即学习“Python免费学习笔记（深入）”；
- 安装
libsdl2-dev和libsdl2-image-dev（Debian/Ubuntu）确保 SDL 支持dummy驱动 - 启动前设环境变量：
SDL_VIDEODRIVER=dummy SDL_AUDIODRIVER=dummy（音频也关掉） - 代码里加兜底逻辑：
import os os.environ['SDL_VIDEODRIVER'] = 'dummy' import pygame pygame.init() screen = pygame.display.set_mode((1, 1)) # 避免 zero-size surface 报错
- 注意：
dummy驱动不支持pygame.display.set_mode()的实际尺寸（会静默降为 1×1），所有渲染需基于Surface对象操作
最容易被忽略的是环境变量设置时机——它必须在 SDL 初始化前生效，而 Python 的 import 过程中 SDL 就可能被间接加载。如果用了某些打包工具（如 PyInstaller）或 IDE 内置终端，环境变量可能未继承，得查进程实际环境。
