Vim + iTerm2 鼠标配置指南¶

状态: ✅ 已完成

创建日期: 2026-02-19
最后更新: 2026-02-19

问题背景¶

在 iTerm2 中使用 vim 时，鼠标滚轮无法滚动内容。

排查过程¶

1. 检查 `~/.vimrc`¶

当时 vimrc 完整内容如下，没有任何 mouse 相关配置：

set number
set autoindent
set tabstop=4
set shiftwidth=4
syntax on
set fileencoding=utf-8
set fileencodings=utf-8,ucs-bom,gb18030,gbk,gb2312,cp936
set autowrite

Vim 默认不启用鼠标支持，因此鼠标滚动完全无效。

2. 检查 iTerm2 配置¶

通过 defaults read com.googlecode.iterm2 检查 XIN profile 的鼠标相关设置：

"Mouse Reporting" = 1                              ← 已开启（正常）
"Restrict Mouse Reporting to Alternate Screen Mode" = 0   ← 不限制
"Option Key Sends" = 2                             ← Left ⌥ 发送 Esc+ 序列
"Right Option Key Sends" = 2                       ← Right ⌥ 也发送 Esc+ 序列

iTerm2 侧配置正常，Mouse Reporting 已开启，TERM=xterm-256color 类型也正确。

根本原因¶

层面	状态	原因
Vim	❌ 缺失	没有 `set mouse=a`，Vim 默认不处理鼠标事件
iTerm2	✅ 正常	Mouse Reporting 已开启，终端类型正确

解决方案¶

第一步：启用 Vim 鼠标支持¶

在 ~/.vimrc 添加：

set mouse=a

mouse=a 在所有模式（normal / insert / visual / command-line）下启用鼠标，包括滚轮滚动和点击定位。

第二步：解决鼠标选择复制冲突¶

启用 set mouse=a 后，Vim 会捕获所有鼠标事件，导致原来"直接鼠标拖拽 → Cmd+C 复制"的工作流失效。

根本原因：Option Key Sends = 2 表示 ⌥ 键被配置为发送 Esc+ 序列（用于 alt-b/alt-f 等 shell 快捷键）。这使得 iTerm2 无法将 ⌥+鼠标事件识别为"绕过 Mouse Reporting"的信号。

修复方法：在 iTerm2 Preferences 中，将 XIN profile 的 Right Option Key 改为 Normal：

Preferences → Profiles → XIN → Keys → Right Option Key → Normal

Left ⌥：保持 Esc+，继续用于 shell 快捷键（alt-b、alt-f 等）
Right ⌥：改为 Normal，用于 iTerm2 原生文本选择的 bypass

操作方式（最终工作流）¶

操作	效果
鼠标滚轮	Vim 内正常滚动
鼠标拖拽（无修饰键）	Vim Visual 模式选择
Right ⌥ + 鼠标拖拽	绕过 Mouse Reporting，系统级原生选择 → `Cmd+C` 复制

注意：在 Vim 中滚动后，可能停留在 Visual 模式。需要先单击一下退出 Visual 模式，再按住 Right ⌥ 进行文本选择，否则 ⌥ bypass 可能不生效。

最终 `~/.vimrc` 相关配置¶

set mouse=a

（其余原有配置保持不变）

环境信息¶

macOS + iTerm2
iTerm2 Profile：XIN（JetBrains Mono 14px，50 行）
TERM=xterm-256color
TERM_PROGRAM=iTerm.app