STM32 VSCode 开发-与STM32CubeMX协同开发环境搭建

一、开发方案核心原理与优势

本方案基于ST官方推出的STM32Cube for Visual Studio Code 插件，采用CMake工程管理框架，是ST官方主推的新一代STM32开发方案，核心优势如下：

1. 工具链自动管理 ：内置Bundles Manager工具，可自动下载、配置工程所需的ARM GCC编译工具链、CMake、调试组件等，无需手动安装STM32CubeCLT及相关工具，大幅降低环境配置门槛；

2. 开发环境统一：VSCode完全免费、开源生态丰富、插件扩展性强，可同时适配Python、前端、后端等多场景开发，避免多开发工具切换成本；

3. 官方原生支持：官方插件原生支持STM32芯片工程解析、寄存器查看、RTOS状态监控、在线调试、ST-Link固件升级等全流程开发功能，开发体验优于传统Keil MDK。

二、前置软件安装

2.1 STM32CubeMX安装

STM32CubeMX为ST官方推出的芯片图形化配置工具，用于生成STM32工程初始化代码，本教程不赘述安装流程，可参考STM32基础开发相关教程完成安装与对应芯片包导入。

2.2 VSCode软件安装

1. 访问VSCode官方网站，下载对应操作系统的安装包；

2. 运行安装包，勾选同意用户许可协议，点击下一步；

3. 选择软件安装路径，点击下一步；

4. 勾选安装界面全部附加任务选项，点击下一步→安装，等待安装完成后自动启动VSCode。

2.3 VSCode中文语言包配置

VSCode默认界面为英文，可通过官方语言包切换为简体中文：

1. 点击VSCode左侧导航栏扩展市场 图标（快捷键Ctrl+Shift+X）；

2. 在搜索框输入Chinese，找到微软官方发布的「中文(简体)语言包」，点击Install安装；

3. 安装完成后，VSCode右下角弹出语言切换与重启提示，点击确认，软件自动重启后界面切换为简体中文。

2.4 VSCode配置文件(Profiles)创建（推荐）

VSCode的**配置文件(Profiles)**功能可实现不同开发场景的插件与配置隔离，避免多场景开发时插件互相干扰，推荐用于STM32专属开发环境配置：

1. 点击VSCode左下角齿轮图标，选择「配置文件」，打开配置文件管理面板；

2. 点击「新建配置文件」，为配置文件命名（如STM32），点击「创建」，生成全新的空白配置文件；

3. 点击配置文件旁的对号，切换至新建的STM32配置文件，后续所有STM32开发相关插件均安装在此配置文件中；

4. 后续可通过左下角配置文件入口，快速切换不同开发场景的配置文件。

三、STM32官方开发插件安装与环境初始化

3.1 插件安装

1. 确保已切换至STM32专属配置文件，打开VSCode扩展市场；

2. 在搜索框输入STM32，找到ST官方发布的STM32Cube for Visual Studio Code插件；

3. 插件安装说明：

   • 若插件已发布正式版（版本号≥3.0.0），直接点击「安装」即可；

   • 若仍为预览版，需点击安装按钮旁的下拉框，选择「安装预发布版本」（示例版本号2.1.1）；

4. 插件将自动安装关联依赖插件，覆盖语法解析、编译分析、调试管理、寄存器查看、RTOS状态监控等全流程功能，等待全部安装完成。

3.2 开发环境自动初始化

1. 插件安装完成后，VSCode左侧导航栏将新增STM32专属图标（ST蝴蝶标志），点击切换至STM32插件管理面板；

2. 插件将自动启动Bundles Manager，在后台自动下载并安装全局开发工具链，包括CMake、ARM GCC编译器、调试组件等，首次安装约需1-2分钟；

3. 安装完成后，可在插件面板的Bundles管理界面，查看已安装的全局工具链版本与状态。

四、基于STM32CubeMX的工程创建

4.1 工程基础配置

1. 打开STM32CubeMX，点击「ACCESS TO MCU SELECTOR」，进入芯片选择器；

2. 在芯片列表中选择目标芯片（本教程以STM32F103系列为例），点击「Start Project」创建工程；

3. 调试接口配置：进入「Pinout & Configuration」→「System Core」→「SYS」，将Debug模式设置为Serial Wire(SWD)，启用SWD调试接口；

4. 外设配置示例：以LED闪烁为例，选择目标GPIO引脚（如PC13），将引脚模式设置为GPIO_Output ，为引脚添加用户标签LED。

4.2 工程管理与工具链配置

1. 切换至「Project Manager」选项卡，完成以下核心配置：

   • Project Name ：设置工程名称，工程全路径严禁包含任何中文字符与特殊符号；

   • Project Location：选择工程存放路径，CubeMX将自动在该路径下创建以工程名命名的文件夹，用于存放工程文件；

   • Toolchain/IDE ：核心配置项，必须选择CMake；

   • Compiler ：可根据开发需求选择ARM GCC或Arm Compiler 6(armclang)；

2. 配置完成后，点击右上角「GENERATE CODE」，等待工程代码生成完成。

五、VSCode工程导入与自动配置

1. 回到VSCode，点击左侧「资源管理器」→「打开文件夹」，选择CubeMX生成的工程根目录（包含顶层CMakeLists.txt的文件夹），点击「确定」打开；

2. CMake插件将自动识别工程类型，弹出预设选择提示，开发调试阶段选择Debug预设，CMake将自动完成工程编译配置；

3. STM32Cube插件将自动识别STM32工程，弹出「是否将工程配置为STM32Cube工程」的提示，点击「Yes」；

4. 插件将自动完成工程级配置：

   • 自动安装工程所需的工具链Bundles；

   • 自动生成.vscode文件夹及内部配置文件，包括工程工具链版本、芯片信息、插件专属配置等；

   • 补全CubeMX生成工程缺失的调试与编译配置文件；

5. 配置完成后，可在STM32插件管理面板，查看当前工程专属的Bundles工具链信息。

5.1 插件冲突提示

VSCode官方C/C++扩展插件与STM32Cube插件自带的C语言语法解析功能存在冲突，若弹出"是否要为C语言安装推荐的来自Microsoft的"C/C++Extension Pack"扩展"，直接忽略即可，无需安装。

六、代码编写、编译与烧录调试

6.1 代码编写示例

工程代码结构与STM32CubeIDE完全一致，用户代码需放置在CubeMX规定的BEGIN/END注释块内，避免重新生成工程时被覆盖。

以LED闪烁为例，核心代码如下：

/* main.c */
#include "main.h"

/* 函数声明 */
void SystemClock_Config(void);
static void MX_GPIO_Init(void);

int main(void)
{
  /* HAL库初始化 */
  HAL_Init();
  /* 系统时钟配置 */
  SystemClock_Config();
  /* 外设初始化 */
  MX_GPIO_Init();

  /* 主循环 */
  while (1)
  {
    /* 翻转LED引脚电平 */
    HAL_GPIO_TogglePin(LED_GPIO_Port, LED_Pin);
    /* 延时500ms */
    HAL_Delay(500);
  }
}

/* 以下为CubeMX自动生成的系统时钟、GPIO初始化代码，此处省略 */

6.2 工程编译

手动编译操作

1. 点击VSCode底部状态栏CMake插件提供的「生成」按钮，或进入CMake配置界面点击「生成」，执行工程编译；

2. 编译完成后，将在输出面板显示编译结果，同时展示程序占用的Flash 与RAM空间；

3. 编译配置说明：

   • 开发调试阶段使用Debug预设，保留完整调试信息，关闭大部分代码优化；

   • 最终量产发布时，可将预设切换为Release，启用代码优化，减小固件体积；

   • 若手动修改了CMakeLists.txt文件，需点击「配置」按钮，让CMake重新加载工程配置，也可右键CMakeLists.txt文件执行配置/生成操作。

自动编译说明

烧录程序前，若检测到代码有修改，STM32Cube插件将自动执行CMake生成与编译流程，确保烧录的是最新版本的固件，无需手动执行编译操作。

6.3 固件烧录与在线调试

前置准备

1. 使用ST-Link下载器连接开发板SWD接口与电脑，确保硬件连接正常；

2. 若使用老旧固件的ST-Link，可能出现烧录失败，可通过STM32Cube插件的ST-Link固件升级功能完成升级，升级前后均需重新插拔ST-Link与电脑的连接，确保设备识别正常。

烧录与调试操作

1. 点击VSCode左侧「运行和调试」图标（快捷键Ctrl+Shift+D），进入调试面板；

2. 调试面板将自动识别已连接的ST-Link下载器，首次调试需选择对应的下载器作为调试工具；

3. 点击调试面板顶部的「开始调试」按钮，插件将自动完成固件编译、烧录，进入调试模式；

4. 程序烧录完成后，将自动在main函数入口处暂停，调试控制面板功能定义如下：

按钮序号	功能名称	核心作用
1	继续运行	继续执行程序，直到遇到下一个断点
2	单步跳过	单步执行代码，不进入被调用函数内部
3	单步步入	进入当前即将执行的函数内部，逐行调试
4	单步步出	执行完当前函数剩余全部代码，跳出函数后暂停
5	重启调试	重新从头开始执行调试流程
6	停止调试	结束调试会话，程序仍保留在芯片中，上电即可运行

1. 调试辅助功能：

   • 断点：点击代码行号左侧空白处，即可添加/取消断点，程序运行到断点处将自动暂停；

   • 变量监视：左侧调试面板可查看当前运行环境下所有局部变量、全局变量的值，也可将指定变量添加到监视区，实时监控数值变化；

   • 调用堆栈：查看程序当前的函数调用层级关系；

   • 外设寄存器：查看STM32所有外设寄存器的实时数值，支持在线修改。

七、关键注意事项

1. 工程全路径（包括上级文件夹名称、工程名称）严禁包含任何中文字符与特殊符号，否则将出现CMake解析失败、编译报错等异常；

2. CubeMX生成工程时，必须将工具链/IDE设置为CMake，否则VSCode插件无法正常识别与配置工程；

3. ST-Link固件升级前后，必须重新插拔设备，确保电脑重新识别ST-Link，避免升级失败或设备无法识别；

4. 请勿同时安装VSCode官方C/C++扩展插件，避免与STM32Cube插件的语法解析功能产生冲突，导致代码提示异常；

5. 用户编写的业务代码必须放置在CubeMX生成的USER CODE BEGIN与USER CODE END注释块之间，否则重新生成工程时，代码将被覆盖。

---

参考出处

• 来源：bilibili keysking STM32系列教程