VSCode 配置 Clangd 开发 STM32

前言#

在 STM32 的传统开发环境中，常见的选择是使用 MDK-ARM 或 IAR 等 IDE。然而，这些工具尽管功能强大，但在代码智能提示、现代化编辑体验等方面存在不足。VSCode 作为当今非常流行的代码编辑器，结合 Clangd 提供的强大代码分析能力，可以为 STM32 开发带来更现代化的体验，并且 VSCode 还有众多 AI 插件可以为代码进行补全。

NOTE
2025.10.21 更新
文章写于 STM32 VS Code Extension 的 v1.0 时期
时代滚滚向前，笔者博客文章具有滞后性，目前拓展已经更新到了 v3.6.4 版本，相较于先前，配置更加简单，插件在安装后，会提示安装开发所需的工具链，所以只需要安装一个拓展（即 STM32 VS Code Extension），按照提示安装工具链后，从 CubeMX 生成 CMake 项目即可，无需额外配置
所以可以基本跳过配置步骤章节（不过仍然需要安装 STM32CubeMX 来配置项目），您仍然可以参考增强配置以提供更好的开发体验
如果嫌弃 STM32 VS Code Extension 安装太多拓展导致 VSCode 界面混乱，可以巧用 VSCode 的配置文件功能

配置步骤#

1. 基础环境安装#

首先，下载并安装所需的基础工具：

安装 Visual Studio Code，代码编辑器
安装 LLVM/Clang，提供 Clangd 语言服务器
安装 STM32CubeMX，用于生成 STM32 项目代码
安装 STM32CubeCLT，STM32CubeCLT 提供 STM32 开发工具集，包含 arm-none-eabi-gcc 编译器、STM32 的 SVD 文件，同时包含 Ninja、CMake 构建工具

确保 LLVM、CMake、arm-none-eabi-gcc、Ninja 已添加到系统环境变量，可以在命令行中执行 clangd --version、cmake --version、arm-none-eabi-gcc --version、ninja --version 进行验证。

2. 安装 VSCode 扩展#

TIP
Clangd 插件与 C/C++ 插件冲突，Clangd 需要禁用 C/C++ 插件才能正常工作。

在 VSCode 中，通过扩展市场安装以下必要扩展：

clangd - 提供 C/C++ 代码智能感知
STM32 VS Code Extension - 提供 STM32 开发工具集

3. 配置 STM32 开发环境#

安装完了 STM32 VS Code Extension 扩展后，需要配置 STM32CubeCLT 路径：

在 VSCode 中，按下 Ctrl + Shift + P 打开命令面板
搜索并选择 STM32 VS Code Extension: Configure Cube CLT Path 命令
找到 STM32CubeCLT 并选择，如果 STM32CubeCLT 正确安装，VSCode 将自动检测到路径

4. 创建并配置项目#

使用 STM32CubeMX 创建新项目，在生成代码时选择 CMake 作为项目生成类型
使用 VSCode 打开生成的项目文件夹
在 VSCode 左侧边栏点击 STM32 VS Code Extension 扩展（ST 小蝴蝶标志），选择 Import CMake Project 选项
在弹出的文件浏览器中，导航并选择刚才用 STM32CubeMX 生成的项目根目录

5. 配置 Clangd#

在 VSCode 中，按下 Ctrl + Shift + P 打开命令面板
搜索并选择 首选项: 打开工作区设置 (JSON)
在打开的 settings.json 文件中，添加以下配置：

1
{
2
    "clangd.arguments": [
3
        "--query-driver=C:/ST/STM32CubeCLT_1.17.0/GNU-tools-for-STM32/bin/arm-none-eabi-*", // 修改为 arm-none-eabi-gcc 实际路径
4
        "--compile-commands-dir=${workspaceFolder}/build/Debug" // 修改为项目构建目录
5
    ],
6
}

6. 完成配置#

在 VSCode 中，按下 Ctrl + Shift + P 打开命令面板
搜索并选择 开发人员: 重新加载窗口 或 clangd: Restart language server
等待 VSCode 重新加载，Clangd 将开始解析项目代码

至此，基本配置已完成。如果一切正常，您应该能看到代码智能提示正常工作，没有红色波浪线错误提示，并且由于使用了 STM32 VS Code Extension 扩展配置项目，在连接 ST-Link 后可以直接 F5 对程序进行调试。

增强配置#

以下是一些可选的增强配置，可以进一步提升您的开发体验：

代码格式化配置#

在项目根目录添加 .clang-format 文件，可以自定义代码格式化规则：

.clang-format（点击展开）

1
# Generated by CLion for STL
2
BasedOnStyle: LLVM
3

4
AccessModifierOffset: -4
5
AlignAfterOpenBracket: DontAlign
6
AlignConsecutiveAssignments: Consecutive
7
AlignConsecutiveMacros: Consecutive
8
AlignEscapedNewlines: Left
9
AlignOperands: AlignAfterOperator
10
AlignTrailingComments:
11
  Kind: Never
12
AllowShortFunctionsOnASingleLine: Empty
13
AlwaysBreakTemplateDeclarations: Yes
14
BreakBeforeBinaryOperators: NonAssignment
15
ColumnLimit: 120
16
IncludeBlocks: Regroup
17
IncludeCategories:
18
  - Regex: '^<yvals(_core)?\.h>$'
19
    Priority: 1
20
  - Regex: '^<(Windows|userenv)\.h>$'
21
    Priority: 3
22
    SortPriority: 3
23
  - Regex: '^<WinIoCtl\.h>$'
24
    Priority: 3
25
    SortPriority: 4
26
  - Regex: '^<__.*\.hpp>$'
27
    Priority: 2
28
  - Regex: '\.hpp[>"]$'
29
    Priority: 5
30
  - Regex: '.*'
31
    Priority: 2
32
IndentCaseBlocks: true
33
IndentWidth: 4
34
IndentWrappedFunctionNames: true
35
InsertBraces: true
36
InsertNewlineAtEOF: true
37
MaxEmptyLinesToKeep: 2
38
NamespaceIndentation: All
39
PointerAlignment: Left
40
RemoveSemicolon: true
41
SpaceAfterCStyleCast: true
42
SpaceBeforeParens: Custom
43
SpaceBeforeParensOptions:
44
  AfterRequiresInClause: true
45
StatementMacros:
46
  - _EXTERN_CXX_WORKAROUND
47
  - _END_EXTERN_CXX_WORKAROUND
48
  - _STD_BEGIN
49
  - _STD_END
50
  - _STDEXT_BEGIN
51
  - _STDEXT_END
52
  - _FMT_P2286_BEGIN
53
  - _FMT_P2286_END
54
  - _EXTERN_C_UNLESS_PURE
55
  - _END_EXTERN_C_UNLESS_PURE

静态代码分析#

在项目根目录添加 .clang-tidy 文件到项目根目录，开启更强大的代码静态分析：

.clang-tidy（点击展开）

1
# Generated from CLion Inspection settings
2
---
3
Checks: '-*,
4
bugprone-argument-comment,
5
bugprone-assert-side-effect,
6
bugprone-bad-signal-to-kill-thread,
7
bugprone-branch-clone,
8
bugprone-copy-constructor-init,
9
bugprone-dangling-handle,
10
bugprone-dynamic-static-initializers,
11
bugprone-fold-init-type,
12
bugprone-forward-declaration-namespace,
13
bugprone-forwarding-reference-overload,
14
bugprone-inaccurate-erase,
15
bugprone-incorrect-roundings,
16
bugprone-integer-division,
17
bugprone-lambda-function-name,
18
bugprone-macro-parentheses,
19
bugprone-macro-repeated-side-effects,
20
bugprone-misplaced-operator-in-strlen-in-alloc,
21
bugprone-misplaced-pointer-arithmetic-in-alloc,
22
bugprone-misplaced-widening-cast,
23
bugprone-move-forwarding-reference,
24
bugprone-multiple-statement-macro,
25
bugprone-no-escape,
26
bugprone-parent-virtual-call,
27
bugprone-posix-return,
28
bugprone-reserved-identifier,
29
bugprone-sizeof-container,
30
bugprone-sizeof-expression,
31
bugprone-spuriously-wake-up-functions,
32
bugprone-string-constructor,
33
bugprone-string-integer-assignment,
34
bugprone-string-literal-with-embedded-nul,
35
bugprone-suspicious-enum-usage,
36
bugprone-suspicious-include,
37
bugprone-suspicious-memset-usage,
38
bugprone-suspicious-missing-comma,
39
bugprone-suspicious-semicolon,
40
bugprone-suspicious-string-compare,
41
bugprone-suspicious-memory-comparison,
42
bugprone-suspicious-realloc-usage,
43
bugprone-swapped-arguments,
44
bugprone-terminating-continue,
45
bugprone-throw-keyword-missing,
46
bugprone-too-small-loop-variable,
47
bugprone-undefined-memory-manipulation,
48
bugprone-undelegated-constructor,
49
bugprone-unhandled-self-assignment,
50
bugprone-unused-raii,
51
bugprone-unused-return-value,
52
bugprone-use-after-move,
53
bugprone-virtual-near-miss,
54
cert-dcl21-cpp,
55
cert-dcl58-cpp,
56
cert-err34-c,
57
cert-err52-cpp,
58
cert-err60-cpp,
59
cert-flp30-c,
60
cert-msc50-cpp,
61
cert-msc51-cpp,
62
cert-str34-c,
63
cppcoreguidelines-interfaces-global-init,
64
cppcoreguidelines-narrowing-conversions,
65
cppcoreguidelines-pro-type-member-init,
66
cppcoreguidelines-pro-type-static-cast-downcast,
67
cppcoreguidelines-slicing,
68
google-default-arguments,
69
google-explicit-constructor,
70
google-runtime-operator,
71
hicpp-exception-baseclass,
72
hicpp-multiway-paths-covered,
73
misc-misplaced-const,
74
misc-new-delete-overloads,
75
misc-no-recursion,
76
misc-non-copyable-objects,
77
misc-throw-by-value-catch-by-reference,
78
misc-unconventional-assign-operator,
79
misc-uniqueptr-reset-release,
80
modernize-avoid-bind,
81
modernize-concat-nested-namespaces,
82
modernize-deprecated-headers,
83
modernize-deprecated-ios-base-aliases,
84
modernize-loop-convert,
85
modernize-make-shared,
86
modernize-make-unique,
87
modernize-pass-by-value,
88
modernize-raw-string-literal,
89
modernize-redundant-void-arg,
90
modernize-replace-auto-ptr,
91
modernize-replace-disallow-copy-and-assign-macro,
92
modernize-replace-random-shuffle,
93
modernize-return-braced-init-list,
94
modernize-shrink-to-fit,
95
modernize-unary-static-assert,
96
modernize-use-auto,
97
modernize-use-bool-literals,
98
modernize-use-emplace,
99
modernize-use-equals-default,
100
modernize-use-equals-delete,
101
modernize-use-nodiscard,
102
modernize-use-noexcept,
103
modernize-use-nullptr,
104
modernize-use-override,
105
modernize-use-transparent-functors,
106
modernize-use-uncaught-exceptions,
107
mpi-buffer-deref,
108
mpi-type-mismatch,
109
openmp-use-default-none,
110
performance-faster-string-find,
111
performance-for-range-copy,
112
performance-implicit-conversion-in-loop,
113
performance-inefficient-algorithm,
114
performance-inefficient-string-concatenation,
115
performance-inefficient-vector-operation,
116
performance-move-const-arg,
117
performance-move-constructor-init,
118
performance-no-automatic-move,
119
performance-noexcept-move-constructor,
120
performance-trivially-destructible,
121
performance-type-promotion-in-math-fn,
122
performance-unnecessary-copy-initialization,
123
performance-unnecessary-value-param,
124
portability-simd-intrinsics,
125
readability-avoid-const-params-in-decls,
126
readability-const-return-type,
127
readability-container-size-empty,
128
readability-convert-member-functions-to-static,
129
readability-delete-null-pointer,
130
readability-deleted-default,
131
readability-inconsistent-declaration-parameter-name,
132
readability-make-member-function-const,
133
readability-misleading-indentation,
134
readability-misplaced-array-index,
135
readability-non-const-parameter,
136
readability-redundant-control-flow,
137
readability-redundant-declaration,
138
readability-redundant-function-ptr-dereference,
139
readability-redundant-smartptr-get,
140
readability-redundant-string-cstr,
141
readability-redundant-string-init,
142
readability-simplify-subscript-expr,
143
readability-static-accessed-through-instance,
144
readability-static-definition-in-anonymous-namespace,
145
readability-string-compare,
146
readability-uniqueptr-delete-release,
147
readability-use-anyofallof'

启用 C++ 支持#

如需在项目中使用 C++，在 CMakeLists.txt 中添加以下语句：

1
set(CMAKE_CXX_STANDARD 20)
2
set(CMAKE_CXX_STANDARD_REQUIRED ON)
3
set(CMAKE_CXX_EXTENSIONS ON)
4

5
enable_language(C ASM CXX) # 修改原有的 enable_language 行

这将启用 C++ 支持，并将 C++ 标准设置为 C++20。

生成 HEX 和 BIN 文件#

为了方便固件烧录，可以在 CMakeLists.txt 中添加以下命令自动生成 hex 和 bin 文件：

1
# Add custom command to generate binary and hex files
2
add_custom_command(TARGET ${CMAKE_PROJECT_NAME} POST_BUILD
3
    COMMAND ${CMAKE_OBJCOPY} -O binary ${CMAKE_PROJECT_NAME}.elf ${CMAKE_PROJECT_NAME}.bin
4
    COMMAND ${CMAKE_OBJCOPY} -O ihex ${CMAKE_PROJECT_NAME}.elf ${CMAKE_PROJECT_NAME}.hex
5
)

添加自定义源文件#

为了更好地组织代码，可以将自己的源文件放在独立的目录中，在 CMakeLists.txt 中添加，比如我需要添加 Core/App 目录下的所有源文件：

1
# Add sources path
2
file(GLOB_RECURSE SOURCES
3
    ${CMAKE_SOURCE_DIR}/Core/App/*.*
4
)
5

6
# Add sources to executable
7
target_sources(${CMAKE_PROJECT_NAME} PRIVATE
8
    # Add user sources here
9
    ${SOURCES}
10
)

添加自定义头文件路径#

同样，可以添加自定义头文件路径，比如我需要添加 Core/App 目录下的头文件：

1
# Add include paths
2
target_include_directories(${CMAKE_PROJECT_NAME} PRIVATE
3
    # Add user defined include paths
4
    ${CMAKE_SOURCE_DIR}/Core/App
5
)

优化编译选项#

可以修改 gcc-arm-none-eabi.cmake 文件中的编译选项，根据需要启用或禁用特定功能：

1
# 修改 C++ 标志，根据需要启用或禁用 RTTI 和异常
2
set(CMAKE_CXX_FLAGS "${CMAKE_C_FLAGS} -fno-rtti -fno-exceptions -fno-threadsafe-statics")
3

4
set(CMAKE_C_LINK_FLAGS "${TARGET_FLAGS}")
5
set(CMAKE_C_LINK_FLAGS "${CMAKE_C_LINK_FLAGS} -T \"${CMAKE_SOURCE_DIR}/STM32F411XX_FLASH.ld\"")
6
# 删除 `nano.specs` 以使用完整标准库
7
set(CMAKE_C_LINK_FLAGS "${CMAKE_C_LINK_FLAGS} --specs=nano.specs")
8
set(CMAKE_C_LINK_FLAGS "${CMAKE_C_LINK_FLAGS} -Wl,-Map=${CMAKE_PROJECT_NAME}.map -Wl,--gc-sections")
9
set(CMAKE_C_LINK_FLAGS "${CMAKE_C_LINK_FLAGS} -Wl,--start-group -lc -lm -Wl,--end-group")
10
set(CMAKE_C_LINK_FLAGS "${CMAKE_C_LINK_FLAGS} -Wl,--print-memory-usage")
11

12
# 添加浮点数打印支持（如果使用完整标准库，可以不添加，因为完整标准库已经包含了浮点数打印支持）
13
set(CMAKE_C_LINK_FLAGS "${CMAKE_C_LINK_FLAGS} -u _printf_float")
14
set(CMAKE_CXX_LINK_FLAGS "${CMAKE_C_LINK_FLAGS} -Wl,--start-group -lstdc++ -lsupc++ -Wl,--end-group")

常见问题解决#

智能提示不工作#

检查 Clangd 扩展是否正确安装
确保 Clangd 已经成功构建了 compile_commands.json 文件
验证 settings.json 中的编译器路径是否正确
Clangd 插件可能会将 C++ 头文件 .h 错误识别为 C 头文件，特别是在使用 C++ 特性时，将导致解析错误，可以使用 .hpp 扩展名代替 .h 来命名 C++ 头文件