一、基础结构

导读：

1. 核心配置规则详解
2. 高级配置模式
3. LazyVim 配置（如使用发行版）
4. 调试与优化
5. 完整示例配置

Lazy.nvim 是目前 Neovim 生态中最流行的插件管理器，以其强大的延迟加载（Lazy Loading）机制和声明式配置著称，以下是完整的规则配置教程,涵盖从基础到高级的使用场景。

Lazy 通过 Spec（规格） 系统定义插件，每个插件是一个 Lua 表：

-- init.lua 或 lua/plugins/init.lua
require("lazy").setup({
  -- 基础形式：仅指定插件源
  "nvim-lua/plenary.nvim",
  -- 完整形式：带配置规则
  {
    "nvim-telescope/telescope.nvim",
    dependencies = { "nvim-lua/plenary.nvim" },
    config = function() 
      require("telescope").setup() 
    end,
  },
}, {
  -- 全局配置（可选）
  ui = { border = "rounded" },
  checker = { enabled = true }, -- 自动检查更新
})

---

核心配置规则详解

插件源（Source）

定义从哪里获取插件：

{
  -- GitHub 仓库（最常用）
  "用户名/仓库名",
  -- 指定分支/标签/提交
  "nvim-treesitter/nvim-treesitter", 
  branch = "main",           -- 指定分支
  version = "^5.0",          -- 语义化版本
  commit = "abc123",         -- 固定提交
  tag = "stable",            -- 指定标签
  -- 本地插件
  dir = "~/projects/my-plugin",
  -- 非 Git 源（罕见）
  url = "https://gitlab.com/.../repo.git",
}

延迟加载条件（Lazy Loading）

这是 Lazy 的核心，控制何时加载插件：

{
  "插件作者/插件名",
  -- 按事件加载（最常用）
  event = "VeryLazy",           -- 在启动后延迟加载
  event = { "BufReadPost", "BufNewFile" }, -- 打开文件时
  event = "InsertEnter",        -- 进入插入模式
  -- 按命令加载
  cmd = "Telescope",            -- 首次执行命令时
  cmd = { "TSUpdate", "TSInstall" }, -- 多个命令
  -- 按文件类型加载
  ft = "python",                -- 打开 Python 文件时
  ft = { "lua", "vim" },
  -- 按快捷键加载（懒加载+定义快捷键）
  keys = {
    { "<leader>f", "<cmd>Telescope find_files<cr>", desc = "查找文件" },
    { "<leader>g", "<cmd>Telescope live_grep<cr>", mode = "n" }, -- 指定模式
  },
  -- 按模块加载（require 时）
  module = "nvim-tree",         -- 当 require("nvim-tree") 时
  -- 自定义条件函数
  cond = function()
    return vim.fn.has("nvim-0.9") == 1 -- 仅 Neovim 0.9+ 加载
  end,
  -- 或者简单布尔值
  cond = vim.fn.has("mac") == 1, -- 仅 MacOS
}

优先级建议：

• 纯工具类（如 plenary.nvim）：不设置延迟条件（立即加载）
• UI 插件：event = "VeryLazy"
• LSP 相关：event = { "BufReadPre", "BufNewFile" }
• 文件浏览器：cmd = "NvimTreeToggle" 或 keys = {...}

依赖管理（Dependencies）

自动安装并确保依赖先加载：

{
  "hrsh7th/nvim-cmp",
  dependencies = {
    -- 简单形式
    "hrsh7th/cmp-buffer",
    -- 复杂形式：依赖本身也有配置
    {
      "hrsh7th/cmp-nvim-lsp",
      dependencies = { "neovim/nvim-lspconfig" },
    },
    -- 仅作为依赖，不单独配置
    { "L3MON4D3/LuaSnip", lazy = true },
  },
}

配置执行时机（Config Hooks）

控制插件如何初始化：

{
  "插件名",
  -- init：在加载前执行（设置全局变量、自动命令等）
  init = function()
    vim.g.my_plugin_setting = true
  end,
  -- opts：传递给 config 函数的选项（推荐方式）
  opts = {
    setting_a = true,
    setting_b = "value",
  },
  -- config：加载后执行（setup 调用）
  -- 如果不定义，Lazy 会自动执行 require("插件名").setup(opts)
  config = function(plugin, opts)
    -- plugin: 插件元数据表
    -- opts: 上面定义的 opts
    require("插件名").setup(opts)
    -- 额外配置
    vim.keymap.set("n", "<leader>x", "<cmd>...<cr>")
  end,
  -- 完全禁用自动 setup（当插件没有 setup 函数时）
  config = false,
}

最佳实践：优先使用 opts，只有需要复杂逻辑时才写 config 函数。

加载优先级（Priority）

控制插件加载顺序（数字越大越先加载）：

{
  "nvim-tree/nvim-web-devicons",
  priority = 100, -- 确保在其他 UI 插件之前加载
}

---

高级配置模式

多规格合并（Import）

将配置分散到多个文件：

-- init.lua
require("lazy").setup({
  { import = "plugins.ui" },      -- 加载 lua/plugins/ui.lua
  { import = "plugins.lsp" },     -- 加载 lua/plugins/lsp.lua
  { import = "plugins.tools" },
})
-- lua/plugins/ui.lua
return {
  { "nvim-tree/nvim-tree.lua", config = true },
  { "akinsho/bufferline.nvim", event = "VeryLazy" },
}

条件插件（Optional Plugins）

根据环境动态启用：

{
  "iamcco/markdown-preview.nvim",
  ft = "markdown",
  -- 仅当系统有 npm 时才安装
  cond = function()
    return vim.fn.executable("npm") == 1
  end,
  build = "cd app && npm install", -- 安装后执行的命令
}

版本锁定（Pinning）

确保团队环境一致：

{
  "neovim/nvim-lspconfig",
  version = "*", -- 最新发布版（非 commit）
  pin = true,    -- 锁定当前版本，忽略更新
}

---

LazyVim 配置（如使用发行版）

如果你使用的是 LazyVim（基于 Lazy.nvim 的 Neovim 发行版）,配置方式略有不同：

-- lua/plugins/my-plugin.lua（LazyVim 结构）
return {
  "echasnovski/mini.nvim",
  version = "*",
  config = function(_, opts)
    require("mini.ai").setup(opts)
    require("mini.surround").setup()
  end,
}

关键区别：

• LazyVim 会自动合并 opts，所以通常只需返回 { opts = {...} }
• 使用 enabled = false 禁用默认插件
• 使用 dependencies 添加额外依赖

---

调试与优化

查看加载统计

运行 Lazy 打开 UI,可查看：

• Loaded：已加载的插件
• Not Loaded：未加载（成功延迟）
• Start Time：启动耗时

性能分析

-- 在 setup 前添加
vim.api.nvim_create_autocmd("User", {
  pattern = "VeryLazy",
  callback = function()
    -- 启动完成后执行，测量实际启动时间
    print("Startup time: " .. vim.fn.reltimefloat(vim.fn.reltime(vim.g.start_time)))
  end,
})

常见错误排查

• 循环依赖：确保 dependencies 不互相引用
• 过早加载：检查是否有其他插件 require 了未延迟加载的模块
• 配置不生效：确认 config 函数是否在 event 触发后执行

---

完整示例配置

-- lua/plugins/example.lua
return {
  -- 示例1：简单延迟加载
  {
    "tpope/vim-surround",
    event = "VeryLazy", -- 启动后加载
  },
  -- 示例2：带依赖和自定义配置
  {
    "nvim-telescope/telescope.nvim",
    cmd = "Telescope",
    dependencies = {
      "nvim-lua/plenary.nvim",
      { "nvim-telescope/telescope-fzf-native.nvim", build = "make" },
    },
    opts = {
      defaults = {
        layout_strategy = "horizontal",
      },
    },
    config = function(_, opts)
      require("telescope").setup(opts)
      require("telescope").load_extension("fzf")
    end,
  },
  -- 示例3：文件类型特定
  {
    "fatih/vim-go",
    ft = "go",
    build = ":GoUpdateBinaries",
    config = function()
      vim.g.go_fmt_command = "gofumpt"
    end,
  },
}

掌握这些规则后，你可以构建出启动速度极快（< 50ms）且模块化的 Neovim 配置，建议从简单的 event = "VeryLazy" 开始,逐步细化加载条件。