在 VSCode 中配置并使用 Clang-Format 进行 C++ 代码自动格式化

2.2 这个配置是如何工作的？

• clangd 用哪一份规则格式化？ clangd 会从当前源文件所在目录开始，向上递归查找 .clang-format：因此：你仓库中的 .clang-format 就是 clangd 的风格来源。
  • 比如你在 ${workspaceFolder}/data/src/... 下编辑文件，
  • clangd 会一路向上找到 ${workspaceFolder}/data/.clang-format，
  • 然后按这份文件里的规则（缩进、括号风格等）来排版。
• 你需要做的事情
  • 保证工程里有一份有效的 .clang-format（例如 data/.clang-format）；
  • 安装并启用 clangd 扩展；
  • 按上述方式设置 editor.defaultFormatter 和 editor.formatOnSave。

谁在执行格式化？ [cpp] / [c] 中的

"editor.defaultFormatter": "llvm-vs-code-extensions.vscode-clangd"

决定了：保存 .cpp/.h/.c 时（editor.formatOnSave: true），以及执行 'Format Document' 时，VSCode 会调用 clangd 扩展 来格式化代码。

3. 方案二：cpptools + clang-format 负责格式化

如果你想直接使用 Microsoft C/C++ 扩展（cpptools）自带的 clang-format 集成来格式化，可以采用下面的配置。

3.1 配置示例（工作区 .vscode/settings.json）

{
  // 1）指定 cpptools 使用 clang-format 作为格式化引擎
  "C_Cpp.formatting": "clangFormat",
  // 2）指定 .clang-format 配置文件路径（使用你自己的配置）
  "C_Cpp.clang_format_style": "file:${workspaceFolder}/data/.clang-format",
  // 3）指定 clang-format 可执行文件路径
  "C_Cpp.clang_format_path": "/usr/bin/clang-format",
  // 4）通用编辑器行为
  "files.autoSave": "afterDelay",
  "editor.formatOnSave": true,
  // 5）为 C/C++ 指定 cpptools 作为默认 formatter
  "[cpp]": {
    "editor.defaultFormatter": "ms-vscode.cpptools",
    "editor.formatOnSave": true
  },
  "[c]": {
    "editor.defaultFormatter": "ms-vscode.cpptools",
    "editor.formatOnSave": true
  }
}

3.2 这个配置是如何工作的？

• 使用 clang-format 作为格式化后端；

• 从 /usr/bin/clang-format 启动 clang-format 可执行文件；

• 使用 ${workspaceFolder}/data/.clang-format 这份规则文件作为格式化风格。

• 你需要做的事情

  • 保证 /usr/bin/clang-format（或你指定的路径）是可执行的；
  • 在 ${workspaceFolder}/data/.clang-format 中写好团队统一的规则；
  • 安装并启用 C/C++（ms-vscode.cpptools）扩展；
  • 按上述方式设置 editor.defaultFormatter 和 C_Cpp.* 选项。

cpptools 如何使用 clang-format 和 .clang-format？

"C_Cpp.formatting": "clangFormat",
"C_Cpp.clang_format_path": "/usr/bin/clang-format",
"C_Cpp.clang_format_style": "file:${workspaceFolder}/data/.clang-format"

含义是：

谁在执行格式化？[cpp] / [c] 中的

"editor.defaultFormatter": "ms-vscode.cpptools"

决定了：保存 .cpp/.h/.c 时，以及执行 'Format Document' 时，VSCode 会调用 cpptools 扩展 来格式化代码。

4. 如何选择与验证

• 已经在使用 clangd 做补全 / 诊断： 推荐选 方案一，让 clangd 同时负责格式化，集成度更高。
• 团队更习惯 cpptools，不想引入 clangd： 可以选 方案二，由 cpptools + clang-format 负责格式化。

快速验证是否用到了你自己的 .clang-format：

1. 在 data/.clang-format 中把 ColumnLimit 改成一个明显的值（比如 60）；
2. 保存 .clang-format；
3. 打开任意 .cpp，执行 'Format Document' 或直接保存；
4. 如果代码行宽明显被折行到约 60 列，说明当前方案已经在正确使用这份 .clang-format。

5. 如何在 VSCode 中设置或修改这些配置

上面两种方案（clangd / cpptools）都可以通过 VSCode 的图形界面或直接编辑 JSON 来配置。

5.1 通过图形界面（Settings UI）配置

1. 菜单路径：文件 → 首选项 → 设置（或使用快捷键 Ctrl+,）。
2. 右上角切换设置作用域：
   • 如果你是在 Remote SSH / 远程容器中，用右上角的齿轮图标把作用域切到 远程；
   • 如果只想对当前仓库生效，可以选择 工作区。
3. 在搜索框中输入关键字：
   • default formatter：将 C++ 和 C 的默认格式化器设置为 clangd 扩展或 cpptools 扩展：
     • 方案一：选择 llvm-vs-code-extensions.vscode-clangd；
     • 方案二：选择 ms-vscode.cpptools。
   • formatOnSave：勾选 Editor: Format On Save（保存时自动格式化）。
   • clangd：按需要调整 clangd.path、clangd.arguments 等（与第 2 章示例对应）。

C_Cpp：按需要设置 C_Cpp.formatting = clangFormat、C_Cpp.clang_format_* 等（与第 3 章示例对应）。

用图形界面改完后，VSCode 会自动把对应项写入当前'用户 / 远程 / 工作区'的 settings.json 中。

5.2 直接编辑 settings.json（推荐远程环境）

1. 按 Ctrl+Shift+P 打开命令面板；
2. 搜索并选择：
   • Preferences: Open Remote Settings (JSON)（远程主机的设置）；或
   • Preferences: Open Workspace Settings (JSON)（当前工作区的设置）。
3. 在打开的 settings.json 中，粘贴或修改前文的示例配置（任选方案一或方案二那一段 JSON）。

一般来讲：

• 远程模式（Remote SSH）下，远程设置对应的 JSON 通常位于类似：
  • Linux 示例：~/.vscode-server/data/Machine/settings.json（仅供理解路径结构，不必手动编辑这个文件）。
• 工作区设置则保存在当前仓库根目录下：
  • <workspace>/.vscode/settings.json

6. 常见问题排查

如果配置未生效，请重点检查以下几点：

• .clang-format 文件是否存在，格式是否正确？
• clang-format 是否能在当前路径中运行（权限/依赖）？
• 是否正确安装并启用了 Microsoft C/C++ 插件？
• 当前 VSCode 是否连接到正确的工作区或远程环境？

7. 总结

通过以上配置步骤，你将实现：

• 高效的代码自动格式化
• 支持远程开发与本地开发统一体验
• 满足团队代码风格一致性要求

建议参考官方文档以进一步自定义 .clang-format 文件： Clang-Format Style Options