Neovim Lua开发：无法require含连字符的Lua模块问题

我正在开发一款Neovim插件，通过加载器函数传入指定模块的路径和名称。加载名称不含连字符的模块时一切正常，但加载名称含连字符的模块时，require无法成功加载。

代码示例 #

local function loadmodule(modulePath, moduleName)
    vim.opt.rtp:append(modulePath)

    package.loaded[moduleName] = nil
    require(moduleName)
end

loadmodule("path/to/module", "module-name")

错误信息 #

E5108: Error executing lua ./lua/script.lua:5: module 'module-name' not found:                                                                                                                                                                          
        no field package.preload['module-name']                                                                                                                                                                                                                      
cache_loader: module module-name not found                                                                                                                                                                                                                           
cache_loader_lib: module module-name not found                                                                                                                                                                                                                       
        no file './module-name.lua'                                                                                                                                                                                                                                  
        no file '/usr/share/luajit-2.1/module-name.lua'                                                                                                                                                                                                              
        no file '/usr/local/share/lua/5.1/module-name.lua'                                                                                                                                                                                                            
        no file '/usr/local/share/lua/5.1/module-name/init.lua'                                                                                                                                                                                                       
        no file '/usr/share/lua/5.1/module-name.lua'                                                                                                                                                                                                                 
        no file '/usr/share/lua/5.1/module-name/init.lua'                                                                                                                                                                                                             
        no file './module-name.so'                                                                                                                                                                                                                                   
        no file '/usr/local/lib/lua/5.1/module-name.so'                                                                                                                                                                                                              
        no file '/usr/lib/lua/5.1/module-name.so'                                                                                                                                                                                                                    
        no file '/usr/local/lib/lua/5.1/loadall.so'                                                                                                                                                                                                                          
        no file '/home/user/.config/nvim//lua/lib/lua/5.1/module-name.so'      

模块确实存在于runtimepath中，但Neovim无法找到。直接传入模块名称加载时，无连字符模块正常，含连字符模块失败。

解决方案 #

1. 检查模块文件路径与命名匹配

Lua的require函数会直接将模块名映射为文件名：

• 若使用require("module-name")，则模块文件必须是module-name.lua，且位于path/to/module/lua/目录下（Neovim会自动将rtp路径下的lua/目录加入Lua搜索路径）
• 若模块是目录结构，则需存在path/to/module/lua/module-name/init.lua

如果模块文件名为module_name.lua（下划线代替连字符），则必须使用require("module_name")加载，反之亦然。

2. 手动更新Lua搜索路径

仅修改vim.opt.rtp可能无法立即让Lua识别到新路径，可手动将模块路径下的lua/目录添加到package.path：

local function loadmodule(modulePath, moduleName)
    vim.opt.rtp:append(modulePath)
    -- 添加模块路径下的lua目录到Lua搜索路径
    local lua_search_path = string.format("%s/lua/?.lua;%s/lua/?/init.lua;", modulePath, modulePath)
    package.path = lua_search_path .. package.path

    package.loaded[moduleName] = nil
    local ok, err = pcall(require, moduleName)
    if not ok then
        error("加载模块失败: " .. err)
    end
end

3. 排查缓存或拼写问题

• 确保package.loaded[moduleName] = nil确实清除了缓存，避免旧缓存干扰
• 仔细核对模块名与文件名的大小写、连字符/下划线是否完全一致

内容的提问来源于stack exchange，提问作者DarkLSD_GuY