必须手动指定xaver.clang-format为c/c++默认格式化器，并在项目根目录放置lf编码的.clang-format文件，否则vscode不调用clang-format且无提示；还需确保clang-format可执行文件在path中或手动配置路径，且.h文件语言模式正确识别为c/c++。
clang-format 插件装了但右键没“Format Document”选项
VS Code 默认不把任何插件设为 C/C++ 的格式化器，即使 clang-format 可执行文件在 PATH 里、插件也已安装，它也不会自动接管格式化动作。
必须显式指定语言级默认格式化器。推荐用 xaver.clang-format 插件（轻量、专注、无副作用），而不是 ms-vscode.cpptools —— 后者自带的格式化逻辑不调用 clang-format，且对 .h 文件行为不一致。
- 打开命令面板（
Ctrl+Shift+P或Cmd+Shift+P），输入并选择 Preferences: Configure Language Specific Settings - 选
c或cpp，在弹出的settings.json片段中填入：
"[c]": {
"editor.defaultFormatter": "xaver.clang-format",
"editor.formatOnSave": true
},
"[cpp]": {
"editor.defaultFormatter": "xaver.clang-format",
"editor.formatOnSave": true
}
注意：如果项目根目录下有 .vscode/settings.json，它会覆盖用户设置，务必检查是否被意外禁用或指向了其他格式化器。
clang-format 可执行文件路径没配对或根本找不到
clang-format 不是 VS Code 自带的，插件只是胶水，真正干活的是系统里的可执行文件。路径错、权限缺、或用了 npm 版本，都会导致静默失败——右键没反应、保存不格式化、终端运行 clang-format -n main.cpp 报 “command not found”。
- 优先用系统包管理器安装：
brew install llvm（macOS）、sudo apt install clang-format（Ubuntu/Debian）；Windows 用户下载 LLVM 安装包，确保bin/clang-format.exe路径加入系统PATH - 不要用
npm install -g clang-format—— 它输出的是 Node.js 封装层，VS Code 插件无法与之通信，会直接跳过 - 若 PATH 不可靠（比如多版本共存），手动指定路径：设置中搜索
clang-format.executable，填绝对路径，如/usr/local/opt/llvm/bin/clang-format或C:\Program Files\LLVM\bin\clang-format.exe
.clang-format 文件放错位置或格式非法
VS Code 只在工作区根目录（即你通过 File → Open Folder 打开的那个文件夹）查找 .clang-format、_clang-format 或无扩展名的 clang-format。放错层级、命名错误、或 YAML 缩进错一个空格，都会导致它完全忽略配置，退回到内置 LLVM 风格——和你想要的 Google 风格差别极大。
- 生成最小可用配置：终端进入项目根目录，运行
clang-format -style=google -dump-config > .clang-format，然后删掉所有注释行（# 开头），只留缩进正确的键值对 - 禁止写
BasedOnStyle: file—— VS Code 插件不支持该指令，会静默失败 - Windows 下务必用 LF 换行符保存
.clang-format，CRLF 可能导致解析失败且无提示 - 验证是否生效：终端运行
clang-format -n src/main.cpp，如果有报错说明语法问题；如果静默但没输出差异，大概率是文件根本没被读到
保存时格式化了但 .h 文件没动
这是 ms-vscode.cpptools 的经典坑：它对 .cpp 和 .h 使用不同内置规则，且不尊重 .clang-format 中的 IncludeIsMainRegex 等控制项。换成 xaver.clang-format 后，仍可能因默认规则差异导致头文件缩进、include 排序异常。
- 在
.clang-format中显式关闭头文件特殊处理：IncludeIsMainRegex: ''和SortIncludes: false - 若需统一 include 行为，可设
IncludeIsMainRegex: '([-_](test|unittest)|[._]unittest)$'并配合SortIncludes: true，但需确保正则匹配你的项目命名习惯 - struct 初始化换行异常？常见于
AllowAllArgumentsOnNextLine: false和Cpp11BracedListStyle: true冲突，建议先用-style=google基线，再微调MaxEmptyLinesToKeep或IndentWidth
最常被忽略的一点：VS Code 的格式化触发依赖于语言模式识别。确保你的 .h 文件右下角显示的是 C 或 C++，而不是 Plain Text 或 C Header —— 后者不会走 [cpp] 设置分支。
