项目根目录必须放置名为 .clang-format 的 UTF-8 无 BOM 文件，且需显式配置 PointerAlignment、IndentWidth 等关键参数；编辑器须验证实际加载，CI 应用 --dry-run --Werror 检查并固定版本。
项目根目录必须放 .clang-format，且文件名不能写错
Clang-Format 不会自动向上扫描所有父级目录，它只在当前文件所在路径及其**直接祖先目录**中找第一个匹配的 .clang-format（注意大小写和点号）。如果你把配置文件放在 src/.clang-format，那么 src/main.cpp 能读到，但 tests/test.cpp 就会 fallback 到默认风格——这正是团队成员格式不一致的常见源头。
必须把 .clang-format 放在 Git 仓库最顶层（即 git rev-parse --show-toplevel 输出的路径），且确保：
- 文件名是
.clang-format，不是clang-format、.clang_format或clang-format.yaml - 文件编码为 UTF-8 无 BOM
- Git 中未被
.gitignore忽略（检查git check-ignore -v .clang-format）
BasedOnStyle 只是起点，PointerAlignment 和 IndentWidth 必须显式覆盖
BasedOnStyle: Google 看似省事，但不同 Clang-Format 版本对 PointerAlignment 的默认值不同：14+ 默认 Right（int *p），旧版可能是 Left（int* p）。团队里有人用 12，有人用 16，int* p 和 int *p 就会在同一行里打架。
关键参数建议统一写死：
立即学习“C++免费学习笔记（深入）”；
-
PointerAlignment: Right（C++ 指针星号紧贴类型） -
ReferenceAlignment: Right（同理，int &r） -
IndentWidth: 4和TabWidth: 4必须相等，否则粘贴时缩进塌陷 -
UseTab: Never，禁用 Tab 是避免混排的底线 -
Cpp11BracedListStyle: true，否则std::vector{1, 2, 3}可能被压成一行破坏可读性
VS Code / CLion 集成时，别信“自动启用”，要验证是否真读了项目配置
VS Code 的 C/C++ 扩展默认可能用内置风格或全局设置，而不是你项目里的 .clang-format。一个简单验证法：临时把 .clang-format 里 IndentWidth 改成 999，然后保存一个 .cpp 文件——如果缩进没变成 999 空格，说明编辑器根本没加载它。
排查要点：
- VS Code 设置中确认
"C_Cpp.formatting": "clangFormat"，且"C_Cpp.clang_format_path"没被硬编码指向某个二进制路径（会绕过配置文件） - CLion 要在
Settings → Tools → Clang-Format中勾选Enable Clang-Format，并手动指定Configuration file为Project style（不是Disabled或Chromium） - 命令行验证：在项目根目录运行
clang-format -dump-config -assume-filename=test.cpp，输出里必须包含你写的IndentWidth值
CI 流程里用 --dry-run --Werror，别自动修复
CI 不该替开发者改代码，而应明确报错并阻断不合规范的提交。用 clang-format --dry-run --Werror 扫描变更文件，一旦发现格式差异就返回非零退出码。
推荐脚本逻辑（GitHub Actions 示例）：
clang-format --dry-run --Werror $(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(cpp|cc|cxx|c|hpp|h|hh|inl)$')
注意点：
- 必须限定后缀，否则可能误扫
build/下的生成文件或third_party/的外部代码 - 要用
git diff --cached，只检查即将提交的内容，而非整个工作区 - CI 中固定 Clang-Format 版本（如
clang-format-15），避免因 CI runner 升级导致行为突变
最易被忽略的是：.clang-format 本身也要进 Git，并在 CONTRIBUTING.md 里写明“所有新成员 clone 后需运行 pre-commit install”。否则格式统一永远只是幻觉。
