nvim config lua

Lua 配置和包管理说明

1. Lua 模块系统基础

1.1 什么是 Lua 模块？

在 Neovim 中，Lua 模块是通过 require() 函数加载的代码文件

基本语法：

local module = require("模块名")

1.2 模块路径解析规则

Neovim 会在 runtimepath (rtp) 中查找 Lua 模块。路径规则如下：

-- 查找 lua/config/options.lua
require("config.options")

关键点：

• 点号 (.) 表示目录分隔符
• lua/ 目录是自动添加的前缀
• 不需要写 .lua 扩展名

2. Neovim 的 runtimepath (rtp)

2.1 什么是 runtimepath？

runtimepath 是 Neovim 查找配置文件的路径列表。你的配置目录会自动添加到 rtp 中

查看当前 runtimepath：

:lua print(vim.inspect(vim.opt.rtp:get()))

3. 路径解析示例

3.1 正确的路径写法

require() 调用	实际查找的文件路径
require("config.options")	lua/config/options.lua ✅
require("config.keymaps")	lua/config/keymaps/init.lua ✅
require("config.autocmd")	lua/config/autocmd/init.lua ✅
require("plugins.specs.code.blink")	lua/plugins/specs/code/blink.lua ✅
require("plugins.manager")	lua/plugins/manager/init.lua ✅
require("pack")	lua/pack/init.lua ✅
require("vv-utils.xxx")	vendors/vv-utils.nvim/lua/vv-utils/xxx.lua ✅（vendor 在 rtp 上）

3.2 错误的路径写法

-- ❌ 错误：不要包含 .lua 扩展名
require("config.options.lua")

-- ❌ 错误：不要包含 lua/ 前缀
require("lua.config.options")

-- ❌ 错误：不要使用反斜杠或斜杠
require("config/options")
require("config\\options")

-- ✅ 正确：使用点号分隔
require("config.options")

4. 你的配置检查

4.1 init.lua 中的路径设置 ✅

init.lua 顶部：

vim.opt.rtp:prepend(vim.fn.stdpath("config"))

Neovim 默认会把标准配置目录加入 runtimepath；这行配置进一步确保它位于搜索顺序最前面。随后 Neovim 可以从 runtimepath 中找到：

• lua/config/ 目录下的文件
• lua/plugins/ 目录下的文件
• lua/pack/ 目录下的文件
• 已加入 runtimepath 的插件及 vendor 中的 lua/ 目录

5. 插件管理（基于 vim.pack）

本配置不使用 lazy.nvim，而是基于 Neovim 0.12+ 的原生 vim.pack API 自建了一套「one-file-per-plugin spec + 懒加载 + GUI 管理」系统（仿 LazyVim 设计）

• 引擎层：lua/pack/（init.lua 是入口，被 require("pack") 驱动）
• spec 目录：lua/plugins/specs/（每个插件一个文件，声明 id / url / deps / 懒加载触发器 / opts / config / build）
• 管理 GUI：lua/plugins/manager/（:PluginManager 浮窗）
• 禁用集合：lua/plugins/manager/user-picks.lua（只记录 [id] = false，默认全启用）

插件的注册格式、懒加载规则、添加/删除步骤详见 AGENTS.md

6. 常见问题

Q1: 如何测试模块是否能被找到？

在 Neovim 中运行：

:lua print(package.searchpath("config.options", package.path))

如果返回路径，说明模块可以被找到

Q2: 如何查看已加载的模块？

:lua print(vim.inspect(package.loaded))