Clang-Format 在 VS Code 不生效的四大原因：可执行文件路径未配置或不在 PATH、.clang-format 文件未置于工作区根目录且命名/语法不规范、settings.json 未为 [cpp] 和 [c] 语言显式启用格式化、头文件格式化行为未通过 IncludeIsMainRegex 和 SortIncludes 统一。
Clang-Format 在 VS Code 里不生效？不是插件没装，而是四个关键环节中至少一个断了：可执行文件找不到、配置文件不被读、语言设置没限定、格式化器没指定。
clang-format 可执行文件必须能被 VS Code 调到
VS Code 自己不带 clang-format，插件只是“调度员”，真正干活的是你系统里的二进制。它默认只查 PATH，查不到就静默跳过——你连报错都看不到。
- 终端里运行
clang-format --version，失败就说明路径没配好 - Linux/macOS 常见路径：
/usr/bin/clang-format、/opt/homebrew/bin/clang-format - Windows 常见路径：
C:\Program Files\LLVM\bin\clang-format.exe（注意是完整.exe） - 别用
npm install -g clang-format安装的版本——它不兼容 VS Code 的 LSP 调用方式，必定静默失败 - 如果路径不在
PATH，必须手动填：设置里搜clang-format.executable，填绝对路径
.clang-format 文件必须放对位置且语法干净
VS Code 不会自动 fallback，也不会递归查找。它只认三个名字（按优先级）：.clang-format（推荐）、_clang-format、clang-format（无扩展名，不推荐），且只在工作区根目录找。
- 工作区根目录 = 你用
File → Open Folder打开的那个文件夹，不是src/或build/ - 生成最小可用配置最可靠命令：
clang-format -style=google -dump-config > .clang-format - 生成后必须检查：UTF-8 编码、LF 换行（Windows 用户尤其注意别是 CRLF）、缩进全用空格（不能混 Tab）
- 哪怕 YAML 里只有一处缩进用了 Tab，整个配置就静默失效
settings.json 必须显式为 [cpp] 和 [c] 启用格式化
VS Code 默认对 .cpp 和 .h 文件完全不启用任何格式化，哪怕插件和二进制都 OK。必须手动加语言专属配置，不能靠全局设置或图形界面点选。
立即学习“C++免费学习笔记（深入）”；
- 编辑
settings.json（用户级或工作区级），加入以下块（注意是[cpp]，不是c++或cpp-language）：
"[cpp]": {
"editor.formatOnSave": true,
"editor.defaultFormatter": "xaver.clang-format"
},
"[c]": {
"editor.formatOnSave": true,
"editor.defaultFormatter": "xaver.clang-format"
}
- 如果用了
ms-vscode.cpptools作为格式化器，它对.h文件行为和.cpp不一致，容易漏格式化头文件 - 务必检查项目根目录下有没有
.vscode/settings.json，它会覆盖用户设置，造成“明明设了却没用”的假象 - 确保没同时启用其他 C++ 格式化插件（比如
jeff-hykin.cpp-textmate-grammar），冲突会导致格式化被跳过
头文件（.h）格式化行为差异怎么统一
clang-format 对 .h 文件有内置特殊逻辑：默认认为头文件是“主文件”（IncludeIsMain），会额外插入 #include "xxx.h" 等规则，导致和 .cpp 行为不一致。
- 在
.clang-format中加这两行即可统一：
IncludeIsMainRegex: '' SortIncludes: false
- 第一行关掉“头文件即主文件”的启发式判断
- 第二行禁用头文件
#include排序，避免和.cpp产生顺序差异 - 如果你用
ms-vscode.cpptools，它默认不读.clang-format里的这些选项，所以更推荐用xaver.clang-format插件
最容易被忽略的其实是工作区根目录这个概念——很多人把 .clang-format 放在 src/ 下，或者用 VS Code 打开的是子模块目录，VS Code 就根本不会去那里找配置文件。验证是否生效最直接的办法：终端进项目根目录，运行 clang-format -n src/main.cpp；如果有报错，说明配置语法有问题；如果静默但没输出差异，大概率是路径或命名不对。
