clang-tidy 默认不读 .clang-tidy，仅当执行目录或其任意上级目录存在合法 YAML 格式的 .clang-tidy 文件时才加载；文件名必须为 .clang-tidy，不可改名，且需位于工作路径链中。
clang-tidy 用哪个配置文件生效
clang-tidy 默认不读 .clang-tidy，除非你显式告诉它——它只在当前目录或父级目录中查找名为 .clang-tidy 的 YAML 文件，并且仅当该文件存在且语法合法时才加载。很多项目把配置放在子目录里，结果 clang-tidy 完全无视，就是因为没放对位置。
- 配置文件必须叫
.clang-tidy（注意开头的点），不能是clang-tidy.yaml或clang_tidy.yml - 它必须位于
clang-tidy命令执行时的当前工作目录，或其任意上级目录（逐级向上查找，找到第一个就停） - 如果用 CMake +
add_compile_options或set(CMAKE_CXX_CLANG_TIDY ...)，CMake 会自动把构建目录下的.clang-tidy传给 clang-tidy，但前提是该文件确实存在于构建目录或源码根目录 - 用
-config参数可强制指定路径，比如clang-tidy -config="{CheckOptions: [{key: readability-function-size.Threshold, value: '20'}]}"，适合 CI 临时覆盖
如何禁用默认检查、只启用自定义规则
clang-tidy 默认启用一长串检查（clang-tidy --list-checks 能看到），但多数项目不需要全开。想“白名单式”启用，关键不是加 -checks，而是先清空再加——否则容易漏掉隐式启用的默认项。
- 用
-checks=-*,readability-identifier-naming,bugprone-unchecked-optional-access：开头的-*是清除所有默认检查的唯一可靠写法 - 别写成
-checks=*, -readability-*...，这种写法不会清空，只是禁用部分，其余默认项照常运行 - 如果规则名拼错（比如
readability-identifer-naming少个f），clang-tidy 不报错，只是静默忽略——建议执行一次clang-tidy -checks="readability-identifier-naming" --list-checks确认是否在列表里 - 某些检查依赖编译命令中的宏定义或头搜索路径，即使启用了，也可能因
-p指向的compile_commands.json缺失信息而跳过，此时看输出里有没有Skipping ... (no relevant compilation info)
自定义命名规则（readability-identifier-naming）怎么写才生效
readability-identifier-naming 是最常配也最容易配错的检查。它不接受简单开关，必须在 .clang-tidy 中提供完整的 CheckOptions 映射，且 key 名必须精确匹配文档里的格式（大小写、连字符、后缀都不能错）。
- 正确 key 是
readability-identifier-naming.NamingStyle，不是readability-identifier-naming.Style或NamingRule - 值必须是 YAML 数组，每个元素含
Name、Type、Regex、Case（如UpperCamelCase），缺一不可 - 常见坑：
Regex里写^g_.*但忘了 YAML 要引号包裹字符串，导致解析失败；或者Case写成UPPER_CAMEL_CASE（实际只认UpperCamelCase） - 示例片段：
Checks: '-*,readability-identifier-naming' CheckOptions: - key: readability-identifier-naming.NamingStyle value: | - Name: 'Variable' Type: 'variable' Regex: '^([a-z][a-z0-9_]{2,})$' Case: 'lower_case' - Name: 'Class' Type: 'class' Regex: '^([A-Z][a-zA-Z0-9]+)$' Case: 'UpperCamelCase'
为什么改了 .clang-tidy 没反应？几个隐蔽原因
改完配置却没看到新规则报错，大概率不是 clang-tidy 不行，而是环境或调用链卡在某个环节。
立即学习“C++免费学习笔记（深入）”；
- CMake 构建系统可能缓存了旧的
CMAKE_CXX_CLANG_TIDY值，删掉build/CMakeCache.txt和build/CMakeFiles/后重新cmake .. - 编辑器插件（如 VS Code 的 C/C++ Extension 或 clang-tidy 插件）通常不实时读取
.clang-tidy，需要重启插件或整个编辑器，甚至手动触发 “Reload Window” - clang-tidy 版本差异大：12 以前不支持
modernize-use-nodiscard，15 才稳定支持cppcoreguidelines-avoid-magic-numbers的IgnoreMacros选项——用clang-tidy --version确认版本，再查对应 LLVM 文档 - 检查被
// NOLINT或// NOLINTNEXTLINE注释屏蔽了，这类注释优先级高于配置，且不校验规则名是否真实存在
配置真正跑通的关键，往往不在 YAML 写得多漂亮，而在确认 clang-tidy 实际加载的是哪个文件、用的是哪个版本、走的是哪条调用路径。多打几次 clang-tidy -dump-config -p build/，比反复改配置更省时间。
