pygame 默认依赖视频子系统来处理事件队列，因此即使仅需手柄输入，在无 gui 环境（如树莓派命令行）下也会报 “video system not initialized” 错误；本文详解原因、验证方法及更优替代方案。
pygame 默认依赖视频子系统来处理事件队列，因此即使仅需手柄输入，在无 gui 环境（如树莓派命令行）下也会报 “video system not initialized” 错误；本文详解原因、验证方法及更优替代方案。
Pygame 的事件系统（pygame.event）并非独立模块，而是深度耦合于显示子系统——官方文档明确指出：“The input queue is heavily dependent on the pygame.display module”。这意味着，即使你完全不创建窗口、不渲染任何图像，只要未调用 pygame.display.set_mode() 或至少初始化显示模块（如 pygame.display.init()），事件循环（如 pygame.event.poll()）将无法正常工作，直接抛出 pygame.error: video system not initialized。
尝试“绕过”视频初始化是不可行的。以下代码看似精简，但在树莓派终端中仍会失败：
import pygame
pygame.init() # 初始化所有模块（含 display）
# ❌ 缺少 display 初始化 → 事件队列不可用
joystick = pygame.joystick.Joystick(0)
joystick.init()
while True:
event = pygame.event.poll() # 此处触发错误
if event.type == pygame.JOYAXISMOTION:
print(f"Axis {event.axis}: {event.value}")
正确做法（仅限有桌面环境时）：显式初始化显示（哪怕创建一个隐藏或最小化窗口）：
import pygame
import os
# 在树莓派 CLI 下可启用虚拟帧缓冲（需提前配置）
os.environ["SDL_VIDEODRIVER"] = "dummy" # 关键！使用 dummy 驱动
pygame.init()
pygame.display.set_mode((1, 1), pygame.DOUBLEBUF | pygame.HWSURFACE) # 创建 1x1 像素隐藏窗口
# 后续 joystick 初始化与事件处理即可正常运行
joystick = pygame.joystick.Joystick(0)
joystick.init()
done = False
while not done:
for event in pygame.event.get(): # 推荐用 get() 替代 poll()，更可靠
if event.type == pygame.QUIT:
done = True
elif event.type == pygame.JOYAXISMOTION and event.axis == 0:
print(f"Left stick X: {round(event.value, 3)}")
⚠️ 注意：SDL_VIDEODRIVER=dummy 方案要求系统已安装 libsdl2-dev 及 libraspberrypi-dev，且需在 pygame.init() 前设置环境变量。但该方式存在兼容性风险（尤其旧版 Pygame），不推荐作为生产环境首选。
✅ 更优实践：使用轻量级专用库 inputs
专为 Linux 输入设备设计，无需 GUI、零依赖显示系统，原生支持 /dev/input/ 事件接口，完美适配树莓派无桌面场景：
pip3 install inputs
from inputs import get_gamepad
import time
print("Gamepad listening... Press any button to exit.")
while True:
events = get_gamepad()
for event in events:
# event.code 示例: 'ABS_X', 'BTN_SOUTH', 'ABS_HAT0X'
# event.state: 0（释放）或 1（按下），模拟轴为 -32767~32767
if event.ev_type == 'Key' and event.state == 1:
print(f"[Button] {event.code} pressed")
elif event.ev_type == 'Absolute':
print(f"[Axis] {event.code}: {event.state}")
time.sleep(0.01) # 避免空转占用过高 CPU
? 提示：不同设备的 event.code 名称可能差异较大（如树莓派 Zero 与 PC 的手柄映射不同），建议首次运行时打印全部 event 查看实际键码，并据此编写条件逻辑（例如 if event.code == 'ABS_Y' and event.state
总结：Pygame 的设计目标是游戏开发，其输入能力是显示系统的附属功能；对于嵌入式机器人控制等纯输入场景，应优先选用 inputs、evdev 或 pygame 的底层替代方案。这不仅规避了视频初始化难题，还显著降低资源开销，提升系统稳定性与可维护性。
