Clang-Tidy依赖场景运行慢 如何完全忽略头文件而非抑制警告

问题背景 #

使用clang-tidy对代码库做lint检查时整体运行速度极慢，运行输出显示有大量来自项目依赖项的非用户代码警告被抑制，示例输出如下：

Suppressed 72958 warnings (72958 in non-user code).
Use -header-filter=.* to display errors from all non-system headers. Use -system-headers to display errors from system headers as well.

仅靠默认的警告抑制逻辑无法解决性能问题：clang-tidy依然会完整解析这些依赖头文件生成AST，只是最后不展示警告而已，这部分解析操作是拖慢运行速度的核心原因。

可行方案 #

• 通过--exclude参数直接跳过指定路径的文件分析
  运行clang-tidy时显式传入要排除的路径，匹配到的所有文件（包括头文件、源文件）会被直接跳过，不会进入解析流程，从根源减少计算量。示例命令：

  clang-tidy [你的待检查源文件列表] -p 编译数据库目录 --exclude=*/third_party/* --exclude=*/build/*
  

  注意不要用无范围的通配符（比如*）扫描整个代码目录，显式指定项目自有源码的路径，避免把依赖文件加入检查队列。

• 将依赖头文件目录标记为系统头文件目录
  clang-tidy默认会完全跳过系统头文件的解析，不会对这部分文件做任何检查逻辑。只要把第三方依赖的头文件包含方式从-I改为-isystem，就能让clang-tidy把这些头文件识别为系统头文件直接跳过。
  如果使用CMake管理项目，可以直接给依赖包含目录加SYSTEM属性，自动生成对应的编译参数：

  target_include_directories(你的项目目标名 SYSTEM PRIVATE ${第三方依赖的头文件目录变量})
  

• 配置参数仅分析源文件，跳过所有头文件解析
  如果不需要检查任何头文件（包括项目自有头文件），可以在运行时传入空的头文件过滤规则，搭配关闭模板实例化的额外参数，阻止clang-tidy递归解析include的头文件内容：

  clang-tidy [待检查源文件] -p build/ -header-filter= --extra-arg=-fno-pch-instantiate-templates
  

  这个配置下clang-tidy只会对传入的.c/.cpp等源文件做检查，不会递归解析所有引入的头文件，运行速度会有明显提升，但会丢失头文件内的代码检查能力，适合只需要校验源文件实现逻辑的场景。

内容的提问来源于stack exchange，提问作者Alexandre Lipp