neovim

Neovim 配置技能

这是一份全面的指南，介绍如何使用基于 lazy.nvim 构建的模块化、高性能 Neovim 配置。

快速参考

指标	值
插件管理器	lazy.nvim
插件总数	82
目标启动时间	<50ms
模块模式	M.setup()
Leader 键	<Space>

架构概览

~/.config/nvim/
├── init.lua                  # Entry point
├── lua/
│   ├── config/               # Core configuration (11 modules)
│   │   ├── lazy.lua          # Plugin manager bootstrap
│   │   ├── options.lua       # Vim options
│   │   ├── keymaps.lua       # Key bindings
│   │   ├── autocmds.lua      # Autocommands
│   │   └── performance.lua   # Startup optimization
│   ├── plugins/specs/        # Plugin specs (9 categories)
│   │   ├── core.lua          # Foundation (plenary, nui, devicons)
│   │   ├── ui.lua            # UI (lualine, bufferline, noice)
│   │   ├── editor.lua        # Editor (autopairs, flash, harpoon)
│   │   ├── lsp.lua           # LSP (lspconfig, mason, conform)
│   │   ├── git.lua           # Git (fugitive, gitsigns, diffview)
│   │   ├── ai.lua            # AI (copilot, ChatGPT)
│   │   ├── debug.lua         # DAP (nvim-dap, dap-ui)
│   │   ├── tools.lua         # Tools (telescope, neo-tree)
│   │   └── treesitter.lua    # Syntax (treesitter, textobjects)
│   ├── kickstart/            # Kickstart-derived modules
│   └── utils/                # Utility functions
└── lazy-lock.json            # Plugin version lock

标准模块模式

所有配置模块都遵循 M.setup() 模式：

local M = {}

M.setup = function()
  -- Configuration logic here
end

return M

插件管理（lazy.nvim）

添加新插件

将插件添加到 lua/plugins/specs/ 中对应的分类文件：

-- lua/plugins/specs/tools.lua
return {
  -- Existing plugins...

  {
    "author/plugin-name",
    event = "VeryLazy",           -- Loading strategy
    dependencies = { "dep/name" }, -- Required plugins
    opts = {
      -- Plugin options
    },
    config = function(_, opts)
      require("plugin-name").setup(opts)
    end,
  },
}

加载策略

策略	使用时机	示例
lazy = true	默认设置，按需加载	大多数插件
event = "VeryLazy"	UI 加载后	UI 增强功能
event = "BufReadPre"	打开文件时	Treesitter、gitsigns
event = "InsertEnter"	输入时	补全、自动配对
cmd = "CommandName"	调用命令时	大型工具
ft = "filetype"	针对特定文件类型	语言插件
keys = {...}	按键时	移动插件

插件命令

命令	说明
:Lazy	打开 lazy.nvim 仪表板
:Lazy sync	更新并安装插件
:Lazy profile	显示启动时间分析
:Lazy clean	移除未使用的插件
:Lazy health	检查插件健康状态

LSP 配置

完整的 LSP 参考请参见 references/lsp.md。

LSP 技术栈

mason.nvim (installer)
    ├── mason-lspconfig.nvim → nvim-lspconfig
    ├── mason-tool-installer.nvim (auto-install)
    └── mason-nvim-dap.nvim → nvim-dap

nvim-lspconfig
    ├── blink.cmp (completion)
    ├── conform.nvim (formatting)
    ├── nvim-lint (linting)
    └── trouble.nvim (diagnostics)

添加 LSP 服务端

-- In lua/plugins/specs/lsp.lua, add to mason-tool-installer list:
ensure_installed = {
  "lua_ls",
  "pyright",
  "your_new_server",  -- Add here
}

-- Configure in lspconfig setup:
servers = {
  your_new_server = {
    settings = {
      -- Server-specific settings
    },
  },
}

LSP 快捷键

键	操作
gd	跳转到定义
gr	跳转到引用
gI	跳转到实现
gD	跳转到声明
K	悬停文档
<leader>rn	重命名符号
<leader>ca	代码操作
<leader>D	类型定义
<leader>ds	文档符号
<leader>ws	工作区符号

快捷键

完整参考请参见 references/keybindings.md。

核心导航

键	操作
<C-h/j/k/l>	窗口导航
<S-h> / <S-l>	上一个/下一个缓冲区
<leader>sf	搜索文件
<leader>sg	按 grep 搜索
<leader><space>	搜索缓冲区
\\	切换 Neo-tree

添加快捷键

-- In lua/config/keymaps.lua M.setup():
vim.keymap.set('n', '<leader>xx', function()
  -- Your action
end, { desc = 'Description for which-key' })

-- Or in a plugin spec:
keys = {
  { "<leader>xx", "<cmd>Command<CR>", desc = "Description" },
}

调试（DAP）

完整参考请参见 references/debugging.md。

DAP 快捷键

键	操作
<F5>	继续/开始调试
<F10>	单步跳过
<F11>	单步进入
<F12>	单步跳出
<leader>b	切换断点
<leader>B	条件断点

添加调试适配器

-- In lua/plugins/specs/debug.lua
local dap = require("dap")

dap.adapters.your_adapter = {
  type = "executable",
  command = "path/to/adapter",
}

dap.configurations.your_filetype = {
  {
    type = "your_adapter",
    request = "launch",
    name = "Launch",
    program = "${file}",
  },
}

性能优化

启动优化层

层	技术	节省时间
1	vim.loader.enable()	~50ms
2	跳过 vim._defaults	~180ms
3	禁用 providers	~10ms
4	禁用内置功能	~20ms
5	延迟配置	~30ms
6	基于事件加载	不定

分析启动性能

:Lazy profile

延迟加载模式

-- In init.lua
vim.defer_fn(function()
  require('config.options').setup()
  require('config.keymaps').setup()
  require('config.autocmds').setup()
end, 0)

常见任务

添加自动命令

-- In lua/config/autocmds.lua M.setup():
vim.api.nvim_create_autocmd("FileType", {
  pattern = { "markdown", "text" },
  callback = function()
    vim.opt_local.wrap = true
    vim.opt_local.spell = true
  end,
})

添加 Vim 选项

-- In lua/config/options.lua M.setup():
vim.opt.your_option = value

创建实用函数

-- In lua/utils/init.lua
local M = {}

M.your_function = function(args)
  -- Implementation
end

return M

-- Usage: require('utils').your_function(args)

插件分类

核心（4 个插件）

plenary.nvim、nui.nvim、nvim-web-devicons、lazy.nvim

UI（11 个插件）

tokyonight、alpha-nvim、lualine、bufferline、noice、nvim-notify、which-key、indent-blankline、mini.indentscope、fidget、nvim-scrollbar

编辑器（13 个插件）

nvim-autopairs、flash.nvim、clever-f、nvim-spectre、grug-far、harpoon、persistence、smartyank、vim-sleuth、vim-illuminate、tabular、todo-comments、toggleterm

LSP（12 个插件）

nvim-lspconfig、mason、mason-lspconfig、mason-tool-installer、lazydev、luvit-meta、SchemaStore、conform、nvim-lint、trouble、blink.cmp/nvim-cmp、LuaSnip

Git（7 个插件）

vim-fugitive、vim-rhubarb、gitsigns、diffview、vim-flog、git-conflict、octo

AI（3 个插件）

copilot.vim、ChatGPT.nvim、mcphub.nvim

调试（8 个插件）

nvim-dap、nvim-dap-ui、nvim-dap-virtual-text、nvim-dap-python、nvim-dap-go、mason-nvim-dap、telescope-dap、nvim-nio

工具（14 个插件）

telescope、telescope-fzf-native、telescope-ui-select、neo-tree、oil.nvim、nvim-bqf、rest.nvim、vim-dadbod、vim-dadbod-ui、vim-dadbod-completion、iron.nvim、markdown-preview、nvim-puppeteer、obsidian.nvim

Treesitter（3 个插件）

nvim-treesitter、nvim-treesitter-context、nvim-treesitter-textobjects

故障排查

问题	解决方案
插件未加载	:Lazy sync
LSP 未启动	:LspInfo、:Mason
图标缺失	安装 Nerd Font
启动缓慢	:Lazy profile
Treesitter 错误	:TSUpdate
快捷键冲突	:verbose map <key>

健康检查

:checkhealth

调试日志

-- Temporarily add to plugin config:
log_level = vim.log.levels.DEBUG,

资源

• lazy.nvim
• Mason.nvim
• Neovim 文档
• Kickstart.nvim

参考资料

• references/configuration.md - 核心配置选项
• references/plugins.md - 详细介绍全部 82 个插件
• references/plugin-deepdives.md - 插件深度指南
• references/lsp.md - LSP 服务配置
• references/keybindings.md - 完整快捷键参考
• references/debugging.md - DAP 调试指南
• references/performance.md - 优化技巧
• references/tools.md - 命令行工具、实用程序和工作流
• references/troubleshooting.md - 常见问题与解决方案
• references/migration-0.11.md - Neovim 0.11 迁移指南

---

注意事项

• LSP 在 FileType 时附加，而不是在 BufRead 时： 在插件规范评估前打开的缓冲区不会获得 LSP。:LspInfo 不会显示任何内容——打开一个相同文件类型的新缓冲区，或运行 :edit 以重新触发自动命令。
• lazy-lock.json 会静默锁定所有内容： 除非移除锁定条目或显式运行 :Lazy update，否则 :Lazy sync 不会更新插件。Sync 只会安装缺失的插件并移除孤立插件。
• vim.defer_fn(..., 0) 会在 UIEnter 之后、FileType 之前运行： 以此方式加载的配置会错过第一个缓冲区的文件类型事件。如果第一个缓冲区的集成出现问题，请将快捷键映射和选项移出 defer_fn。
• Mason 会将工具安装到 ~/.local/share/nvim/mason/bin/，而不是 $PATH： 从 shell 调用格式化程序或代码检查工具的外部工具，无法找到 Mason 安装的二进制文件，除非你显式将该路径添加到环境变量前面。
• event = "VeryLazy" 会延迟到 UI 就绪之后： 拦截启动行为的插件（会话、仪表盘、配色方案）必须使用 lazy = false 和 priority = 1000——VeryLazy 触发得太晚。
• Treesitter 解析器会针对已安装的 Neovim ABI 编译： 升级 Neovim 后必须运行 :TSUpdate，否则可能会看到原因不明的 “Impossible pattern” 错误。