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

在 VSCode 中用 Clang-Format 自动格式化 C++ 代码（clangd 与 cpptools 两种方案）

本文介绍两种常见方案，每种方案都使用仓库中的 .clang-format 作为唯一格式规则，区别在于'谁来执行格式化'：

方案一：clangd 扩展负责格式化
方案二：Microsoft C/C++ 扩展（cpptools）+ clang-format 负责格式化

1. 前提条件

1.1 安装必要扩展

至少安装：

clangd 扩展：提供 C++ 语言服务和格式化（方案一主角）
C/C++（ms-vscode.cpptools）扩展：提供 IntelliSense、调试等功能（方案二主角）

1.2 确保已安装 clang / clang-format

远程或本地环境中需要有 clang / clang-format，常见位置例如：

/usr/bin/clangd /usr/bin/clang++ /usr/bin/clang-format

如果你的 SDK 提供了自己的 clang-format，也可以用 SDK 里的路径：

${workspaceFolder}/clangd_tools/bin/clang-format

1.3 工程中存在 `.clang-format`

在仓库根目录或组件根目录放置 .clang-format，例如：

${workspaceFolder}/data/.clang-format

clangd 和 cpptools 都可以读取这份文件作为风格定义。规则说明详见官方文档：https://clang.llvm.org/docs/ClangFormatStyleOptions.html

2. 方案一：clangd 扩展负责格式化

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

{
  // 1）clangd 语言服务器配置
  "clangd.path": "/usr/bin/clangd",
  "clangd.arguments": [
    "--background-index", "-j", "24", "--clang-tidy", "--clang-tidy-checks=performance-*,bugprone-*,misc-*,google-*,modernize-*,cppcoreguidelines-*,hicpp-*,clang-analyzer-*,concurrency-*,boost-*,readability-*,portability-*",
    "--query-driver=/usr/bin/clang++",
    "--compile-commands-dir=${workspaceFolder}/build/compile_commands",
    "--all-scopes-completion", "--completion-style=detailed", "--header-insertion-decorators", "--header-insertion=iwyu", "--include-cleaner-stdlib", "--pch-storage=memory", "--enable-config"
  ],
  // 2）通用编辑器行为
  "files.autoSave": "afterDelay",
  "editor.formatOnSave": true,
  // 3）为 C/C++ 指定 clangd 扩展作为默认 formatter
  "[cpp]": {
    "editor.defaultFormatter": "llvm-vs-code-extensions.vscode-clangd",
    "editor.formatOnSave": true
  },
  "[c]": {
    "editor.defaultFormatter": "llvm-vs-code-extensions.vscode-clangd",
    "editor.formatOnSave": true
  }
}

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：

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

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

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

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

菜单路径：文件 → 首选项 → 设置（或使用快捷键 Ctrl+,）。
右上角切换设置作用域：
- 如果你是在 Remote SSH / 远程容器中，用右上角的齿轮图标把作用域切到远程；
- 如果只想对当前仓库生效，可以选择 工作区。
在搜索框中输入关键字：
- 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（推荐远程环境）

按 Ctrl+Shift+P 打开命令面板；
搜索并选择：
- Preferences: Open Remote Settings (JSON)（远程主机的设置）；或
- Preferences: Open Workspace Settings (JSON)（当前工作区的设置）。
在打开的 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

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

在 VSCode 中用 Clang-Format 自动格式化 C++ 代码（clangd 与 cpptools 两种方案）

1. 前提条件

1.1 安装必要扩展

1.2 确保已安装 clang / clang-format

1.3 工程中存在 `.clang-format`

2. 方案一：clangd 扩展负责格式化

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

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

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

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

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

4. 如何选择与验证

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

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

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

6. 常见问题排查

7. 总结

更多推荐文章

相关免费在线工具

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

在 VSCode 中用 Clang-Format 自动格式化 C++ 代码（clangd 与 cpptools 两种方案）

1. 前提条件

1.1 安装必要扩展

1.2 确保已安装 clang / clang-format

1.3 工程中存在 .clang-format

2. 方案一：clangd 扩展负责格式化

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

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

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

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

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

4. 如何选择与验证

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

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

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

6. 常见问题排查

7. 总结

微信扫一扫，关注极客日志

更多推荐文章

相关免费在线工具

1.3 工程中存在 `.clang-format`