STM32 一键烧录 · 调试分离

ST-Link / J-Link 烧录，F5 独立调试。 用于桌面版 VS Code 的社区扩展，与 STMicroelectronics、SEGGER、Microsoft 无隶属关系。

日常操作

运行按钮 ▷ 是 VS Code 自带的分体按钮：从下拉菜单选过哪一项，主按钮就会变成哪一项。选过“启动调试”后，再从下拉菜单选一次“编译并烧录”即可恢复。

烧录入口执行：保存文件 → CMake 编译 → 下载并校验 → 复位运行。烧录不会启动调试会话；F5 仍由 Cortex-Debug 或已有 STM32 调试扩展提供。

首次使用

1. 安装本扩展。如果装过旧的 local.stm32-flash-button 或 llinkam.stm32-flash-button，请先卸载，避免同名命令冲突。
2. 用 VS Code 打开 STM32 工程文件夹，点击左侧 STM32 图标。
3. 展开 环境体检，点击 检查工具链。点击标红的项目可以直接处理：C/C++ 与 clangd 冲突、失效插件、旧版烧录插件、缺失的工具。
4. 连接下载器，在 下载器 视图点击 扫描下载器，点击列表中的设备即可切换。首次烧录时如果只有一个下载器，会自动选中并记住。
5. 点 ▷ 烧录；需要调试时从 ▷ 的下拉菜单选择 启动调试，会自动生成本工程的 F5 配置。

如果右上角没有按钮，先打开工程里的一个源文件。刚安装或升级后可以运行“Developer: Reload Window”。

面板与设置

工程与配置记忆

面板查找工作区中的 CMakePresets.json 和 .ioc 文件。每个子工程分别记住下载器类型、序列号和选定的固件，保存到 .vscode/settings.json 的 stm32flash.projectProfiles。打开某个子工程里的源文件时会自动切换到对应工程。

下载器类型、J-Link 芯片型号、SWD 频率、连接模式、构建预设、构建目录、BIN 下载地址等，在 VS Code 设置中搜索 stm32flash 修改。

ST-Link / J-Link

• ST-Link：使用 STM32CubeProgrammer CLI。可设置 UR / NORMAL / HOTPLUG 连接模式、SWD 频率和序列号。
• J-Link：使用 SEGGER J-Link Commander，接口为 SWD。填写精确的 SEGGER 芯片名称，例如 STM32F103C8 或 STM32F407VE。.ioc 能提供部分系列的建议名称，使用前请核对。
• 扫描 USB 只枚举下载器，不下载固件。J-Link 枚举使用 ShowEmuList USB。
• 未设置序列号时，首次烧录会枚举当前类型下载器；仅一个时选中并记忆，多个时由用户选择。已有序列号时不会自动替换成另一块设备。
• 面板显示的型号来自 .ioc。下载器视图标题栏另有“读取芯片信息”按钮，用 HOTPLUG 连接读取工具报告的型号/ID，不写 Flash。它可能只能识别芯片系列，不能替代核对实物的精确封装型号。
• J-Link 不宣称自动识别所有目标芯片；精确设备名由工程信息和用户设置确定。SEGGER 工具报不支持时需修改设备名或更新 SEGGER 软件。
• Java 也提供 jlink.exe；自动查找会检查路径及 SEGGER DLL，避免调用错程序。

固件与分区

• 支持 ELF / AXF / HEX / BIN。AXF 经 ELF 格式检查后，J-Link 使用临时 .elf 副本。
• 固件路径为空时，在指定构建目录内查找 ELF / AXF；多个时让用户选择，不按时间猜测。手动选定的固件会记入当前工程配置。
• 相对固件路径基于当前子工程目录，支持绝对路径和 ${workspaceFolder}。
• ELF / HEX 使用文件中的地址；BIN 必须填写正确下载地址，默认 0x08000000。
• 带 Bootloader 的 APP 优先使用 ELF/HEX。烧录后的复位会走 MCU 的正常启动流程，偏移 APP 需要已有 Bootloader 正确跳转。
• 没有整片擦除、读保护解除或选项字节修改命令。

快捷键

设置 stm32flash.flashShortcut 可选 Ctrl+Alt+U、Ctrl+Alt+F、F6、关闭预设。需要其他组合，在 VS Code 快捷键编辑器中搜索 stm32flash.flash 自行绑定。F5 未被本插件绑定。

F5 调试

ST-Link 配置使用 Cortex-Debug + OpenOCD，J-Link 配置使用 Cortex-Debug + J-Link GDB Server。自动生成的配置会先构建，再返回 ELF 路径，并停在 main。

每个工程各有一个本插件管理的配置，从下拉菜单 启动调试 时自动生成或更新。用户原有配置会保留。修改下载器类型、频率或序列号后，请用 启动调试 而不是直接按 F5，以便配置同步更新。

调试期间需要烧录，请先 Shift+F5 结束调试。编译或烧录进行中会阻止标准 STM32 调试入口启动。不同 VS Code 窗口和外部应用间没有跨进程互斥，请避免同时占用同一下载器。

外部工具要求

扩展不捆绑上述软件。换电脑后重新检查工具链、定位路径即可。工具链检查验证的是工具可用路径；不代表硬件接线、驱动或实板烧录已经验证。

支持在 PATH、CubeProgrammer 常见安装目录及 SEGGER 标准安装目录中定位工具。自定义安装目录可从面板选择。ARM GCC/Ninja 需要在 PATH 中可用。Windows 是主要验证环境；其他平台需自行配置工具路径并验证。

编译设置

默认配置预设、构建预设均为 Debug，固件搜索目录为 build/Debug。修改预设时同步检查构建目录。

若已有配置好的 CMake 构建目录，可清空两个预设，此时使用 cmake --build <构建目录>。Keil 等其他构建系统可以先在原工具编译，再用本插件的“仅烧录”下载已有固件。

HAL 模块检查

编译失败时，如果报错是 undefined reference to 'HAL_CAN_Start'、implicit declaration of function 'HAL_...' 或 unknown type name 'CAN_HandleTypeDef' 这类，插件会对照 Core/Inc/*_hal_conf.h 和 CMake 源文件列表，判断是哪个 HAL 模块没有启用或没有加入编译，并在 环境体检 中列出。点击问题可用 CubeMX 打开工程，在对应外设中启用后重新生成代码。

日志、失败与取消

输出面板 STM32 烧录 记录实际命令、固件路径及工具输出。编译失败时不下载，下载失败时不报告成功。重复点击不会重复启动同一窗口中的操作。

编译单条命令超时 5 分钟，烧录 2 分钟，设备扫描 20 秒。面板及进度通知支持取消；取消会终止相应进程树。中途停止烧录后可能需要重新完整下载。

ST-Link 使用 -d ... -v -rst -run -q；J-Link 使用无对话框的批处理，启用 ExitOnError，LoadFile 默认执行下载和校验，然后复位运行。J-Link 还检查下载完成信息，未识别成功信息时不会误报。

数据处理与验证范围

扩展无遥测和后台联网请求，不上传源代码或固件。仅在用户点击官方安装链接时打开浏览器。面板采用本地资源及内容安全策略。固件交给本地下载工具处理。

软件测试覆盖两种下载器的分支、地址、错误、取消、多个设备和配置隔离；在真实 VS Code 验证了侧栏加载、工程编译、ST-Link 枚举、工具路径检查和配置恢复。实板烧录、J-Link 硬件及断点/变量仍需连接指定目标板验证。

开发

npm ci
npm test
npm run package

参考：SEGGER Commander、VS Code 快捷键、Cortex-Debug 配置。