必须手动将xaver.clang-format设为C/C++默认格式化器，并在项目根目录放置LF编码的.clanɡ-format文件，否则VSCode不调用clang-format且无提示。
Clang-Format 插件装了但右键没“Format Document”选项
VSCode 默认不启用 Clang-Format 作为 C/C++ 文件的格式化工具，即使插件已安装、clang-format 可执行文件在 PATH 中，也得手动指定它为默认格式化程序。
实操建议：
立即学习“C++免费学习笔记（深入）”；
- 打开命令面板（
Ctrl+Shift+P或Cmd+Shift+P），输入并选择Preferences: Configure Language Specific Settings...，选c或cpp - 在弹出的
settings.json片段中添加："editor.defaultFormatter": "ms-vscode.cpptools", "editor.formatOnSave": true
→ 这不对，ms-vscode.cpptools自带的格式器不调用clang-format；必须改成llvm-vs-code-extensions.vscode-clangd或更常用的xaver.clang-format（如果装的是这个插件） - 确认插件是
xaver.clang-format后，全局或语言级设置里写："[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 或 _clang-format）
clang-format 不会自动 fallback 到系统默认样式；它严格按路径向上查找 .clang-format、_clang-format 或 clang-format（无点号），找不到就用内置 LLVM 风格——和你预期的 Google/Chromium 风格往往差很远。
实操建议：
立即学习“C++免费学习笔记（深入）”；
- 把
.clang-format放在项目根目录（不是src/或build/），确保 VSCode 工作区打开的是该目录（即资源管理器顶部显示的是项目根） - 用
clang-format -dump-config -style=google > .clang-format生成一个可读配置，再手工调整；别直接复制粘贴网上不可靠的 YAML 片段（缩进错一个空格就静默失效） - 验证是否生效：终端进项目根，运行
clang-format -n src/main.c，看报错还是静默——报错说明配置语法错，静默但没输出差异说明根本没读到配置 - Windows 下注意换行符：用 LF（Unix 风格）保存
.clang-format，CRLF 可能导致解析失败且无提示
格式化后 struct 初始化换行/缩进异常
C 语言里 struct 初始化块（尤其是嵌套或长字段）容易被 clang-format 拆成难以阅读的多行，根源常是 AllowAllArgumentsOnNextLine、AllowAllParametersOnNextLine 等布尔项没关，或 Cpp11BracedListStyle 干扰了大括号初始化。
实操建议：
立即学习“C++免费学习笔记（深入）”；
- 在
.clang-format中显式控制初始化风格：AllowAllArgumentsOnNextLine: false AllowAllParametersOnNextLine: false Cpp11BracedListStyle: false
- 对特定 struct 块临时禁用格式化：用
// clang-format off和// clang-format on包裹，比硬调参数更可靠 - 避免用
BasedOnStyle: google直接套用——Google 风格默认把长初始化全压单行，而 Chromium 风格才倾向展开；查清你真正在模仿哪个项目的实际产出 - 注意
IndentWidth和ContinuationIndentWidth差值：若设成相同值，嵌套初始化可能少缩进一级，看起来像对不齐
保存时格式化卡顿或崩溃（尤其大型 C 项目）
VSCode 调用 clang-format 是同步阻塞的；如果 .clang-format 里开了 SortIncludes: true，又没配 IncludeIsMainRegex，它会对每个 #include 行做全路径解析+排序，IO 开销陡增。
实操建议：
立即学习“C++免费学习笔记（深入）”；
- 关掉高开销项：
SortIncludes: false IncludeIsMainRegex: ""
除非你真需要 include 排序，否则别开 - 用
clang-format的-assume-filename参数（需插件支持或自定义clang-format.executable路径加参数），避免它反复猜文件语言类型 - 检查
clang-format版本：12+ 对 C 代码解析明显快于 9.x；用clang-format --version确认，别依赖系统包管理器装的旧版 - 如果项目含大量生成头文件（如
build/generated.h），在.clang-format加DisableFormat: true BasedOnStyle: none
并配合文件匹配规则（需插件支持 glob），或直接在 VSCode 设置里用files.exclude排除这些路径
配置真正起效的关键，往往卡在「VSCode 找没找到那个配置文件」和「clang-format 实际读没读到那行设置」之间。多试一次 clang-format -dump-config -style=file，比反复重启窗口有用得多。
