【LunarVim】解决which-key 自定义键位注册不成功问题

问题描述

LunarVim将which-key设置放在一个keymaps.lua中，然后config.lua调用reload “user.keymaps”，键位没用注册成功，而直接写在config.lua中，就注册成功

这暴露了LunarVim 插件和配置加载顺序的一些细节坑，下面解释为什么把 which_key 设置放在外部模块中反而失效了：

🧠 为什么 which_key 配置放在外部文件中（如 keymaps.lua）不生效？

✅ 核心原因：加载时机与模块作用域的问题

LunarVim 是 基于模块化的 Lua 启动流程，其 config.lua 实际上是在某个生命周期阶段被执行的。你通过 reload "user.keymaps" 这种方式 动态加载一个模块，但这个模块可能会：

1. 在 which-key 插件加载前执行，这时还没初始化好注册系统。
2. 被 reload() 调用时，是运行时注册，而不是在 which_key 初始化期间注册。
3. 被重新加载的模块 作用域不同，可能不会影响全局配置表 lvim.builtin.which_key.mappings，特别是如果模块中你用的是局部表。

📦 举个直观的类比：

-- config.lua
reload("user.keymaps")  -- 加载时 which-key 还没准备好

-- keymaps.lua
lvim.builtin.which_key.mappings["P"] = {...}

这个时候可能出现两种情况：

1. which-key 还没加载：你修改的是一个还不存在的表项，或者被后续清除。
2. 模块作用域限制：模块中如果用 local 定义表或变量，或者没有写对注册的路径，which-key 是注册不到的。

✅ 推荐做法：统一在 config.lua 中设置 which_key 映射

LunarVim 官方和社区的推荐写法就是 所有 lvim.builtin.xxx 相关配置（包括 which_key）都写在主配置文件中，因为它们依赖启动顺序，涉及插件初始化。

✅ 进阶做法：仍然可以模块化，但要注意调用时机

如果你想保持结构清晰，把映射分模块写，其实是可以的，只要你小心点方式。例如：

-- ~/.config/lvim/lua/user/keymaps.lua
local M = {}

function M.setup()
  local wk = lvim.builtin.which_key

  wk.mappings["P"] = { "<cmd>Telescope projects<CR>", "Projects" }
  wk.mappings["t"] = {
    name = "+Trouble",
    r = { "<cmd>Trouble lsp_references<cr>", "References" },
    f = { "<cmd>Trouble lsp_definitions<cr>", "Definitions" },
  }
end

return M

然后在 config.lua 中：

require("user.keymaps").setup()

这样它会在主配置文件加载过程中调用，确保执行顺序、作用域都正确。

✅ 小结：为什么直接写在 config.lua 就能用？

因为：

• 它跟随主配置同步初始化
• 插件加载顺序受控
• 全局 lvim.builtin 表没有丢失作用域或晚于注册