WezTerm 的 Kitty 键盘协议、CSI-u 与 Win32 输入模式如何选？

WezTerm 的 Kitty 键盘协议、CSI-u 与 Win32 输入模式如何选【免费下载链接】weztermA GPU-accelerated cross-platform terminal emulator and multiplexer written by wez and implemented in Rust项目地址: https://gitcode.com/GitHub_Trending/we/wezterm当你运行需要区分修饰键组合的 TUI 程序或在 Windows 上跑 Far Manager 这类 win32 控制台程序时发现按键行为不对问题往往出在键盘编码上。WezTerm 默认的 xterm 兼容编码只生成按键按下事件且存在歧义——文档给出的例子是Control-I会被编码成 ASCII Tab应用无法区分它是 Tab 还是 CtrlI。WezTerm 提供了几种可切换的键盘编码机制xtermmodifyOtherKeys、CSI-ufixterms、Kitty 键盘协议、Windows 的 Win32 输入模式。本文基于 Keyboard Encoding 文档 和对应的配置项文档说明这几种机制的差异、官方推荐的取舍以及如何在配置中启用。四种机制分别解决什么问题以下事实均来自 docs/config/key-encoding.md默认xterm 兼容只生成按键按下不生成释放事件能表示 1980 年代终端硬件的按键集合Control修饰会移位按键的 ASCII 表示如Control-I变 Tab因此存在歧义。xtermmodifyOtherKeys自版本20221119-145034-49b9839f起支持当 wezterm 收到转义序列CSI 4;NmN为0、1或2时按 xterm 的 modifyOtherKeys 规则改变编码使应用能区分带修饰与不带修饰的按键。这是由应用程序发送序列主动触发的无需你在 wezterm 配置里开关。CSI-u / fixterms对应配置项enable_csi_u_key_encoding默认false。它来自 fixterms 方案试图解决编码歧义并表示更多修饰键但文档明确指出它有问题且以不向后兼容的方式改变部分按键的行为、应用无法检测或请求该行为因此文档不建议启用见 enable_csi_u_key_encoding。Kitty 键盘协议Kitty 终端在 CSI-u 基础上扩展了Comprehensive keyboard handling protocol。它允许应用程序主动请求不同程度的增强编码并能把CMD/Super/Windows等修饰键报告给应用。wezterm 是否响应这些请求由enable_kitty_keyboard控制默认false见 enable_kitty_keyboard自版本20220624-141144-bd1b7c5d起存在。Win32 输入模式仅 Windowsallow_win32_input_mode自版本20220624-141144-bd1b7c5d起默认true。此时 wezterm 会监听 Windows ConPTY 层生成的转义序列切换到对 win32 控制台应用兼容性最好的私有编码会生成按键释放事件并能区分左右位置的修饰键见 allow_win32_input_mode。按运行场景做选择文档给出的取舍依据可以归纳成这样优先级也来自 key-encoding.md你的情况选择依据Windows 上运行 Far Manager 等 win32 控制台程序allow_win32_input_mode默认已开启无需配置该模式提供对 win32 控制台应用的最佳兼容性应用支持 Kitty 键盘协议需要CMD/Super/Windows修饰键或按键释放enable_kitty_keyboard true协议允许应用按自身需求请求不同程度的增强而不是全局一刀切应用只发CSI 4;Nm序列无需配置 modifyOtherKeys应用序列即触发这是 xterm 既有机制wezterm 直接响应想用 fixterms 编码文档不建议向后不兼容地改变部分按键行为且应用无法检测/请求该行为优先级关系在文档中有明确说明enable_csi_u_key_encoding与allow_win32_input_mode都优先于modifyOtherKeys 的行为allow_win32_input_mode又优先于enable_csi_u_key_encoding。也就是说如果多个机制同时开启Windows 上实际生效的是 Win32 输入模式。因此实际决策路径很短默认配置已经覆盖大多数场景只有当你要运行的应用走 Kitty 键盘协议、而你希望 wezterm 响应其增强请求时才需要打开enable_kitty_keyboardCSI-u 是文档明确不推荐的选项除非你清楚知道自己在做什么。在 wezterm 配置中启用 Kitty 键盘协议WezTerm 用 Lua 配置文件文档推荐放在$HOME/.wezterm.luaWindows 上是%USERPROFILE%/.wezterm.lua。按 Configuration 文档 的 Quick Start 结构最小写法如下-- ~/.wezterm.lua local wezterm require wezterm local config wezterm.config_builder() -- 让 wezterm 响应 kitty 键盘协议的转义序列 config.enable_kitty_keyboard true return config注意该选项默认是false不开启时 wezterm 不会响应应用发起的编码增强请求。如果你要的是文档不推荐的 CSI-u 编码对应写法是config.enable_csi_u_key_encoding true同样默认false但再次强调文档不建议这样做。Windows 上的 Win32 输入模式默认即为true一般不需要写任何配置。让配置生效并检查wezterm 会监视配置文件的变更文件改动后配置会自动重新加载大多数选项立即生效也可以用CTRLSHIFTR快捷键强制重新加载见 files.md。也可以用命令行临时覆盖无需改文件wezterm --config enable_kitty_keyboardtrue文档明确说明通过命令行指定的配置始终覆盖配置文件中的值即使配置文件随后被重新加载。如果候选配置文件存在但解析失败wezterm 会显示错误并改用内置默认配置当前所有版本的行为。所以改完配置后启动时留意是否出现错误提示是判断配置是否真正被加载的直接信号。wezterm show-keys会打印基于你配置文件的完整按键绑定集含各 key table 和鼠标绑定可用于确认当前生效的配置内容它的输出展示的是按键绑定不是键盘编码本身见 show-keys 文档。各模式生效后的可观察行为文档描述了各机制生效后应用侧能观察到的差异可用来判断模式是否按预期工作Kitty 协议enable_kitty_keyboard true应用可以请求不同程度的增强编码CMD/Super/Windows等修饰键能被报告给应用。Win32 输入模式Windows 默认会生成按键释放事件并能区分左右修饰键。modifyOtherKeys应用能区分带修饰与不带修饰的按键按下。默认 xterm 编码下没有上述能力且Control-I之类的组合与 Tab 无法区分。已知问题与限制modifyOtherKeys 状态残留changelog 记录过一个问题——ResetTerminalRIS此前不会重置modifyOtherKeys状态一个以该状态启用后非正常退出的程序可能让 Ctrl 键持续输出 shell 不认识的转义序列。修复后 RIS 会同时重置 modifyOtherKeys 状态以及左右边距模式和 bidi 状态。如果你遇到过退出某个程序后 Ctrl 组合键行为异常可对照这条确认你的版本是否包含该修复。CSI-u 的取舍是永久性的限制启用enable_csi_u_key_encoding后应用无法检测这一行为变化也没有请求/协商机制这是文档给出的不推荐核心理由。协议响应是开关式的Kitty 协议由应用侧请求、wezterm 侧按enable_kitty_keyboard决定是否响应Win32 模式由 ConPTY 层序列触发、wezterm 按allow_win32_input_mode决定是否响应。两者都默认处于Kitty 不响应、Win32 响应的状态跨平台时注意这一差异。相关文档Keyboard Encoding 总览enable_kitty_keyboardenable_csi_u_key_encodingallow_win32_input_modeConfiguration 文件结构与加载逻辑【免费下载链接】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），仅供参考