树莓派Linux环境下Python键盘监听代码误捕获鼠标滚轮输入为字符的问题排查

阿华AIGC实验室

2026-4-2

问题背景

你这段用来捕获单字符按键做调试的代码，本来用着挺顺手，结果在树莓派Bookworm上滚动鼠标滚轮时，会被误识别成字符输入，确实挺闹心的。先给你理清楚问题出在哪，再给你靠谱的解决办法。

问题原因

你疑惑鼠标滚轮不该把字符丢进stdin？其实在Linux终端环境里，当鼠标处于终端窗口内时，部分终端会把鼠标事件（包括滚轮滚动）编码成特殊的ASCII转义序列，通过标准输入传递给当前运行的程序——这不是你的代码有bug，是终端的默认行为。

比如滚轮上下滚动时，终端可能会发送类似\x1b[62~、\x1b[63~这类多字节转义序列，而你的代码用sys.stdin.read(1)每次只读一个字节，就会把这些序列拆成单个字符（比如\x1b、[、6、2、~）逐个返回，看起来就像乱码字符。

解决方案

我们有两个方向可以解决，既不会全局禁用滚轮，也能保留你的键盘监听功能：

方案1：临时禁用终端的鼠标事件传递（推荐）

在你的KeyPoller类的初始化阶段，用ANSI转义码告诉终端：暂时不要把鼠标事件发送到标准输入。退出时再恢复，完全不影响系统其他地方的鼠标使用。

修改后的完整KeyPoller类：

import sys
import termios
import select

class KeyPoller():
    def __enter__(self):
        # 保存终端原始设置
        self.fd = sys.stdin.fileno()
        self.new_term = termios.tcgetattr(self.fd)
        self.old_term = termios.tcgetattr(self.fd)

        # 设置终端为无缓冲、无回显模式
        self.new_term[3] = (self.new_term[3] & ~termios.ICANON & ~termios.ECHO)
        termios.tcsetattr(self.fd, termios.TCSAFLUSH, self.new_term)

        # 新增：禁用终端向stdin发送鼠标事件
        sys.stdout.write("\x1b[?1000l")
        sys.stdout.flush()

        return self

    def __exit__(self, type, value, traceback):
        # 恢复终端原始设置
        termios.tcsetattr(self.fd, termios.TCSAFLUSH, self.old_term)
        # 新增：恢复终端的鼠标事件上报
        sys.stdout.write("\x1b[?1000h")
        sys.stdout.flush()

    def poll(self):
        dr,dw,de = select.select([sys.stdin], [], [], 0)
        if not dr == []:
            return sys.stdin.read(1)
        return None

\x1b[?1000l是ANSI控制码，作用是临时关闭终端的鼠标事件上报
__exit__里的\x1b[?1000h用来恢复默认行为，确保退出上下文管理器后，终端鼠标功能完全正常

方案2：在代码里过滤鼠标转义序列

如果不想修改终端设置，也可以在poll方法里识别并跳过鼠标事件的转义序列。这类序列通常以\x1b（ESC键的ASCII码）开头，我们可以在读取时判断并跳过整个序列：

修改poll方法：

def poll(self):
    dr,dw,de = select.select([sys.stdin], [], [], 0)
    if not dr == []:
        c = sys.stdin.read(1)
        # 捕获到ESC开头的转义序列，跳过整个序列
        if c == '\x1b':
            # 循环读取后续字符，直到转义序列结束
            while True:
                dr2,_,_ = select.select([sys.stdin], [], [], 0)
                if dr2:
                    next_c = sys.stdin.read(1)
                    # 转义序列通常以~或字母结尾，这里做简单判断
                    if next_c in '~ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz':
                        break
                else:
                    break
            return None
        return c
    return None

这个方法的小缺点是：会误过滤掉以ESC开头的合法按键（比如F1-F12功能键），如果你的调试场景不需要功能键，这个方法也能用。