Neovim LSP配置中光标词高亮问题的解决方案

在Neovim的LSP配置使用过程中，许多用户遇到了光标下单词高亮无法禁用的问题。这个问题通常出现在使用LazyVim这类预配置框架时，但本质上与nvim-lspconfig插件的配置方式有关。

问题现象

用户期望通过配置document_highlight = false来禁用LSP提供的单词高亮功能，但实际上该配置项并未生效。测试发现：

1. 直接禁用LSP时高亮消失，确认是LSP相关功能
2. 配置项修改后高亮仍然存在

技术背景

在Neovim的LSP生态中，单词高亮功能涉及多个层面：

1. LSP协议本身提供的textDocument/documentHighlight能力
2. 客户端对LSP响应的可视化呈现
3. 可能存在的其他插件（如vim-illuminate）的叠加效果

解决方案

经过社区验证的有效方案有以下几种：

方案一：修改LSP客户端能力

在LSP的on_attach回调中显式禁用高亮能力：

LazyVim.lsp.on_attach(function(client, buffer)
  client.server_capabilities.documentHighlightProvider = false
end)

方案二：检查并禁用相关插件

某些情况下可能是其他插件（如vim-illuminate或snacks.nvim）引起的高亮：

-- 对于vim-illuminate
require('illuminate').configure({ under_cursor = false })

-- 对于snacks.nvim
require('snacks').setup({
  words = { enabled = false }
})

方案三：使用自动命令拦截

创建LspAttach自动命令来动态修改能力：

vim.api.nvim_create_autocmd("LspAttach", {
  callback = function(args)
    local client = vim.lsp.get_client_by_id(args.data.client_id)
    if client and client.server_capabilities.documentHighlightProvider then
      client.server_capabilities.documentHighlightProvider = false
    end
  end,
})

最佳实践建议

1. 明确区分LSP原生高亮和其他插件的高亮功能
2. 优先使用on_attach回调进行LSP能力控制
3. 对于框架配置（如LazyVim），建议查阅最新文档确认配置方式
4. 可以通过:LspInfo命令验证当前会话的实际能力配置

技术原理

LSP的高亮功能是通过客户端-服务器协商实现的。服务器在初始化时会声明自己支持的能力，客户端根据这些声明来决定启用哪些功能。直接修改server_capabilities是最底层的控制方式，能够确保功能被彻底禁用。

理解这一点后，开发者就能更灵活地控制LSP的各种功能表现，而不仅限于高亮这一个功能点。这种能力控制模式适用于所有LSP提供的特性，包括代码补全、悬停提示、代码动作等。