WezTerm show-keys 命令完全指南导出并校验你的按键与鼠标绑定配置【免费下载链接】weztermA GPU-accelerated cross-platform terminal emulator and multiplexer written by wez and implemented in Rust项目地址: https://gitcode.com/GitHub_Trending/we/weztermwezterm show-keys是 WezTerm 提供的一个命令行工具用于根据你当前的配置文件打印出完整生效的按键分配集合——包括默认按键表、所有自定义 key table 以及全部鼠标绑定。读完本文你将掌握该命令的两种输出模式、各参数的精确语义并学会用它在排错、迁移配置和审查快捷键冲突时快速拿到权威依据。该命令自20220624-141144-bd1b7c5d版本起可用属于 WezTerm GUI 侧的子命令其 CLI 定义位于 wezterm-gui-subcommands/src/lib.rs。命令作用查看实际生效的按键分配WezTerm 的按键行为由三部分共同决定内置默认绑定、你的wezterm.lua配置中的keys/key_tables/mouse_bindings以及运行时的模式切换如 copy_mode、search_mode。wezterm show-keys的价值在于它不是简单罗列默认值而是加载你的配置文件后输出真正会生效的最终按键表。它展示每一个 key table按键表它同时展示完整的鼠标绑定集合它会先加载配置config::ConfigHandle再构建InputMap输出因此结果与你的实际运行环境一致。底层实现位于 wezterm-gui/src/inputmap.rs 的show_keys()方法与 wezterm-gui/src/main.rs 的run_show_keys()函数。从源码结构可以推断该命令依赖 GUI 进程执行在 wezterm/src/main.rs 中ShowKeys与其他 GUI 子命令一起通过delegate_to_gui委托给wezterm-gui处理因此即使你只想查按键表也请确保安装的是完整版 WezTerm而非仅 CLI 组件。配置项在源码中的归并逻辑要理解输出内容需要先知道这些按键绑定从何而来。在 config/src/config.rs 中配置中的keys数组被归并进名为default的按键表配置中的key_tables映射被逐个构建为独立命名表归并时会对每个按键执行resolve(self.key_map_preference)与normalize_shift(...)即根据你设置的key_map_preference解析物理/逻辑键并对 Shift 组合做规范化处理每一条目最终以(key, mods) - KeyTableEntry { action }的形式存储show-keys输出的正是这张归并后的KeyTable。这意味着如果你在配置中为CTRLShiftX做了绑定而该按键经过normalize_shift被规范化show-keys会以规范化后的最终形态打印这恰恰是排查我明明绑定了却没生效类问题的关键线索。输出格式详解命令默认输出为人类可读的文本表格按区块组织。完整示例如下来自 docs/cli/show-keys.mdDefault key table ----------------- CTRL Tab - ActivateTabRelative(1) SHIFT | CTRL Tab - ActivateTabRelative(-1) ... Key Table: copy_mode -------------------- Tab - CopyMode(MoveForwardWord) SHIFT Tab - CopyMode(MoveBackwardWord) SHIFT $ - CopyMode(MoveToEndOfLineContent) ... Key Table: search_mode ---------------------- Enter - CopyMode(PriorMatch) Escape - CopyMode(Close) CTRL n - CopyMode(NextMatch) ... Mouse ----- Down { streak: 1, button: Left } - SelectTextAtMouseCursor(Cell) SHIFT Down { streak: 1, button: Left } - ExtendSelectionToMouseCursor(None) ALT Down { streak: 1, button: Left } - SelectTextAtMouseCursor(Block) ...输出区块按以下顺序排列与 show_keys() 的实现顺序一致Leader若你的配置定义了leader键会先打印Leader: 键 修饰键 时长例如Leader: LeftControl MODS_NONE 1sDefault key table默认按键表即不处于任何自定义模式时生效的绑定Key Table:每个自定义 key table 一个区块按键表名按字典序排序输出Mouse鼠标绑定区块。字段语义修饰键列逗号分隔的修饰键集合如CTRL、SHIFT | CTRL、ALT。无修饰键时该列为空源码中Modifiers::NONE渲染为空字符串见 show_key_table()。按键列经过人类可读化human_key的键名如Tab、$、n、Enter、Escape。动作列Debug 格式的KeyAssignment例如ActivateTabRelative(1)、CopyMode(MoveForwardWord)、SelectTextAtMouseCursor(Cell)。动作括号内的参数与 config/src/keyassignment.rs 中定义的KeyAssignment枚举一一对应可作为你配置wezterm.action时的权威参考。表格各列宽度会按内容动态对齐代码中通过计算mod_width、key_width最大值实现便于阅读。鼠标绑定为何分四组输出show_keys()中的show_mouse()方法wezterm-gui/src/inputmap.rs会把鼠标绑定按四种场景分组过滤后分别打印Mouse普通屏幕下生效的绑定Mouse: alt_screen备用屏幕如 vim、less 全屏应用下生效的绑定Mouse: mouse_reporting程序开启鼠标上报如 TUI 应用时生效的绑定Mouse: mouse_reporting alt_screen两者叠加时的绑定。每个鼠标触发事件由(trigger, mods)二元组构成其中mods携带alt_screen与mouse_reporting两个标志位。这与 MouseEventTriggerMods 的lookup_mouse()查询逻辑一致输出时按标志位过滤、按键按字典序BTreeMap排序空分组自动跳过。这意味着同一组鼠标按键可能在不同场景绑定不同动作show-keys可以帮你逐组核对。命令参数完整用法来自 docs/examples/cmd-synopsis-wezterm-show-keys--help.txtShow key assignments Usage: wezterm show-keys [OPTIONS] Options: --lua Show the keys as lua config statements --key-table KEY_TABLE In lua mode, show only the named key table -h, --help Print help参数语义与源码定义wezterm-gui-subcommands/src/lib.rs对照如下参数类型默认值作用--lua布尔开关关闭以 Lua 配置语句形式输出按键绑定输出结果可直接作为wezterm.lua配置片段使用--key-table KEY_TABLE字符串无仅在--lua模式下生效只输出指定名称的 key table-h, --help布尔开关—打印命令帮助注意--key-table依赖--lua。若单独使用--key-table而不带--lua由于非 Lua 模式走show_keys()分支、会忽略该参数见 run_show_keys 中if cmd.lua { ... } else { map.show_keys() }的分支逻辑因此实际使用时请始终两者搭配。实战场景一Lua 模式导出完整按键配置wezterm show-keys --lua的输出是一段可以直接写回配置文件的 Lua 代码。其生成逻辑在dump_config()wezterm-gui/src/inputmap.rslocal wezterm require wezterm local act wezterm.action return { keys { -- 默认按键表每条形如 -- { key Tab, mods CTRL, action act.ActivateTabRelative(1) }, }, key_tables { copy_mode { -- 自定义按键表条目 }, search_mode { -- ... }, } }这个输出结构的意义在于它把当前配置解析后的最终按键集合翻译成标准的{ key ..., mods ..., action act.... }条目。当你准备从零重写配置文件、或想把自己调整过的绑定迁移到另一台机器时可以运行wezterm show-keys --lua将输出中的keys与key_tables内容复制为新的配置骨架在此基础上继续增量修改。该模式默认输出全部按键表若只想查看某个特定表例如只想导出copy_mode使用wezterm show-keys --lua --key-table copy_mode此时输出中keys区块会被省略key_tables中仅保留名为copy_mode的表对应dump_config中key_table.is_none()与name ! wanted_table的过滤逻辑。Lua 化的动作参数在--lua模式下每个按键动作会被lua_key()/luaify()序列化为wezterm.action的调用形式wezterm-gui/src/inputmap.rs。字符串会经过quote_lua_string转义嵌套结构会递归格式化因此导出的结果既可用于阅读也保留了可直接评估的合法性——当你对某个动作的参数形式拿不准时先用show-keys --lua看 WezTerm 自己是怎么写的再照搬到配置里可以显著减少手写错误。实战场景二键盘与鼠标绑定排错官方排错指南docs/troubleshooting.md明确推荐使用本命令定位键盘相关问题。典型排查流程确认按键确实被 WezTerm 捕获在配置中开启debug_key_events参见 docs/config/lua/config/debug_key_events.md以记录按键事件日志查看最终生效的绑定运行wezterm show-keys检查你的目标按键是否以预期的修饰键组合出现在对应 key table 中若绑定缺失或修饰键与预期不符检查normalize_shift与key_map_preference的影响——这也是show-keys打印的形态可能与你配置书写形态不完全一致的原因同时核对--lua输出确认动作参数与wezterm.action的期望形式一致。此外若你怀疑是系统级快捷键拦截如输入法、窗口管理器占用也可以先用show-keys确认 WezTerm 侧绑定无误再转向排查外部拦截因素。默认按键表与搜索/复制模式的完整绑定还可以对照 docs/config/default-keys.md、docs/config/mouse.md 与 docs/copymode.md 交叉验证。常见问题Qshow-keys输出与我的配置不完全一致A这是预期行为。输出是配置解析并归一化resolvenormalize_shift后的最终形态而非原始书写形态同时leader、key_map_preference等配置都会影响最终按键表。Q为什么--key-table不生效A--key-table仅在--lua模式下有意义请使用wezterm show-keys --lua --key-table 名称的形式。Q输出里没有显示我的某个鼠标绑定A鼠标绑定按alt_screen与mouse_reporting四种场景分组请检查你的绑定属于哪一组并确认该组非空才会打印空分组会被跳过。Qshow-keys需要 GUI 环境吗A从源码结构看该命令由wezterm-gui二进制处理主程序通过delegate_to_gui委托因此建议在完整安装 WezTerm 的环境中使用。小结wezterm show-keys是把配置中的按键/鼠标声明与运行时真实生效的绑定对齐起来的关键工具默认文本模式适合人工审查与排错--lua模式适合导出可复用的配置骨架--key-table则让定位特定模式copy_mode、search_mode 等的绑定变得精准高效。配合debug_key_events与 docs/config/default-keys.md 中的默认绑定清单你可以快速定位绝大多数按键失效或冲突问题。【免费下载链接】weztermA GPU-accelerated cross-platform terminal emulator and multiplexer written by wez and implemented in Rust项目地址: https://gitcode.com/GitHub_Trending/we/wezterm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考