强曰为道

与天地相似,故不违。知周乎万物,而道济天下,故不过。旁行而不流,乐天知命,故不忧.
文档目录

19 - 故障排查与性能优化

“If your Neovim starts slower than VS Code, you’re doing something wrong.”

19.1 启动时间优化

19.1.1 测量启动时间

# Neovim 启动分析
nvim --startuptime startup.log
nvim --startuptime /dev/stdout 2>&1 | tail -20

# 查看总启动时间
head -1 startup.log    # 开始时间
tail -1 startup.log    # 结束时间

# lazy.nvim 内置分析器
:Lazy profile

19.1.2 启动时间目标

等级启动时间评价
⭐⭐⭐⭐⭐< 30ms极快
⭐⭐⭐⭐30-50ms优秀
⭐⭐⭐50-100ms良好
⭐⭐100-200ms可接受
> 200ms需优化

19.1.3 优化策略

策略一:延迟加载插件

-- 错误方式:启动即加载
{ "nvim-telescope/telescope.nvim" }

-- 正确方式:按键触发加载
{ "nvim-telescope/telescope.nvim",
    cmd = "Telescope",
    keys = {
        { "<leader>ff", "<cmd>Telescope find_files<cr>" },
    },
}

-- 事件触发加载
{ "numToStr/Comment.nvim",
    event = "BufReadPost",
}

-- 文件类型触发加载
{ "simrat39/rust-tools.nvim",
    ft = "rust",
}

策略二:禁用不需要的内置插件

performance = {
    rtp = {
        disabled_plugins = {
            "gzip",
            "tarPlugin",
            "tohtml",
            "tutor",
            "zipPlugin",
            "netrw",
            "netrwPlugin",
        },
    },
},

策略三:优化配置加载顺序

-- init.lua 中确保顺序正确
vim.g.mapleader = " "          -- 1. Leader 键(必须在插件前)
require("config.options")       -- 2. 基本选项
require("config.lazy")          -- 3. 插件管理器
require("config.keymaps")       -- 4. 快捷键
require("config.autocmds")      -- 5. 自动命令(最后加载)

19.2 运行时性能

19.2.1 大文件处理

-- 大文件优化
vim.api.nvim_create_autocmd("BufReadPre", {
    callback = function()
        local file = vim.fn.expand("<afile>")
        local size = vim.fn.getfsize(file)
        if size > 1024 * 1024 then -- 1MB
            vim.opt_local.syntax = ""
            vim.opt_local.foldmethod = "manual"
            vim.opt_local.spell = false
            vim.opt_local.undofile = false
            vim.opt_local.swapfile = false
            vim.b.large_file = true
        end
    end,
})

19.2.2 Tree-sitter 优化

highlight = {
    enable = true,
    disable = function(lang, buf)
        local max_filesize = 100 * 1024 -- 100KB
        local ok, stats = pcall(vim.loop.fs_stat, vim.api.nvim_buf_get_name(buf))
        if ok and stats and stats.size > max_filesize then
            return true
        end
    end,
},

19.2.3 updatetime 调优

-- 默认 4000ms 太慢
vim.opt.updatetime = 250

-- 如果有性能问题,可以适当增大
vim.opt.updatetime = 500

19.3 常见问题排查

19.3.1 配置错误定位

# 检查配置语法
nvim --clean  # 无配置启动

# 仅加载特定文件测试
nvim -u minimal.lua

# 最小配置模板(用于排查)
cat > /tmp/minimal.lua << 'EOF'
vim.opt.runtimepath:prepend("~/.local/share/lazy/lazy.nvim")
require("lazy").setup({
    { "folke/which-key.nvim", config = true },
}, { root = "/tmp/lazy" })
EOF

nvim -u /tmp/minimal.lua

19.3.2 Lua 错误调试

-- 查看最近的错误
:messages

-- Lua 执行追踪
:lua require("notify")("test")

-- 打印调试
:lua print(vim.inspect(vim.opt.tabstop:get()))
:lua print(vim.fn.stdpath("config"))
:lua print(vim.fn.stdpath("data"))

19.3.3 LSP 问题

:LspInfo                    " 查看 LSP 状态
:LspLog                     " 查看 LSP 日志
:lua print(vim.lsp.get_active_clients())  " 列出活跃客户端
:MasonLog                   " Mason 日志

" 检查 LSP 是否正确连接
:lua vim.lsp.buf.execute_command({ command = '...' })

19.3.4 Tree-sitter 问题

:TSInstallInfo              " 查看解析器安装状态
:TSHighlightCapturesUnderCursor  " 查看当前高亮组
:TSModuleInfo               " 查看模块状态
:checkhealth nvim-treesitter  " 健康检查

19.3.5 插件冲突

" 禁用所有插件测试
nvim --noplugin

" 逐个禁用插件排查
" 在 lazy.nvim 中临时设置 enabled = false

" 查看插件加载顺序
:Lazy profile

19.4 健康检查

:checkhealth              " 全部健康检查
:checkhealth vim.lsp      " LSP 检查
:checkhealth nvim-treesitter  " Tree-sitter 检查
:checkhealth telescope    " Telescope 检查

常见检查项:

检查项说明
Python 支持pynvim 是否安装
Node.js 支持neovim npm 包
剪贴板xclip/wl-clipboard
终端真彩色支持
字体Nerd Font 图标
磁盘undo/swap 目录权限

19.5 内存优化

-- 定期清理未使用缓冲区
vim.api.nvim_create_autocmd("BufHidden", {
    callback = function(event)
        if not event.file:match("^%w+://") and vim.bo[event.buf].buftype ~= "nofile" then
            vim.schedule(function()
                pcall(vim.api.nvim_buf_delete, event.buf, { force = false })
            end)
        end
    end,
})

19.6 常见错误速查

错误原因解决
E486: Pattern not found搜索无结果检查搜索模式
E21: Cannot make changes只读文件:set modifiablesudo
E13: File exists保存覆盖警告:w! 强制保存
E576: Error while reading ShaDaShaDa 文件损坏删除 ShaDa 文件
E484: Can’t open file文件不存在检查路径
LSP not attachedLSP 未连接:LspInfo 排查
Highlight not workingTree-sitter 问题:TSInstall lang

19.7 ShaDa 文件

" ShaDa(Shared Data)文件存储:
" - 命令历史
" - 搜索历史
" - 寄存器内容
" - 标记位置
" - jumplist

" ShaDa 文件位置
" Linux: ~/.local/state/nvim/shada/
" macOS: ~/.local/state/nvim/shada/

" 重置 ShaDa
" 删除文件后重启 Neovim

19.8 业务场景

场景排查方法
启动慢--startuptime + Lazy profile
编辑卡顿检查大文件、禁用插件
LSP 不工作:LspInfo + :MasonLog
高亮错误:TSHighlightCapturesUnderCursor
插件冲突--clean / 逐一禁用

19.9 总结

优化项方法
启动速度延迟加载、禁用内置插件
运行性能大文件优化、Tree-sitter 限制
LSP 问题:LspInfo + :checkhealth
错误排查--clean 最小配置、:messages
健康检查:checkhealth

下一步第 20 章 - 最佳实践与 IDE 配置 → 从零搭建完整的 Neovim IDE 配置。


扩展阅读

  • Neovim 性能指南
  • :h startup — 启动优化
  • :h checkhealth — 健康检查
  • :h shada — ShaDa 文件