VSCode 里的 Vim 插件安装后没有反应？别急着怀疑配置文件写错了。90% 的情况下，问题并不在于你少配了哪个选项，而是插件根本没有进入真正的工作状态。想让 Vim 在 VSCode 里乖乖听话，得先通过三道关卡：打开一个真实文件、把冲突的快捷键清理干净、再确认系统剪贴板能打通。少一步，效果都出不来。
先说第一条，也是最容易被忽略的——你必须先打开一个真实文件，而不是停留在欢迎页或资源管理器面板里。VSCode Vim 插件只在编辑器获得焦点时才会激活，空窗口下它压根不工作。
按 Esc 没反应？先检查快捷键劫持
按下 Esc 键，光标毫无反应？这通常不是插件没加载，而是你的按键在进入 Vim 状态之前，已经被 VSCode 自身抢走了。默认情况下，VSCode 把 Esc 分配给了两条命令：workbench.action.showCommands（打开命令面板）和 workbench.action.terminal.toggleTerminal（切换终端）。它们优先级高于 Vim 插件监听，直接截断了按键信号。
- 打开快捷键设置：
Ctrl+K Ctrl+S（Windows/Linux）或Cmd+K Cmd+S（macOS） - 搜索
escape，找到上述两条命令，右键 →「删除键绑定」 - 检查
vim.useCtrlKeys是否设置为true（在远程开发环境下，它常被默认设为false） - 执行
Developer: Reload Window让配置生效，无需重启整个 VSCode
jj 或 jk 退出插入模式怎么配？必须写进 keybindings.json
习惯用 jj 或 jk 退出插入模式？这个映射的配置方式，和你平时想的不太一样。它本质上是一个在插入模式下监听的按键序列，普通的 UI 设置界面没法处理，也不能放在 settings.json 的 vim.insertModeKeyBindings 里——那个字段只对 Vim 插件的内部命令有效，而 extension.vim_escape 是一条扩展级别的命令，必须通过 VSCode 原生的快捷键机制来定义。
- 执行
Preferences: Open Keyboard Shortcuts (JSON) - 在数组里添加以下配置（注意 JSON 格式，逗号分隔、大小写敏感）：
{ "key": "j j", "command": "extension.vim_escape", "when": "editorTextFocus && vim.mode == 'InsertMode'"}
vim.mode == 'InsertMode' 不能用 'insert' 或 '-- INSERT --' 代替，字符串值必须完全匹配console.log(vimState)。如果报 ReferenceError，说明插件根本没加载复制粘贴不走系统剪贴板？vim.useSystemClipboard 必须开启
在 Vim 里用 y 复制，切换到浏览器按 Ctrl+V 却贴不出来？或者从外部复制内容，回到 Vim 按 p 毫无反应？这不是 Bug，而是 VSCode-Vim 的默认行为：它使用内部寄存器（以 " 开头），与系统剪贴板物理隔离。
- 在
settings.json中添加："vim.useSystemClipboard": true - macOS 用户注意：还要到「系统设置 → 隐私与安全性 → 辅助功能」里，手动给 VSCode 授权
- 如果你在 WSL 或 Remote-SSH 环境下工作，需要确保
DISPLAY变量或 X11 转发正常，否则unnamedplus寄存器行为不可用 - 千万别指望在
.vimrc里写set clipboard=unnamedplus——vscodevim 根本不解析这行配置，写了也白写
自定义 nnoremap 不生效？别指望它读取 .vimrc
vscodevim 不是真正的 Vim 进程，它不运行 .vimrc。所有你在原生 Vim 里写过的 nnoremap、inoremap 等映射，都必须手动转换成 JSON 格式才能用，而且语法完全不兼容。
- 使用
vim.normalModeKeyBindingsNonRecursive字段，避免递归展开引发意想不到的行为 before字段是一个按键数组，比如[" ", "f", "f"]，不能写成"ff" commands字段只能填 VSCode 的命令 ID（例如"workbench.action.files.newUntitledFile"）或扩展命令（例如"extension.vim_noHighlight"），不支持:nohlsearch这类 Ex 命令leader键慎用\——中文输入法下它经常被吞掉。改用,或space会更稳定，对应配置是"vim.leader": ","
总的来说，真正卡住你的点，往往不是配置本身写错了，而是插件模式有没有被激活、编辑器的焦点是否落在内容区、以及系统层级的权限有没有到位。特别是 macOS 的辅助功能授权和 WSL 下的剪贴板桥接——这些环节一旦漏掉，就算你把键位映射写得再精致，效果也出不来。
