从零搭建 STM32 VSCode 开发环境

【动手学 Claude Code】（11）基于 Claude Code 开发 STM32 程序

从零搭建 STM32 VSCode 开发环境

- [1. 为什么要基于 VSCode 构建 STM32 开发环境？](#1. 为什么要基于 VSCode 构建 STM32 开发环境？)
- - [1.1 什么是 STM32CubelDE for VSCode](#1.1 什么是 STM32CubelDE for VSCode)
  - [1.2 STM32CubelDE for VSCode 的核心功能特性](#1.2 STM32CubelDE for VSCode 的核心功能特性)
  - [1.3 本文的主要内容](#1.3 本文的主要内容)
- [2. 硬件环境与软件安装](#2. 硬件环境与软件安装)
- - [2.1 硬件与软件的准备](#2.1 硬件与软件的准备)
  - [2.2 硬件连接与测试](#2.2 硬件连接与测试)
  - [2.3 软件安装](#2.3 软件安装)
  - - [2.3.1 安装 Visual Studio Code](#2.3.1 安装 Visual Studio Code)
    - [2.3.2 安装 STM32CubeIDE for VS Code 扩展包](#2.3.2 安装 STM32CubeIDE for VS Code 扩展包)
  - [2.4 验证开发环境](#2.4 验证开发环境)
- [3. 创建第一个 STM32 工程](#3. 创建第一个 STM32 工程)
- - [3.1 在 STM32CubeMX 中新建工程](#3.1 在 STM32CubeMX 中新建工程)
  - [3.2 设置工程并生成代码](#3.2 设置工程并生成代码)
  - [3.3 在 VSCode 中打开工程](#3.3 在 VSCode 中打开工程)
- [4. 编写并运行 LED 闪烁程序](#4. 编写并运行 LED 闪烁程序)
- - [4.1 配置 MCU 外设](#4.1 配置 MCU 外设)
  - [4.2 编写 LED 闪烁代码](#4.2 编写 LED 闪烁代码)
  - [4.3 编译工程](#4.3 编译工程)
  - [4.4 烧录并运行程序](#4.4 烧录并运行程序)
- [5. 使用 VSCode 调试 STM32 程序](#5. 使用 VSCode 调试 STM32 程序)
- - [5.1 启动调试](#5.1 启动调试)
  - [5.2 设置断点](#5.2 设置断点)
  - [5.3 单步执行程序](#5.3 单步执行程序)
  - [5.4 查看变量](#5.4 查看变量)
  - [5.5 停止调试](#5.5 停止调试)
- [6. 总结](#6. 总结)

1. 为什么要基于 VSCode 构建 STM32 开发环境？

在 STM32 开发中，常见的开发环境主要包括 Keil MDK、STM32CubeIDE 和 VSCode。

使用 VSCode 开发 STM32 的优点在于：

统一的编程环境；
丰富的扩展生态；
现代化的工程管理；
便于使用 AI 编程工具。

1.1 什么是 STM32CubelDE for VSCode

STM32Cube软件生态系统提供两款强大的集成开发环境：STM32CubelDE和STM32CubelDE for Visual Studio Code。两款工具均属于STM32Cube生态系统，可提供跨平台兼容性、版本控制等增强功能以优化开发流程。

STM32CubeIDE for Visual Studio Code 将 VS Code的原生优势与STM32Cube生态的深度融合，打造出面向STM32 MCU的下一代免费IDE。

Visual Studio Code是微软推出的轻量级代码编辑器，其开放架构与核心特性非常契合嵌入式开发对"高效、灵活、可扩展"的需求。STM32CubeIDE for VS Code是基于VS Code扩展构建的"STM32专属开发环境"，其定位是STM32Cube生态的下一代免费IDE，在设计之初就深度融入STM32的开发体系。

融入 STM32Cube 生态，无缝衔接现有工具。
全维度工具链支持，覆盖开发全流程。
跨平台与全STM32 MCU覆盖。

1.2 STM32CubelDE for VSCode 的核心功能特性

STM32CubeIDE for VS Code 是围绕STM32开发场景设计的"全流程优化方案"，其架构设计、工程部署、编辑-构建-调试全链路及增值工具的特性如下。

STM32CubeIDE for VS Code 具有灵活更新的架构。
STM32CubeIDE for VS Code 引入了 STM32Cube bundles manager 对工具链进行管理，可以有选择的进行升级或者管理，具有更高的灵活性。也可以通过 CMSIS-PACKS 对 STM32 进行支持，在支持新STM32产品时只需更新对应的PACKS即可。

更高工程可再现性：从"个人开发"到"团队协作"的无缝衔接。
团队协作中，传统IDE常因路径配置、工具链版本差异导致"本地可编译，他人不可用"。STM32CubeIDE for VS Code通过工程的预配置把相关的工具链及版本进行了锁定和记录，再次打开工程时则按照配置列表自动更新工具链还原至相同的环境，很好的满足了工程可再现性高的要求。
编辑-构建-调试全链路优化：聚焦开发效率提升。
STM32CubeIDE for VS Code对嵌入式开发的"编辑-构建-调试"全流程进行了针对性优化，形成闭环高效工具链。

增值工具：Map文件分析器与RTOS调试，解决核心痛点。
针对STM32开发中的高频痛点，STM32CubeIDE for VS Code提供了两款核心增值工具：
- Map文件分析器：该工具通过图形化界面展示展示不同存储区的剩余可用空间及目标的存储位置等，同时可辅助分析Linker脚本问题，降低调试难度；
- RTOS调试：对于采用RTOS的项目，该工具支持线程的调用栈分析（full thread call stack）和内核对象（Kernel objects）的可视化分析。

1.3 本文的主要内容

本文将以 Windows 系统为例，从零开始完成软件安装和基础配置。随后，我们会创建一个简单的 LED 闪烁工程，依次完成以下操作：

在 STM32CubeMX2 中选择开发板或芯片；
配置 LED 对应的 GPIO 引脚；
生成 CMake 工程；
在 VSCode 中打开工程；
编写 LED 闪烁代码；
编译并烧录程序；
设置断点并进行单步调试。

本文的目标不是一次性讲清 STM32 开发工具链的全部细节，而是帮助初学者先完成一个可以正常运行的开发环境。只有先把第一个程序运行起来，后续学习 GPIO 输入、串口通信、定时器、PWM、ADC 和 FreeRTOS 等内容才会更加顺利。

2. 硬件环境与软件安装

本章以 NUCLEO-G431RB 开发板为例，介绍从硬件检查到 VSCode 插件安装的全过程。

2.1 硬件与软件的准备

硬件
- NUCLEO-G431RB（板载 STM32G431RBT6 芯片，集成 ST-LINK/V3E 调试器/编程器），或其它 NUCLEO 开发板，如： NUCLEO-U385RG、NUCLEO-H533RE、NUCLEO-H755ZI 等
- Type-C USB 连接线
软件工具
- Visual Studio Code：主编辑器，版本：最新稳定版（如 v1.111+），下载地址：code.visualstudio.com
- STM32CubeMX：硬件配置与工程生成，版本：≥6.12.0，下载地址：st.com/stm32cubemx
- STM32CubeProgrammer：固件烧录与连接检查，版本：≥2.20.0，下载地址：st.com/stm32cubeprog
- STM32CubeIDE for VS Code 扩展包：VSCode 插件，版本：≥3.8.0，下载地址：VSCode 扩展商店

注意：

不需要提前手动安装 CMake、arm-none-eabi-gcc 或 OpenOCD。STM32CubeIDE for VS Code 扩展会自动通过 Bundle Manager 下载管理这些依赖。
VSCode 的安装路径建议不要包含空格或中文字符（如 C:\Program Files\Microsoft VS Code 是允许的，但避免自定义含中文的路径）。

2.2 硬件连接与测试

在安装软件之前，建议先确认开发板硬件工作正常，这有助于后续排查问题。

连接开发板。

使用 USB 连接线将 STM32 Nucleo 开发板（板载 ST-LINK）连接到电脑。开发板通电后，电源指示灯应正常点亮。
检查驱动与连接状态。

打开设备管理器，查看"端口 (COM 和 LPT)"和"通用串行总线设备"，如图所示可以看到：

STMicroelectronics STLink Virtual COM Port (COMx)

使用 STM32CubeProgrammer 验证连接。
（1）打开 STM32CubeProgrammer；
（2）在右侧选择连接方式：ST-LINK → 点击 Connect；
（3）连接成功后，界面会显示芯片信息（如 Device ID、Flash 大小等）；
（4）如果提示升级 ST-Link 固件，请点击 Yes 进行升级。

检查 Option Bytes（可选）
在 STM32CubeProgrammer 中，点击左侧的 Option bytes 选项卡：
确认 RDP（Read Out Protection）状态为 Open（即未启用读保护）
如果使用 TrustZone 相关功能，请确认 TrustZone 处于关闭状态（对于 G431 默认不支持，可忽略）

2.3 软件安装

完成硬件连接和初步检查后，可以开始安装 STM32 开发所需的软件。

在完整的 STM32 开发环境中，需要安装 STM32CubeMX和 STM32CubeProgrammer，本文不再展开介绍。

STM32CubeMX：版本不低于 6.12.0，用于选择芯片、配置引脚、设置时钟和外设，并生成初始化代码；
STM32CubeProgrammer：版本不低于 2.20.0，用于程序烧录、芯片连接测试和固件更新等操作。

本文中安装过程主要包括以下步骤：

安装 Visual Studio Code；
安装 STM32CubeIDE for Visual Studio Code 扩展包；
等待扩展包自动完成初始化；
安装 ST-LINK USB 驱动（可选）；
检查开发工具包是否下载完成。

2.3.1 安装 Visual Studio Code

VSCode（Visual Studio Code）是免费开源的现代化轻量级代码编辑器，支持几乎所有主流的开发语言，内置命令行工具和 Git 版本控制系统，支持插件扩展，并针对网页开发和云端应用开发做了优化，是优秀的远程开发工具。

安装步骤：

打开 Visual Studio Code 官网，根据电脑系统选择对应的版本下载。
本文以 64 位 Windows 10 或 Windows 11 系统为例，建议下载 Windows 版本的安装程序。
双击下载后的安装文件，根据提示完成安装。
安装过程中，可以保留默认安装路径。在"选择其他任务"页面，建议勾选以下选项：
- 将 VSCode 添加到系统 PATH；
- 将"通过 Code 打开"操作添加到 Windows 文件资源管理器文件右键菜单；。
安装完成后，重启 VSCode。推荐关机后重新开机启动。
可选：安装中文界面。
单击 Extensions 图标，搜索 "Chinese"，找到 Microsoft 发布的中文语言包，单击 "Install"。
安装完成后，根据提示重新启动 VSCode，即可切换为中文界面。

2.3.2 安装 STM32CubeIDE for VS Code 扩展包

安装 VSCode 后，还需要安装 STMicroelectronics 官方提供的 STM32 开发扩展包。该扩展包可以为 VSCode 增加 STM32 工程管理、代码编辑、编译构建、程序烧录和在线调试等功能。

注意：不需要提前手动安装 CMake、arm-none-eabi-gcc 或 OpenOCD。STM32CubeIDE for VS Code 扩展会自动通过 Bundle Manager 下载管理这些依赖组件。

打开扩展商店。

打开 VS Code，点击左侧活动栏的"扩展（Extensions）"图标（或快捷键 "Ctrl+Shift+X"）。
新建 STM32 配置文件。

为了避免扩展配置与其他项目冲突，推荐为 STM32 开发创建一个独立的配置文件。也就是说，使用 VSCode 开发 STM32 项目可以选择该配置文件，使用 VSCode 开发其它项目如 Python 项目则选择相应的其它配置文件。

（1）点击菜单 "文件 → 首选项 → 配置文件 → 新建配置文件"，创建新的配置文件 "STM32"。

（2）点击菜单 "文件 → 首选项 → 配置文件 → STM32"，切换到新的配置文件 STM32。
搜索并安装插件。

在搜索框中输入 "STM32"，在搜索结果中找到 "STM32CubeIDE for Visual Studio Code" 插件，确认发布者为：STMicroelectronics，然后单击 "Install" 按钮。

等待自动安装完成。

该扩展包会自动安装所需的依赖组件，如：CMake、Cortex-Debug、clangd 等。

安装过程中，右下角会弹出进度提示。等待，等待...

安装完成后，在 VSCode 左侧活动栏中将会出现 STM32Cube 图标（蝴蝶形状）。
打开 STM32 开发界面。

单击左侧活动栏中的 STM32Cube 图标，打开 STM32 开发界面。

该界面中包括若干常用功能区域：
- STM32Cube Projects 创建、导入和管理 STM32 工程；
- STM32Cube Devices and Boards 查看电脑当前识别到的开发板或调试器；
- STM32Cube Resources 查看文档、教程、驱动程序和常见问题；
- Bundle Manager 下载和管理编译、构建、烧录及调试所需的工具包。
工具包初始化。

首次打开 STM32CubeIDE for VS Code 时，扩展包需要下载基础开发工具。这个过程通常需要保持网络连接。

扩展包采用 Bundle Manager 管理开发工具，包括编译器、构建工具、调试工具和其他命令行组件。

如果 Bundle Manager 显示某些工具尚未安装，可以根据界面提示完成下载。

下载完成后，可以在 Bundle Manager 中查看工具包状态。如果相关组件显示为已安装，即说明基础工具已经准备完成。

安装 ST-LINK USB 驱动.
如果使用带有板载 ST-LINK 的开发板，或者使用外置 ST-LINK 下载器，还需要安装 ST-LINK USB 驱动。
（1）单击左侧活动栏中的 STM32Cube 图标，打开 STM32 开发界面，找到 "STM32Cube Resources"；
（2）在该区域中选择："Install ST-Link USB Drivers"，然后根据提示运行驱动安装程序。

驱动安装完成后：

（1）关闭并重新启动 VSCode；

（2）从电脑上拔下开发板的 USB 数据线，等待几秒后重新连接；

（4）再次打开 STM32CubeIDE for VS Code 界面；

（5）检查是否能够识别 ST-LINK 或开发板。

2.4 验证开发环境

检查 STM32 扩展包。

打开 VSCode，查看左侧活动栏。

左侧活动栏中应出现 STM32CubeIDE for Visual Studio Code 图标（蝴蝶）。单击图标后，可以打开 STM32 开发界面，包括 STM32CUBE KEY ACTIONS、STM32CUBE RESOURCES 和 STM32CUBE BUNDLES MANAGER 三个区域。
检查工具包管理器。

检查编译和调试所需的工具包是否安装完成。

点击："STM32CUBE BUNDLES MANAGER" 可以正常显示 Bundle Manager 界面。由于尚未创建或打开 STM32 工程，Bundle Manager 界面中通常只显示："System"。
验证 ST-LINK 驱动。

（1）关闭并重新启动 VSCode；

（2）重新连接开发板的 USB 数据线到电脑。

（2）在 VSCode 中点击左侧活动栏的 "运行和调试" 图标，在左侧窗口中会显示连接的 STM32 设备和开发板。

如图所示，点击列表中的 STLINK-V3 调试器，将显示 Product ID 和 Serial ID（设备串号），说明 VSCode 已正确识别开发板。

3. 创建第一个 STM32 工程

完成开发环境安装后，可以创建第一个 STM32 工程。

STM32CubeIDE for Visual Studio Code 支持多种工程创建方式。例如，可以在 VSCode 中直接创建空白工程，也可以导入 STM32CubeMX 生成的工程。

对于初学者来说，建议使用 STM32CubeMX 创建工程。STM32CubeMX 提供图形化界面，可以帮助我们选择开发板或芯片，并自动生成基础代码。后续需要配置 GPIO、串口和定时器等外设时，也可以继续使用同一个工具。

本章先创建一个简单的测试工程。暂时不修改代码，也不烧录程序。下一章将在这个工程中编写 LED 闪烁程序。

3.1 在 STM32CubeMX 中新建工程

本节先在 STM32CubeMX 中创建一个新的 STM32 工程。读者只需要完成测试目录创建、软件启动和芯片选择，为后续生成工程代码做好准备。

创建测试目录。

在正式创建工程之前，建议先建立一个专门存放 STM32 项目的目录。例如，"C:\STMicroelectronics\STworkspace_G431"。

创建一个名为 led_blink 的测试工程，例如："C:\STMicroelectronics\STworkspace_G431\MyLed01"。
启动 STM32CubeMX。

选择 New Project（或Ctrl-N快捷键）新建工程，进入 New Project 芯片或开发板选择界面。
选择开发板或芯片。

STM32CubeMX 通常提供两种选择方式创建工程：
- Board Selector：按照开发板型号创建工程；
  使用 NUCLEO 官方开发板时建议，按照 Board Selector 选择，例如选择开发板型号为 NUCLEO-G431RB。
- MCU/MPU Selector：按照 STM32 芯片型号创建工程。
  使用最小系统板、自制开发板或其他第三方开发板时，建议选择 MCU/MPU Selector，并输入开发板上实际使用的芯片型号。

在选择 MCU 和开发板后直接点击 "Start Project" 建立项目。弹出项目选项窗口，确认后自动进入工程配置界面。

3.2 设置工程并生成代码

本节将完成工程名称、保存路径和构建方式的设置，并使用 STM32CubeMX 生成 CMake 工程。生成完成后，工程即可在 VSCode 中打开。

打开工程设置。

进入 STM32CubeMX 工程配置界面后，暂时不需要修改芯片引脚。

单击上方的："Project Manager"，进入工程设置页面，可以看到工程名称、保存路径和工具链等设置项。
设置工程名称和保存路径。

在 Project Name 中输入工程名称："MyLed01"，将自动生成的完整工程路径："C:\STMicroelectronics\STworkspace_G431\MyLed01"。
选择 CMake 工程。

在 Toolchain / IDE 中选择工程构建工具："CMake"。不要选择 Keil、IAR 或 STM32CubeIDE。

STM32CubeMX 会自动生成基础配置文件。
生成工程代码。

完成设置后，单击右上角的："GENERATE CODE"，STM32CubeMX 会根据当前芯片型号生成基础工程。

第一次为某个 STM32 系列创建工程时，STM32CubeMX 可能提示下载对应的软件包。按照提示完成下载即可。

其它外设的配置，详见后文。

代码生成完成后，打开工程目录可以看到 .ioc 文件、CMakeLists.txt 文件以及 Core、Drivers 等文件夹，说明工程已经生成成功。

3.3 在 VSCode 中打开工程

本节在 VSCode 中采用"打开工程---选择 Debug---执行 CMake: Configure---检查 build\Debug 文件夹"的流程，打开并初始化刚刚生成的工程。

打开工程文件夹。

启动 VSCode。

在顶部菜单中选择："File > Open Folder..."，选择刚才生成的工程目录："...\MyLed01"，然后单击"选择文件夹"。

打开工程后，在 VSCode 左侧资源管理器中，可以看到 CMakeLists.txt、Core 和 Drivers 等文件或文件夹。
选择 CMake 配置预设。

第一次打开 CMake 工程时，VSCode 可能会提示选择配置预设，开发过程选择 "Debug" 即可。CMake 将按照该预设进行配置，STM32 插件（STM32CubeCMake Support）也识别该工程是 STM32Cube Project。

Debug 表示调试版本，适合学习和测试；Release 更适合正式发布程序。

执行 CMake 配置。
（1）按下 Ctrl + Shift + P 打开命令面板，输入并执行："CMake: Configure"。CMake 会读取工程配置，并生成 VSCode 编译器所需的编译、索引、头文件、宏、工具链环境，让代码能正常编译。
（2）STM32 插件（STM32CubeCMake Support）也识别该工程是 STM32Cube Project，确认后将自动安装所需的工具链。
（3）STM32 插件调用工具链，生成了一些 CubeMX 创建工程时缺失的文件，如 .vscode 中记录的插件配置文件, .settings 中记录的使用工具链的文件。
（4）打开工程目录。如果看到："build\Debug"，就说明 CMake 配置已经完成。在STM32 工具包管理器 Bundle Manager 界面中也可以看到当前工程的捆绑包 MyLed01。

打开 main.c

在 VSCode 中点击左侧资源管理器图标，依次展开："Core > Src"，双击打开："main.c"。

完成以上操作后，工程已经准备就绪。
注意：VSCode 自动识别 C语言程序，推荐安装官方【C/C++ Extension Park 扩展】，在开发 STM32 项目时不要安装以免冲突。

4. 编写并运行 LED 闪烁程序

本章将在已经创建的工程中编写一个 LED 闪烁程序。程序运行后，开发板上的 LED 将每隔 500 毫秒切换一次状态。

这个实验可以完整验证 STM32 开发的基本流程：配置 GPIO 引脚、生成代码、修改程序、编译工程、烧录程序和观察运行结果。

4.1 配置 MCU 外设

本节先在 STM32CubeMX 中将 LED 对应的引脚设置为输出模式，为后续控制 LED 做好准备。在实际操作中，外设配置可以在 3.2 节建立工程之后进行。

打开 STM32CubeMX 工程。

打开 STM32CubeMX，然后选择："File > Open Project"，打开生成的工程配置文件："MyLed01.ioc""

（1）选择 "System Core -- SYS" 设置调试器类型，将 Debug 模式设为 "Serial Wire"，启用SWD接口用于后续的下载和调试。

（3）选择 "System Core -- RCC" 配置时钟模式，设置高速晶振为外部时钟，将 High Speed Clock (HSE) 设为 "Crystal/Ceramic Resonator"，为系统提供时钟源。

（4）选择 "Connectivity" 配置串口通信，设置 "LPUSAT1"，启用异步模式，用于程序调试信息输出。
将 LED 引脚设置为输出模式。

确认开发板上 LED 所对应的引脚。以 NUCLEO-G431RB 开发板为例，板载 LD2 连接到 PA5。

（1）在芯片引脚图中单击 PA5，然后选择："GPIO_Output"，将引脚设置为将其设置为 GPIO_Output。

（2）在左侧配置栏中，依次打开："System Core > GPIO"，选中 PA5，在 User Label 一栏中输入：LD2。

设置标签后，STM32CubeMX 会在代码中自动生成与 LED 引脚对应的名称，例如："LED_GPIO_Port"、"LED_Pin"。后续代码不需要直接写死 GPIOA 和 GPIO_PIN_5。更换开发板或修改引脚时，只需要重新配置 STM32CubeMX 即可。
将用户按键（PC13）配置为外部中断

确认开发板上用户按键对应的引脚。以 NUCLEO-G431RB 开发板为例，板载 BTN 连接到 PC13。

（1）在芯片引脚图中找到 PC13，将其配置为 "GPIO_EXTI13"。

（2）在左侧配置栏中，依次打开："System Core > GPIO"，选中 PC13，在 User Label 一栏中输入：LD2。

重新生成代码
完成引脚配置后，单击右上角的："GENERATE CODE"，STM32CubeMX 会更新工程文件。

提醒：后续重新生成代码时，应尽量将自行编写的程序放在 USER CODE BEGIN 和 USER CODE END 标记之间。否则，部分代码可能被自动生成内容覆盖。

4.2 编写 LED 闪烁代码

本节将使用 VSCode，在 main.c 的主循环中加入两行代码，让 LED 按照固定时间间隔切换状态。

打开 main.c

在 VSCode 中点击左侧资源管理器图标，依次展开："Core > Src"，双击打开："main.c"。
在 main.c 中，找到主循环 "while (1)" 中的用户代码区域。

while (1) 是一个无限循环。STM32 上电运行后，会不断重复执行其中的代码。

c 复制代码

/* Infinite loop */
/* USER CODE END WHILE */
while (1)
{
    /* USER CODE BEGIN 3 */
    /* USER CODE END 3 */
}
/* USER CODE END WHILE */

添加 LED 闪烁代码。
在 USER CODE BEGIN 3 和 USER CODE END 3 之间加入以下代码：

c 复制代码

  /* Infinite loop */
  /* USER CODE BEGIN WHILE */
  while (1)
  {
    /* USER CODE BEGIN 3 */
    HAL_GPIO_TogglePin(LD2_GPIO_Port, LD2_Pin);
    /* Insert delay 500 ms */
    HAL_Delay(500);
    /* USER CODE END 3 */
  }
  /* USER CODE END WHILE */
}

其中：

HAL_GPIO_TogglePin() 用于切换 GPIO 引脚的输出状态；
LED_GPIO_Port 和 LED_Pin 对应前面配置的 LED 引脚；
HAL_Delay(500) 表示延时 500 毫秒。

程序每执行一次循环，LED 状态就会切换一次。LED 点亮 500 毫秒，再熄灭 500 毫秒，闪烁周期约为 1 秒。

检查 LED 引脚定义（可选）。
LED_GPIO_Port 或 LED_Pin 是根据 STM32CubeMX 中 User Label 的设置，自动在 main.h 中定义的。
打开：Core > Inc > main.h，可以检查是否存在类似内容：

c 复制代码

#define LD2_Pin GPIO_PIN_5
#define LD2_GPIO_Port GPIOA

实际端口和引脚编号取决于在 STM32CubeMX 中配置 MCU 外设时对 User Label 的设置。

如果没有找到这些定义，应返回 STM32CubeMX，确认 GPIO 引脚的 User Label 设置，然后重新生成代码。

4.3 编译工程

本节将在 VSCode 中重新配置并编译工程，生成可以烧录到 STM32 中的程序文件。

执行 CMake 配置

如果修改 STM32CubeMX 配置并重新生成代码，建议再次执行 CMake 配置，生成编译所需的环境配置文件。
编译工程

VSCode 调用编译器，对工程中的 C 语言代码进行编译和链接。

（1）点击 VSCode 底部工具栏的 "生成" 按钮（或 "CMake-项目状态-生成"），将执行完整编译链接流程：完成源码编译、目标文件链接、固件格式转换，产出可烧录的程序文件。

（2）编译完成后，输出窗口中应显示构建成功的信息，例如：" $build$ 生成已完成"，无错误、警告或仅列出无害警告。

编译出错时，输出窗口提示 "Build failed"，并显示具体报错信息。

（3）编译完成后，工程目录中会生成原始固件文件："build\Debug\MyLed01.elf"，CMake 的 BUILD ANALYZER 也会显示程序所占达到 RAM 与 Flash 信息。

4.4 烧录并运行程序

在 VSCode 中将编译生成的程序烧录到开发板，并启动调试。

连接开发板

使用 USB 数据线将 STM32 开发板（板载 ST-LINK）连接到电脑。

开发板上的电源指示灯应正常点亮。Windows 设备管理器中应能够识别 ST-LINK。
检查 ST-LINK 下载器

（1）在 VSCode 中左侧活动栏中点击 "运行与调试"，VSCode 左侧出现"运行与调试"面板。

（2）查看 "STM32Cube Device and Boards"，可以看到识别到的下载器 STM32 STLink。

注意：如果启动调试时提示 ST-LINK 固件版本过旧，可以在："STM32CUBE DEVICES AND BOARDS" 中选择对应的 ST-LINK 设备，然后按照提示升级固件【Upgrade ST-LINK Firmware】。
启动烧录和调试

（1）在"运行与调试"面板中，单击："运行与调试" 按钮，

（2）如果 VSCode 提示选择调试器，选择："STM32Cube: STM32 Launch ST-Link GDB Server"。

（3）推荐点击 "创建一个 launch.json 文件（create a launch.json file）"，将自动创建配置文件，不需要修改或保存。

br>

VSCode 会自动完成以下操作：

检查工程是否已经成功编译；
将程序烧录到 STM32 开发板；
启动 ST-LINK 调试连接；
进入调试状态。

进入调试状态后，VSCode 顶部出现调试工具栏，编辑器中显示当前暂停的位置。通常程序会暂停在 main() 函数附近。

运行程序

（1）进入调试状态后，STM32 系统心跳指示的红色 LED 闪烁，表示处于调试连接状态。

（2）程序暂时停在 main() 函数处，因此绿色 LED2 不会立即闪烁。

（3）单击顶部调试工具栏中的"继续"按钮，或按下：F5，开发板上的绿色 LED2 按照固定时间间隔闪烁。
停止调试

完成测试后，可以单击顶部调试工具栏中的"停止"按钮，或使用快捷键："Shift + F5"。

顶部调试工具栏消失，VSCode 退出调试状态。
完成测试

如果 LED2 能够周期性闪烁，说明以下环节已经正常工作：

STM32CubeMX 可以生成工程代码；
VSCode 可以编译 CMake 工程；
ST-LINK 可以连接开发板；
VSCode 可以将程序烧录到 STM32；
STM32 芯片可以正常运行程序；
VSCode 可以进入调试状态。

至此，STM32 VSCode 开发环境已经完成基础验证。

5. 使用 VSCode 调试 STM32 程序

上一章已经通过"运行与调试"功能完成程序烧录，并让 LED 正常闪烁。本章继续使用同一个工程，学习断点、单步执行和变量查看等基础调试功能。

调试的作用是让程序暂时停在指定位置，逐行观察代码如何执行。对于初学者来说，先掌握几项常用操作即可。

5.1 启动调试

打开"运行与调试"界面

在 VSCode 左侧活动栏中，单击 "运行与调试" 图标或使用快捷键 "Ctrl + Shift + D" 打开"运行与调试"界面。
启动调试

确认开发板已经连接电脑，然后单击："运行与调试" 按钮；

如果需要选择调试器，选择："STM32Cube: STM32 Launch ST-Link GDB Server"，VSCode 会将程序烧录到开发板，并进入调试状态。

5.2 设置断点

断点可以理解为程序中的"暂停标记"。程序执行到断点所在行时，会暂时停止，便于观察当前状态。

找到 LED 翻转代码
打开："Core > Src > main.c" 文件，找到以下代码：

c 复制代码

HAL_GPIO_TogglePin(LED_GPIO_Port, LED_Pin);
HAL_Delay(500);

设置断点
在下面这一行左侧的空白区域单击：

c 复制代码

HAL_GPIO_TogglePin(LED_GPIO_Port, LED_Pin);

单击后，左侧会出现一个红色圆点，说明断点已经设置成功。

继续运行程序
按下：F5，程序会继续运行，并在执行到断点所在行时暂停。
编辑器中断点所在行出现高亮显示，说明程序已经停在该位置。

5.3 单步执行程序

程序暂停后，可以使用调试工具栏中的按钮，也可以使用快捷键。

操作	快捷键	作用
继续运行	`F5`	继续执行，直到遇到下一个断点
单步跳过	`F10`	执行当前行，然后停在下一行
单步进入	`F11`	进入当前函数内部
停止调试	`Shift + F5`	退出调试状态

对于第一次调试，主要使用 F5 和 F10 即可。

单步运行
程序在断点处暂停后，VSCode 会用黄色背景或箭头标出当前代码行。需要注意的是，黄色高亮行表示下一条即将执行的语句。该语句此时尚未执行。
按下：F10，程序会执行当前行的 HAL_GPIO_TogglePin() 函数，将 LED 引脚的输出状态切换一次，然后停在下一行语句处：

c 复制代码

HAL_Delay(500);

恢复连续运行

按下：F5，程序会继续运行。由于断点仍然存在，程序每次执行到 LED 翻转代码时都会暂停。
取消断点

再次单击左侧红色圆点，取消断点。

5.4 查看变量

当前 LED 闪烁程序没有需要观察的普通变量。为了演示，可以增加一个计数变量，用于记录循环执行次数。

添加计数变量

在 main() 函数中，修改的关键代码如下：

c 复制代码

/* USER CODE BEGIN 1 */
uint32_t count = 0;
/* USER CODE END 1 */

while (1)
{
    /* USER CODE END WHILE */

    /* USER CODE BEGIN 3 */
    HAL_GPIO_TogglePin(LED_GPIO_Port, LED_Pin);
    count++;
    HAL_Delay(500);
    /* USER CODE END 3 */
}

重新编译并启动调试

（1）保存代码后，点击 VSCode 底部工具栏的 "生成" 按钮，执行编译链接流程。

（2）编译成功后，再次启动 "运行与调试"。

（3）设置断点。

在："count++;" 这一行设置断点，然后按下 F5 启动调试。程序运行到断点 count++ 所在行暂停，该行代码被高亮。
打开监视窗口

在 VSCode 左侧 "运行与调试" 面板，找到监视（WATCH）区域。监视区域默认是空的，需手动添加。

变量（VARIABLES）区域显示的是当前函数的所有局部变量和参数，无需手动添加，其刷新频率和 Watch 相同。
添加变量到 Watch

（1）将鼠标悬停在监视区域，点击右侧出现的 "+" 按钮；

（2）在弹出的输入框中，输入你想要监视的变量名（如："count" ），按回车确认；

（3）添加成功后，变量及其当前值会立即显示在列表中。

查看变量数值
继续运行：按下 F5，程序会运行到下一个断点或结束，再次暂停时 Watch 中的值会自动更新。
每执行一步，Watch 中的值都会刷新。

说明：普通 Watch 在程序暂停（Break）时显示静态值，需要中断程序执行，适用于静态断点调试、分析某一时刻状态。STM32CubeIDE for VSCode 也提供了 LiveWatch 功能，允许开发者在程序运行时实时刷新、动态查看变量数值。

5.5 停止调试

完成调试后，单击顶部调试工具栏中的"停止"按钮，或者按下："Shift + F5" 停止调试。顶部调试工具栏消失，VSCode 返回普通编辑状态。

如果希望开发板继续运行程序，可以按下开发板上的 RESET 按钮。程序会从头开始执行，LED 恢复周期性闪烁。

本章介绍了 VSCode 调试 STM32 程序的基本方法，这些功能已经能够满足多数基础实验的调试需求。后续遇到程序运行异常时，可以先在关键代码处设置断点，再通过单步执行和变量查看逐步定位问题。

6. 总结

本文从零开始搭建了基于 VSCode 的 STM32 开发环境，并通过一个简单的 LED 闪烁程序完成了完整测试。

在环境准备阶段，我们安装了 Visual Studio Code 和 STM32CubeIDE for Visual Studio Code 扩展包，连接 STM32 开发板，并检查了扩展包、Bundle Manager 和 ST-LINK 驱动是否正常。
随后，我们使用 STM32CubeMX 创建 CMake 工程，在 VSCode 中打开工程并完成初始化。在 LED 闪烁实验中，我们依次完成了 GPIO 配置、代码编写、工程编译、程序烧录和运行测试。
最后，我们进一步使用 VSCode 的调试功能设置断点，单步执行程序，并观察 LED 状态和变量数值的变化。

至此，一个基本可用的 STM32 VSCode 开发环境已经搭建完成。

版权声明：

转发必须注明原文链接：

从零搭建 STM32 VSCode 开发环境 (https://youcans.blog.csdn.net/article/details/161358391)

Copyright by youcans@qq.com 2026

Crated：2026-06