.clang-format 文件必须放在项目根目录，命名严格为 .clang-format（区分大小写），Clang-Format 仅向上查找祖先目录中的首个匹配项，不向下或跨子模块搜索；常见失效原因包括路径错误、命名不符、IDE工作区未以文件夹打开、clang-format版本不一致及关键配置项未显式声明。
直接结论：.clang-format 文件必须放在项目根目录，且命名严格为 .clang-format（区分大小写），Clang-Format 只会向上查找祖先目录中的第一个匹配项，不会跨子模块或向下搜索。
为什么你的 .clang-format 总是不生效
常见错误现象是改了配置但保存代码毫无反应，或者 VS Code 格式化结果和 CLI 不一致。根本原因通常是：
-
.clang-format放在了src/或build/子目录下——Clang-Format 不会从当前文件所在目录“向下”找配置，只向上查到项目根为止 - 文件名写成
clang-format、.clang_format或clang-format.yaml——全部无效，必须是.clang-format - IDE 没有正确传递工作目录，比如 VS Code 打开的是单个
.cpp文件而非整个文件夹，导致它找不到根目录下的配置 - 团队成员本地 clang-format 版本不一致（如有人用 12，有人用 17），同一份配置可能被部分忽略或报
unknown key警告
关键配置项必须显式声明，不能依赖默认值
不同版本 clang-format 对 PointerAlignment、ReferenceAlignment、Cpp11BracedListStyle 等字段的默认值差异极大。不写明就会导致团队格式不统一。以下是最常踩坑的几项：
Clang 22.1.3
下载
Clang 22.1.3 Windows 64 位历史版本安装包，适合旧项目兼容、LLVM/Clang 工具链回退、编译行为对比、链接问题复现和 C/C++ 构建环境维护。
-
PointerAlignment: Right—— 控制int *p还是int* p；Clang-Format 14+ 默认是Right，但旧版本可能是Left -
ReferenceAlignment: Right—— 同理，影响void foo(int &x)的空格位置 -
IndentWidth: 4和TabWidth: 4必须一致，且UseTab: Never；否则粘贴代码时缩进错乱 -
Cpp11BracedListStyle: true—— 决定std::vector{1, 2, 3}是否换行；不设会导致初始化列表被强行压成一行，可读性崩坏 -
BasedOnStyle: Google或LLVM可快速起步，但所有冲突项必须覆盖，不能只靠基线
如何验证配置是否真正加载
别只信 IDE 界面显示，用命令行直击本质：
- 在项目根目录执行：
clang-format --dump-config -assume-filename=test.cpp—— 它会输出当前生效的完整配置，确认你写的字段是否被识别 - 检查输出中是否有
Unknown key行；如果有，说明该字段不被当前版本支持（例如SortIncludes: Lexical在 clang-format 10 中无效） - 对一个测试文件运行：
clang-format -i test.cpp && git diff test.cpp，看实际改动是否符合预期 - VS Code 用户可在设置中搜
clang-format，确认clang-format.executable指向的是你安装的路径，而不是插件自带的旧版
批量格式化命令必须和 CI 保持一致
很多团队把格式化当“锦上添花”，结果 CI 报错才发现本地没跑全。真实可用的命令应明确限定范围、跳过生成文件，并与 CI 脚本对齐：
- Linux/macOS（推荐）：
find . -name '*.cpp' -o -name '*.h' -o -name '*.cc' -o -name '*.hpp' | xargs clang-format -i - Windows PowerShell：
Get-ChildItem -Recurse -Include "*.cpp","*.h","*.cc","*.hpp" | ForEach-Object { clang-format -i $_.FullName } - 更稳妥的做法是复用项目已有的脚本，比如 Nebula 的
make clang-format或 Shipwright 的./run-clang-format.sh，它们已内置过滤逻辑（跳过src/下反编译头、子模块、自动生成资产等） - CI 中务必固定版本，例如 Ubuntu 上用
sudo apt install clang-format-14，而不是clang-format（后者随系统升级可能变 15）
最易被忽略的一点：Clang-Format 不处理换行符（CRLF/LF）、BOM、文件编码——这些得靠 Git 的 core.autocrlf 或编辑器自身设置。配置再完美，如果团队混用 CRLF 和 LF，diff 里全是红色空行，review 就变成体力活。
