如何防止Electron吞噬按键 避免屏蔽屏幕阅读器等辅助工具快捷键

核心原因 #

Electron在Linux桌面环境下默认的键盘事件处理逻辑，会优先在应用层消费所有捕获到的按键事件，默认未开启辅助功能相关的事件透传通道，导致Orca屏幕阅读器这类依赖系统全局快捷键、AT-SPI辅助总线的工具无法接收到按键事件，表现为应用聚焦时全局快捷键失效。 #

推荐解决方案（无硬编码按键列表，适配自定义快捷键场景） #

适用于Electron 14及以上版本（所有官方维护的LTS版本均支持），不需要维护任何允许透传的按键清单，系统会自动识别全局快捷键并完成透传：

1. 主进程初始化阶段，在app.whenReady()调用前追加命令行开关，开启辅助功能键盘事件透传

const { app } = require('electron')
// 开启辅助功能键盘事件上报，所有按键事件会先同步给系统辅助总线
app.commandLine.appendSwitch('enable-accessibility-keyboard-events')
// Wayland环境下自动适配平台规则，避免合成器层面的事件拦截
app.commandLine.appendSwitch('ozone-platform-hint', 'auto')

2. 创建应用窗口时，显式开启渲染进程的辅助功能支持，不要使用默认的自动检测配置

const mainWindow = new BrowserWindow({
  // 你原有窗口配置项，比如宽高、图标等
  webPreferences: {
    // 保留你原有webPreferences配置，比如preload路径、上下文隔离开关等
    accessibilitySupport: 'enabled'
  }
})

该方案的透传逻辑由系统AT-SPI总线完成判定：所有被注册为全局快捷键的按键组合，会直接被系统/对应全局应用消费，不会流入Electron的应用事件队列；普通应用内按键事件逻辑完全不受影响，不管用户怎么修改全局快捷键配置都能正常生效，不存在硬编码问题。

低版本兼容方案（Electron <14） #

如果项目暂时无法升级Electron版本，可以通过主进程的事件监听兜底，全程不对键盘事件做拦截操作，让事件自然冒泡到系统层：

app.whenReady().then(() => {
  const mainWindow = new BrowserWindow({ /* 你的窗口配置 */ })
  // 监听所有输入事件，不调用preventDefault拦截
  mainWindow.webContents.on('before-input-event', (event, input) => {
    // 不要在这里添加任何按键判断、拦截逻辑，直接放行
  })
})

注意：该兼容方案在部分Wayland桌面环境下存在透传失效的概率，优先升级Electron版本使用上述推荐方案 #

验证方式 #

打包启动应用后保持窗口聚焦，按下Insert+Space测试Orca配置面板唤起功能，同时测试其他自定义全局快捷键，确认不需要切出应用即可正常触发就说明配置生效。

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