VSCode / Trae 搭建 STM32CubeMX 开发环境：插件配置、编译与调试流程

本文记录一套适合 STM32 日常开发的轻量化工作流：用 STM32CubeMX 完成芯片、时钟、外设和中间件初始化，用 VSCode 或 Trae 进行代码编辑、编译、下载和调试。相比完全依赖 STM32CubeIDE，这种方式更适合习惯现代编辑器、AI 辅助编码、CMake 工程和命令行构建的开发者。

一、整体思路

STM32 开发可以拆成三部分：

  1. 工程生成：STM32CubeMX 负责选择芯片、配置时钟树、GPIO、USART、SPI、I2C、ADC、FreeRTOS、USB 等外设，并生成初始化代码。
  2. 代码开发：VSCode 或 Trae 负责编辑代码、跳转定义、补全、格式化、Git 管理和 AI 辅助。
  3. 构建调试：通过 CMake / Makefile、Arm GCC、ST-LINK / J-Link、GDB 完成编译、烧录和调试。

推荐新项目优先使用 CMake。ST 官方当前的 VS Code 方案也围绕 CMake、clangd、调试适配器和 STM32 工具链做了整合。

二、需要安装的软件

1. 基础软件

软件 作用 说明
STM32CubeMX 生成 STM32 初始化工程 必装
VSCode 或 Trae 代码编辑与插件宿主 二选一，也可以都装
Git 版本管理 推荐安装
CMake CMake 工程配置 推荐安装
Ninja 更快的 CMake 构建后端 推荐安装
Arm GNU Toolchain 编译 ARM Cortex-M 固件 必装，需加入 PATH
ST-LINK Driver ST-LINK 下载调试驱动 Windows 用户必装
STM32CubeProgrammer 烧录、擦除、读写 Flash 推荐安装

如果使用 ST 官方的 STM32CubeIDE for Visual Studio Code 扩展包，部分命令行工具可以通过扩展的 Bundle Manager 管理；但调试探针驱动通常仍建议手动安装。

2. 安装后检查 PATH

打开终端，输入：

arm-none-eabi-gcc --version
cmake --version
ninja --version
git --version

如果提示“不是内部或外部命令”，说明对应工具没有加入系统环境变量，需要把工具的 bin 目录加入 PATH。

Windows 下常见路径示例：

C:\Program Files\CMake\bin
C:\Program Files\Git\cmd
C:\Program Files\Arm GNU Toolchain arm-none-eabi\bin

三、VSCode 插件配置

在 VSCode 扩展市场搜索并安装以下插件：

插件 插件 ID 用途
STM32CubeIDE for Visual Studio Code stmicroelectronics.stm32-vscode-extension ST 官方 STM32 开发扩展包
CMake Tools ms-vscode.cmake-tools 配置、构建 CMake 工程
clangd llvm-vs-code-extensions.vscode-clangd C/C++ 代码补全、跳转、诊断
Cortex-Debug marus25.cortex-debug Cortex-M 调试
C/C++ ms-vscode.cpptools C/C++ 基础能力，和 clangd 二选一或辅助使用
LinkerScript zixuanwang.linkerscript .ld 链接脚本语法高亮
MemoryView mcu-debug.memory-view 调试时查看内存，适合嵌入式
Peripheral Viewer mcu-debug.peripheral-viewer 查看外设寄存器，依赖 SVD

如果只想走官方集成路线，可以优先安装 STM32CubeIDE for Visual Studio Code 扩展包，它会整合项目创建、构建、调试、串口终端、板卡管理、外设查看等能力。

如果更喜欢手动、可迁移的通用方案，可以使用：

  • STM32CubeMX 生成 CMake / Makefile；
  • VSCode + CMake Tools 负责编译；
  • Cortex-Debug + OpenOCD / ST-LINK GDB Server 负责调试。

四、Trae 插件配置

Trae 的使用方式和 VSCode 类似，也有扩展商店。一般步骤如下：

  1. 打开 Trae 左侧的扩展商店。
  2. 搜索并安装 CMake、clangd、C/C++、Cortex-Debug 等插件。
  3. 如果 Trae 商店中找不到某个插件，可以去 VS Code Marketplace 下载 .vsix 文件。
  4. 回到 Trae 扩展商店，把 .vsix 拖入扩展面板进行安装。

建议优先安装：

ms-vscode.cmake-tools
llvm-vs-code-extensions.vscode-clangd
marus25.cortex-debug
zixuanwang.linkerscript
mcu-debug.memory-view
mcu-debug.peripheral-viewer

需要注意：Trae 对 VSCode 插件 API 的兼容程度可能随版本变化。如果某个插件安装失败，可以在 VS Code Marketplace 下载较早版本的 VSIX 再安装。

五、STM32CubeMX 新建工程

下面以常见的 STM32F103 / STM32F407 / STM32H743 等芯片流程为例，其他系列基本类似。

1. 新建芯片或开发板工程

打开 STM32CubeMX：

  1. 点击 New Project。
  2. 按芯片型号搜索，例如 STM32F103C8T6。
  3. 选择具体型号或开发板。
  4. 进入 Pinout & Configuration 页面。

2. 配置调试接口

在 System Core -> SYS 中配置：

Debug: Serial Wire

如果不打开 SWD，生成代码后可能无法正常使用 ST-LINK 调试，甚至某些引脚会被当作普通 GPIO 占用。

3. 配置时钟

在 System Core -> RCC 中按硬件选择：

HSE: Crystal/Ceramic Resonator   // 使用外部晶振
LSE: Crystal/Ceramic Resonator   // 使用外部 32.768kHz 晶振，可选

然后进入 Clock Configuration：

  • 设置 PLL 输入源；
  • 配置 SYSCLK；
  • 确认 AHB、APB1、APB2 不超频；
  • 确认 USB、SDIO、ADC 等外设时钟满足要求。

4. 配置外设

常见外设示例：

GPIO      LED、按键、片选信号
USART     串口打印、通信
SPI       Flash、屏幕、传感器
I2C       EEPROM、传感器
TIM       PWM、编码器、周期中断
ADC       电压采样
DMA       串口/SPI/ADC 高速搬运
FreeRTOS  多任务调度

5. Project Manager 设置

进入 Project Manager：

Project Name: stm32_demo
Project Location: D:\STM32Project\stm32_demo
Toolchain / IDE: CMake

如果你的 CubeMX 版本没有 CMake 选项，可以先选择：

Toolchain / IDE: Makefile

然后用 VSCode / Trae 的终端执行 make 构建。

建议在 Code Generator 中勾选：

Generate peripheral initialization as a pair of '.c/.h' files per peripheral
Keep User Code when re-generating

这样每个外设会拆成独立文件，工程结构更清晰；重新生成代码时，也能尽量保留 USER CODE BEGIN 和 USER CODE END 之间的手写代码。

六、用 VSCode / Trae 打开工程

CubeMX 生成工程后，用 VSCode 或 Trae 打开工程根目录。

典型目录结构如下：

stm32_demo/
├─ Core/
│  ├─ Inc/
│  └─ Src/
├─ Drivers/
├─ Middlewares/
├─ CMakeLists.txt
├─ CMakePresets.json
├─ STM32xxxx_FLASH.ld
└─ stm32_demo.ioc

注意：尽量打开工程根目录，而不是只打开 Core/Src。否则 CMake、头文件索引、调试配置都可能找不到正确路径。

七、CMake 工程编译

如果安装了 CMake Tools，VSCode / Trae 底部通常会出现 CMake 状态栏。

常用操作：

  1. 选择 Kit：一般选 GCC for arm-none-eabi 或 ST 扩展提供的工具链。
  2. 选择 Preset：例如 Debug、Release。
  3. 点击 Configure。
  4. 点击 Build。

也可以直接在终端中编译：

cmake --preset Debug
cmake --build --preset Debug

如果没有 preset，也可以手动创建构建目录：

cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Debug
cmake --build build

编译成功后，一般会生成：

build/stm32_demo.elf
build/stm32_demo.hex
build/stm32_demo.bin

不同 CubeMX 版本和 CMake 模板生成的文件名可能略有不同，以实际 build 目录为准。

八、Makefile 工程编译

如果 CubeMX 生成的是 Makefile 工程，打开终端执行：

make -j8

清理工程：

make clean

Windows 下如果没有 make，可以安装：

  • MSYS2；
  • xPack GNU Arm Embedded GCC；
  • STM32CubeCLT；
  • 或其他自带 make 的工具链环境。

九、下载固件

方式一：STM32CubeProgrammer 图形界面

  1. 打开 STM32CubeProgrammer。
  2. 选择 ST-LINK。
  3. 点击 Connect。
  4. 选择 .hex 或 .bin 文件。
  5. 点击 Download。

方式二：命令行下载

如果安装了 STM32CubeProgrammer CLI，可以使用：

STM32_Programmer_CLI -c port=SWD -w build/stm32_demo.hex -v -rst

如果使用 .bin，通常需要指定 Flash 地址：

STM32_Programmer_CLI -c port=SWD -w build/stm32_demo.bin 0x08000000 -v -rst

十、调试配置

1. 使用 ST 官方 VS Code 扩展调试

如果安装的是 STM32CubeIDE for Visual Studio Code，可以优先使用扩展提供的调试入口。它对 ST-LINK、J-Link、外设寄存器、RTOS 视图和串口终端做了较多集成，适合新手。

2. 使用 Cortex-Debug 调试

如果使用 Cortex-Debug，可以在工程下新建：

.vscode/launch.json

示例配置：

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug STM32",
      "type": "cortex-debug",
      "request": "launch",
      "servertype": "openocd",
      "cwd": "${workspaceFolder}",
      "executable": "${workspaceFolder}/build/stm32_demo.elf",
      "device": "STM32F103C8",
      "configFiles": [
        "interface/stlink.cfg",
        "target/stm32f1x.cfg"
      ],
      "runToEntryPoint": "main",
      "svdFile": "${workspaceFolder}/STM32F103.svd"
    }
  ]
}

需要根据芯片修改：

device
executable
target/stm32f1x.cfg
svdFile

常见 OpenOCD target：

STM32F1: target/stm32f1x.cfg
STM32F4: target/stm32f4x.cfg
STM32G0: target/stm32g0x.cfg
STM32H7: target/stm32h7x.cfg

如果使用 J-Link，把 servertype 和配置改成 J-Link 对应方式即可。

十一、推荐的 settings.json

可以在工程下创建：

.vscode/settings.json

示例：

{
  "C_Cpp.intelliSenseEngine": "disabled",
  "clangd.arguments": [
    "--background-index",
    "--compile-commands-dir=build",
    "--query-driver=**/arm-none-eabi-*"
  ],
  "cmake.configureOnOpen": true,
  "files.associations": {
    "*.h": "c",
    "*.ld": "linkerscript"
  },
  "editor.formatOnSave": true
}

如果你使用 Microsoft C/C++ 插件而不是 clangd，可以不要禁用 C_Cpp.intelliSenseEngine。

十二、推荐的 extensions.json

团队协作时，可以把推荐插件写入：

.vscode/extensions.json

内容如下：

{
  "recommendations": [
    "stmicroelectronics.stm32-vscode-extension",
    "ms-vscode.cmake-tools",
    "llvm-vs-code-extensions.vscode-clangd",
    "marus25.cortex-debug",
    "zixuanwang.linkerscript",
    "mcu-debug.memory-view",
    "mcu-debug.peripheral-viewer"
  ]
}

这样其他人打开工程时，VSCode 会提示安装推荐插件。

十三、用户代码应该写在哪里

CubeMX 生成的文件中有大量标记：

/* USER CODE BEGIN 0 */

/* USER CODE END 0 */

自己的代码尽量写在 USER CODE BEGIN 和 USER CODE END 之间。例如：

/* USER CODE BEGIN 2 */
HAL_UART_Transmit(&huart1, (uint8_t *)"hello stm32\r\n", 13, 100);
/* USER CODE END 2 */

不要随意修改 CubeMX 自动生成区域，否则下次重新 Generate Code 时可能被覆盖。

更推荐的工程组织方式是：

Core/
├─ App/
│  ├─ app_main.c
│  ├─ bsp_led.c
│  ├─ bsp_uart.c
│  └─ protocol.c
├─ Inc/
└─ Src/

然后在 main.c 里只保留入口调用：

/* USER CODE BEGIN 2 */
App_Init();
/* USER CODE END 2 */

while (1)
{
  /* USER CODE BEGIN WHILE */
  App_Loop();
  /* USER CODE END WHILE */
}

这样 CubeMX 负责底层初始化，业务代码放在独立目录，后期维护会舒服很多。

十四、常见问题

1. 代码能编译，但 VSCode / Trae 头文件飘红

原因通常是索引器没有读取到真实编译参数。

解决方法：

  1. 先完整执行一次 CMake Configure 和 Build。
  2. 确认 build/compile_commands.json 存在。
  3. clangd 设置中指定：
"--compile-commands-dir=build"

2. ST-LINK 连接失败

检查：

  • 是否安装 ST-LINK 驱动；
  • USB 线是否是数据线；
  • CubeMX 中 SYS -> Debug 是否选择 Serial Wire；
  • 芯片是否供电正常；
  • SWDIO、SWCLK、GND 是否接对；
  • 是否有程序把调试引脚复用成了 GPIO。

3. 下载后程序不运行

检查：

  • Flash 起始地址是否为 0x08000000；
  • 链接脚本 .ld 是否匹配芯片 Flash / RAM 大小；
  • 时钟配置是否超频；
  • 是否开启了看门狗；
  • main() 是否进入 HardFault；
  • Boot0 引脚是否处于正确电平。

4. 重新生成代码后手写代码丢失

只把代码写到：

/* USER CODE BEGIN xxx */
/* USER CODE END xxx */

之间。自动生成区域不要手动改。复杂业务逻辑尽量放到自己新建的 .c/.h 文件中。

5. CMake 找不到 arm-none-eabi-gcc

检查：

arm-none-eabi-gcc --version

如果命令不存在，需要把 Arm GNU Toolchain 的 bin 目录加入环境变量，然后重启 VSCode / Trae。

十五、VSCode、Trae、STM32CubeIDE 怎么选

环境 优点 适合人群
STM32CubeIDE 官方完整 IDE，开箱即用 初学者、调试链路不想折腾
VSCode 插件生态成熟，CMake/Git/终端体验好 想要轻量和可配置开发流的用户
Trae 类 VSCode 体验，AI 辅助能力更突出 希望边写嵌入式边用 AI 辅助分析代码

个人建议：

  • 刚入门 STM32：先用 STM32CubeIDE 跑通下载和调试。
  • 已经熟悉 HAL / LL：使用 CubeMX + VSCode / Trae。
  • 团队项目：优先 CMake，减少 IDE 绑定，方便 CI 自动构建。

十六、总结

用 VSCode 或 Trae 开发 STM32 的核心不是“换一个编辑器”，而是把工程拆清楚：

  • CubeMX 负责芯片配置和初始化代码生成；
  • CMake / Makefile 负责可复现构建；
  • Arm GCC 负责编译；
  • ST-LINK / J-Link + GDB 负责调试；
  • VSCode / Trae 负责编辑、插件、终端、Git 和 AI 辅助。

新项目建议优先选择 CubeMX 的 CMake 工程，再配合 ST 官方 VS Code 扩展包或通用的 CMake Tools + clangd + Cortex-Debug。这样既保留了 CubeMX 的外设配置效率，又能获得现代编辑器的开发体验。

参考资料

  • ST 官方文档：STM32CubeIDE for Visual Studio Code
    https://dev.st.com/stm32cube-docs/stm32cubeide-vscode/1.0.0/en/docs/markup/introduction/overview.html
  • VS Code Marketplace：STM32CubeIDE for Visual Studio Code
    https://marketplace.visualstudio.com/items?itemName=stmicroelectronics.stm32-vscode-extension
  • ST 官方文档：CMake in STM32CubeIDE for Visual Studio Code
    https://dev.st.com/stm32cube-docs/stm32cubeide-vscode/1.0.0/en/docs/markup/basic_concepts/cmake.html
  • Trae 官方文档：How to Manage Extensions in Trae IDE
    https://traeide.com/docs/how-to-manage-extensions-in-trae-ide
  • VS Code 官方文档：Extensions
    https://code.visualstudio.com/docs/getstarted/extensions
# vscode # stm32 # ide
Logo
AtomGit AI 社区

AtomGit AI 社区提供模型库、数据集、Agent、Token等资源

更多推荐

cover

程序员用 AI 会员，真正要省的不是打字时间，而是上下文成本

avatar AtomGit AI 社区
cover

开 AI 会员前，开发者先用这 3 个模板验证：Debug、接口文档、测试用例能不能跑进工作流

avatar AtomGit AI 社区
cover

从企业信息诊断到AI搜索可见度评估

avatar AtomGit AI 社区