仅使用pygame的key模块报视频系统未初始化错误，无GUI环境如何解决

问题根因 #

pygame的key模块底层完全绑定pygame视频子系统的事件循环，并非独立的全局键盘监听组件，即使没有单独的pygame.key.init()方法，调用key.get_pressed()也必须依赖视频子系统初始化完成。默认情况下视频子系统需要X11窗口环境，这就是无头环境下出现video system not initialized、XDG_RUNTIME_DIR not set报错的核心原因。

方案1：适配pygame的低资源方案 #

如果需要保留原有pygame相关代码，可以通过配置虚拟显示+隐藏窗口的方式实现无GUI运行，额外资源占用远低于完整桌面环境：

• 安装虚拟X服务器：

sudo apt install xvfb

• 代码中指定dummy视频驱动，创建最小隐藏窗口：

import os
# 强制pygame使用无输出的dummy视频驱动
os.environ['SDL_VIDEODRIVER'] = 'dummy'
import pygame
pygame.init()
# 创建1*1像素的隐藏窗口，满足视频子系统初始化要求
pygame.display.set_mode((1,1), pygame.HIDDEN)

# 调用key模块前必须先刷新事件队列，否则按键状态不会更新
pygame.event.pump()
from pygame import key
keys = key.get_pressed()

• 运行脚本时挂载虚拟显示：

export DISPLAY=:1 && xvfb-run --auto-servernum python 你的脚本名.py

方案2：无头环境原生键盘监听（更优） #

如果没有强制使用pygame的需求，直接通过Linux内核输入子系统读取键盘事件是最优方案，完全不需要X服务或窗口，资源占用极低：

• 安装evdev依赖：

pip install evdev

• 代码示例：

import evdev

# 遍历所有输入设备匹配键盘
devices = [evdev.InputDevice(path) for path in evdev.list_devices()]
keyboard = None
for dev in devices:
    if "keyboard" in dev.name.lower():
        keyboard = dev
        break

if not keyboard:
    raise Exception("未检测到键盘设备")

# 给运行脚本的用户添加input组权限即可免sudo运行：sudo usermod -aG input $USER（执行后需重新登录）
for event in keyboard.read_loop():
    if event.type == evdev.ecodes.EV_KEY:
        key_info = evdev.categorize(event)
        # 按键按下
        if key_info.keystate == key_info.key_down:
            print(f"按键按下：{key_info.keycode}")
        # 按键松开
        elif key_info.keystate == key_info.key_up:
            print(f"按键松开：{key_info.keycode}")

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