在nvimdots中禁用Clangd自动插入头文件功能

背景介绍

在使用基于Neovim的nvimdots配置时，许多C/C++开发者会遇到一个常见问题：当通过LSP（Language Server Protocol）选择代码补全建议时，Clangd会自动插入相关的头文件引用。虽然这一功能对部分开发者很有帮助，但有些开发者更倾向于手动管理头文件引用，以保持代码的整洁性和可控性。

问题分析

Clangd作为C/C++的LSP服务器，默认会启用header-insertion功能。当用户选择补全建议时，如果该符号定义在其他头文件中，Clangd会自动添加对应的#include语句。这一行为虽然方便，但可能导致：

1. 头文件引用顺序不符合项目规范
2. 引入不必要的头文件依赖
3. 与开发者个人的编码习惯冲突

解决方案

通过修改nvimdots中的Clangd配置，可以完全禁用自动插入头文件的功能。具体实现步骤如下：

1. 在nvimdots配置目录中创建专用配置文件：

   touch lua/user/configs/lsp-servers/clangd.lua
   

2. 编辑该文件，添加以下配置内容：

   local function get_binary_path_list(binaries)
     local path_list = {}
     for _, binary in ipairs(binaries) do
       local path = vim.fn.exepath(binary)
       if path ~= "" then
         table.insert(path_list, path)
       end
     end
     return table.concat(path_list, ",")
   end
   
   return function(options)
     require("lspconfig").clangd.setup({
       on_attach = options.on_attach,
       capabilities = vim.tbl_deep_extend("keep", { offsetEncoding = { "utf-16", "utf-8" } }, options.capabilities),
       single_file_support = true,
       cmd = {
         "clangd",
         "-j=12",
         "--enable-config",
         "--background-index",
         "--pch-storage=memory",
         "--query-driver=" .. get_binary_path_list({ "clang++", "clang", "gcc", "g++"}),
         "--clang-tidy",
         "--all-scopes-completion",
         "--completion-style=detailed",
         "--header-insertion-decorators",
         "--header-insertion=never",  -- 关键配置项
         "--limit-references=3000",
         "--limit-results=350",
       },
     })
   end
   

关键配置项--header-insertion=never会完全禁用Clangd的自动头文件插入功能。

配置详解

1. 二进制路径检测：get_binary_path_list函数用于检测系统中可用的C/C++编译器路径，确保Clangd能够正确解析项目。

2. 性能优化参数：

   • -j=12：设置并行工作线程数
   • --background-index：启用后台索引
   • --pch-storage=memory：将预编译头文件存储在内存中

3. 补全相关参数：

   • --all-scopes-completion：在所有作用域提供补全
   • --completion-style=detailed：提供详细的补全信息

效果验证

配置生效后，当选择LSP提供的补全建议时：

• 仍然会显示符号的完整信息（包括定义位置）
• 不会自动添加#include语句
• 开发者可以手动添加所需的头文件引用

扩展建议

1. 如果只想禁用特定情况下的自动插入，可以考虑其他选项：

   • --header-insertion=iwyu：遵循Include-What-You-Use原则

2. 对于团队项目，建议将此类配置纳入项目级的.clangd配置文件中，确保所有团队成员使用一致的开发环境。

通过这种方式，开发者可以在享受LSP强大补全功能的同时，保持对代码结构的完全控制，特别适合对代码质量有严格要求的中大型项目。