Clang-Format在VSCode中需同时满足三条件才生效：clang-format可执行文件路径正确（终端clang-format --version可验证）、.clang-format文件置于工作区根目录且为UTF-8+LF编码、settings.json中显式配置"[cpp]": {"editor.defaultFormatter":"xaver.clang-format","editor.formatOnSave":true}。

clang-format 可执行文件路径没配对，格式化直接失效

VS Code 找不到 clang-format 就不会调用它，哪怕插件装了、.clang-format 文件也放好了。Linux/macOS 通常装在 /usr/bin/clang-format 或 /usr/local/bin/clang-format；Windows 常见路径是 C:Program FilesLLVMinclang-format.exe 或你手动解压的 C:Toolsclang-formatclang-format.exe。

验证方式：终端里运行 clang-format --version，有输出就说明路径正确；没反应或报 “command not found”，就得手动配。

• VS Code 用户级配置（全局生效）：打开 settings.json，加这一行：
  "clang-format.executable": "/usr/bin/clang-format"（Linux/macOS）或 "clang-format.executable": "C:\Program Files\LLVM\bin\clang-format.exe"（Windows，注意双反斜杠）
• 工作区级配置（仅当前项目）：在项目根目录建 .vscode/settings.json，内容同上
• 别信插件自动探测——某些版本的 xaver.clang-format 插件根本不会自动找路径，必须显式指定

VS Code 没启用保存时自动格式化，改了配置也白搭

装完插件、配好路径，但按 Ctrl + S 没反应？大概率是 editor.formatOnSave 没开。

Clang 22.1.3

Clang 22.1.3 Windows 64 位历史版本安装包，适合旧项目兼容、LLVM/Clang 工具链回退、编译行为对比、链接问题复现和 C/C++ 构建环境维护。

下载

• 快捷方式：按 Ctrl + , 打开设置，搜 format on save，勾选 Editor: Format On Save
• 或者直接编辑 settings.json，确保有这行：
  "editor.formatOnSave": true
• 注意：如果同时开了 Prettier 或其他格式化器，得设默认格式化程序为 Clang-Format —— 在任意 C++ 文件里右键 → “格式化文档” → “配置默认格式化程序” → 选 Clang-Format

.clang-format 文件编码或位置错，规则全不生效

.clang-format 必须是 UTF-8 编码（无 BOM），且必须放在项目根目录，否则 VS Code 和 clangd 都会静默忽略。

• 常见错误：用记事本新建文件 → 默认 ANSI 编码 → 规则解析失败 → 格式化退回到默认 LLVM 风格
• 正确做法：用 VS Code 新建文件，保存时手动选 “UTF-8” 编码；或用命令行生成：
  clang-format -style=Google -dump-config > .clang-format
• 层级生效规则：VS Code 只读取当前打开文件所在目录向上最近的那个 .clang-format；子目录下放另一个 .clang-format，只影响该子目录及以下文件
• 验证是否加载成功：打开一个 .cpp 文件，状态栏右下角应显示 “Clang-Format” 字样；没显示，说明文件没被识别

BasedOnStyle 设错或参数拼写错误，格式化结果怪异

比如缩进变成 2 空格却设了 IndentWidth: 4，或者大括号始终换行但写了 BreakBeforeBraces: Attach —— 很可能是基础风格覆盖了你的自定义项。

• BasedOnStyle 是关键：设成 Google 后，IndentWidth 默认就是 2，你再写 IndentWidth: 4 才有效；设 LLVM 则默认是 2，但很多团队习惯 4，必须显式覆盖
• YAML 语法敏感：冒号后必须空一格，IndentWidth:4（缺空格）会被忽略；布尔值写 true 不要写 True 或 1
• 常用调试法：删掉整个 .clang-format，只留两行：
  Language: Cpp
BasedOnStyle: Google
  看是否回归 Google 风格；再逐行加参数，定位哪一行导致异常

实际项目里最常卡住的不是“怎么配”，而是“配了但没生效”——路径、编码、作用域这三关漏掉任何一个，clang-format 就像没装过一样。