which-key.nvim 插件中的键映射更新机制缺陷分析与修复方案

问题背景

在 Neovim 生态系统中，which-key.nvim 是一个非常受欢迎的插件，它能够实时显示可用的键绑定及其对应的功能描述。然而，近期发现该插件在处理动态键映射更新时存在一个关键缺陷：当用户删除某个键映射后，插件仍然会在帮助窗口中显示该映射。

问题现象

具体表现为：

1. 当用户通过 vim.keymap.set 添加一个缓冲区局部键映射时，which-key 能够正确显示
2. 但当使用 vim.keymap.del 删除该映射后，which-key 仍然保留该键映射的显示
3. 这个问题不仅影响缓冲区局部映射，也影响全局键映射

技术分析

深入分析 which-key.nvim 的源代码后发现，问题根源在于 Keys.update_keymaps 函数的实现逻辑。该函数目前只负责添加新的键映射到内部树结构中，但从未执行任何清理操作。具体表现为：

1. 内部使用树形结构(Tree)存储键映射信息
2. 每次更新时只是简单追加新映射，不清理已删除的映射
3. 对于已注册的钩子(hook)函数也没有进行相应清理

解决方案

经过多次实验，发现有效的修复方案需要同时处理两个方面：

1. 清理现有的树结构：在每次更新前重置树对象
2. 移除已注册的钩子：遍历现有树结构，取消所有已注册的钩子

核心修复代码如下：

function M.update_keymaps(mode, buf)
  -- 获取当前键映射
  local keymaps = buf and vim.api.nvim_buf_get_keymap(buf, mode) or vim.api.nvim_get_keymap(mode)

  -- 清理现有树结构和钩子
  do
    local function unhook(node)
      if node.mapping and M.is_hooked(node.mapping.prefix, mode, buf) then
        M.hook_del(node.mapping.prefix, mode, buf)
      end
    end
    M.get_tree(mode, buf).tree:walk(unhook)
    M.get_tree(mode, buf).tree = Tree:new()
  end

  -- 后续处理逻辑...
end

技术影响

这个修复对于 which-key.nvim 用户来说具有重要意义：

1. 解决了动态键映射场景下的显示一致性问题
2. 特别有利于那些需要频繁注册/注销键映射的复杂配置
3. 提升了插件的整体稳定性和可靠性

最佳实践建议

对于使用 which-key.nvim 的用户，建议：

1. 关注插件的更新，及时获取修复版本
2. 在自定义键映射时，注意使用标准的注册/注销方法
3. 对于复杂的键映射场景，考虑使用命名空间来管理

总结

键映射管理是 Neovim 插件生态中的核心功能之一，which-key.nvim 作为可视化键映射的标杆插件，其稳定性和准确性至关重要。本次发现的更新机制缺陷及相应修复，进一步完善了插件的功能完整性，为用户提供了更可靠的键映射展示体验。