STM32 工程助手 · VS Code 扩展
简体中文 · English
STM32 Project Helper 为本地 Windows 工程提供 STM32 工具链检测、VS Code 编译与 DAPLink 烧录任务配置、源文件管理、STM32CubeMX MDK-ARM/CMake 双向转换和修改恢复。扩展直接使用当前工作区,无需启动桌面程序,不上传工程。
v1.4.1:调试时自动下载
更新了debug时自动下载
下载 v1.4.1 VSIX,覆盖安装后重载 VS Code。对应桌面版为 v1.7.1。
“开发配置 → 调试模式”默认使用 编译、下载并调试:先执行当前配置的编译任务,成功后通过 Cortex-Debug launch 下载所选 ELF,再进入调试。需要观察已运行固件时,选择 仅附加(不下载固件),使用 attach 且不执行编译任务。
已有工程请重新“写入调试配置”,核对 launch.json、专用调试编译任务及 .vscode/stm32-debug.cmake 的差异,再确认写入。启动确认会显示实际固件路径及是否下载;编译失败请修复错误,不要选择“仍然调试”。用户自建调试配置和同名任务保留。若助手配置包含 overrideLaunchCommands,需先移除或明确选择仅附加,避免自定义命令跳过下载。
v1.4.0:FreeRTOS 移植层补全与遥测授权
发布日期:2026-10-25。下载 v1.4.0 VSIX,覆盖安装后重载窗口。完整版本说明。对应桌面版为 v1.7.0。
FreeRTOS 移植层补全
“工程转换”检查 MDK 工程后,选择具体 MDK 文件和构建目标,可使用“下载并预览 FreeRTOS 补全…”或“本地移植层导入…”。官方模式只查找当前内核对应版本,固定官方提交并校验内容、版本及 GNU 语法;离线模式选择包含同版本 port.c、portmacro.h 的目录。
预览只读,原生确认后才添加缺失文件并记录可恢复历史,不升级内核、不覆盖已有不同内容的文件。预览中的 MDK、内核或移植层内容发生变化时会拒绝写入,需重新预览。补全后保留选中目标并重新检查,其他编译覆盖、专用库等问题仍需处理;错误信息同时展示解决步骤。自动补全仅覆盖可确认的非 MPU ARM_CM0/ARM_CM3/ARM_CM4F,具体核心和 FPU 必须匹配;未知版本或其他移植层需人工核对。
桌面端同样提供这两个入口。补全预览可取消,进入批量保存后等待完成;保存后针对原目标重新计算转换诊断,保留组级选项、专用库等其他阻断。后端只向界面发送文件摘要,完整补全计划及文件内容留在扩展端用于差异和确认写入。
本版同时包含下述 v1.3.1/v1.3.2 的遥测改动:默认关闭,首次启动明确授权,接收方固定为开发者项目,用户不需要创建项目或填写令牌;遵守 VS Code 全局遥测设置。桌面 EXE 不包含统计。
本次完成针对性软件检查和临时工程补全流程,未进行新增补全功能的真机调度测试。既有转换范围仍限定受支持的 STM32CubeMX 工程,不自动执行 CubeMX。
v1.3.2:首次启动授权
在受信任的本地 Windows x64 VS Code 中,插件首次激活时弹出中英文遥测授权提示,可选择“同意并启用”或“暂不开启”。关闭弹窗也保持关闭;选择在本机跨工程记忆,后续启动不重复提示。仍可在“设备与诊断”中修改。VS Code 全局遥测关闭或开发者项目未配置时,不弹窗也不发送;接收项目变化后需重新授权。
此本地版本未单独公开发布,改动已包含在 v1.4.0;本地旧安装包保留。
v1.3.1:匿名统计接收项目修正
- 匿名事件发送至开发者固定配置的 PostHog 项目,用户无需创建项目或填写令牌。
- 默认关闭,原生弹窗授权后启用;旧授权不继承,接收项目变更需重新授权,遵守 VS Code 遥测开关。
- 更新中英文统计界面与说明,不发送工程路径、源码、日志或串口数据;桌面 EXE 不包含统计。
此本地版本未单独公开发布,改动已包含在 v1.4.0。
插件 v1.3.0 / 桌面 v1.6.0 功能
以下十项已包含在本地插件 v1.3.0 中,安装包为 artifacts/vsix/stm32-project-helper-1.3.0-win32-x64.vsix。桌面 v1.6.0 在“开发与分析”入口提供其余九项,桌面端不包含 PostHog;桌面生成的 Cortex-Debug 配置在 VS Code 中使用。桌面发布目录为 artifacts/publish/v1.6.0/portable(自带运行时)和 artifacts/publish/v1.6.0/lite(依赖 .NET 9 Desktop Runtime)。旧安装包保留,本节为此前发布功能的历史说明。插件覆盖安装新版 VSIX 后重载窗口即可。
| 功能 |
入口与使用方法 |
| clangd 自动配置 |
开发配置 → 配置并生成编译数据库,再确认写入 .clangd 与 .vscode/settings.json。使用实际 CMake 编译命令获取宏和包含路径,合并查询编译器参数,关闭 C/C++ IntelliSense 引擎以避免冲突;保留已有注释和其他参数。需要安装 clangd 扩展,可通过“查看 clangd 扩展”打开安装入口。 |
| Cortex-Debug 配置 |
先编译并选择当前实际 ELF,再写入调试配置或启动调试。保留用户 launch.json 配置,使用所选 GDB、OpenOCD、探针、SWD 速度和复位方式。需要 Cortex-Debug 扩展;生成配置使用 attach,连接与加载符号,不自动下载固件。 |
| CubeMX 重新生成后的同步 |
监视 .ioc、MDK、CMake 和链接配置变化,在页面提示;预览后确认写入。有 CubeMX MDK 来源时重新计算 CMake 转换;CMake 来源已重新生成时恢复助手管理的源文件块。不运行 CubeMX、不重新生成外设源码、不猜测复杂用户构建逻辑。管理块保存于本机 VS Code 工作区状态,用于重启后的恢复,不保存最近工程列表。 |
| 硬件连接检测 |
开发配置 → 连接并检查硬件,分别显示脚本、探针和芯片状态。直接烧录默认先检查,可取消勾选。仅明确执行后连接硬件,可能暂停或复位目标;不在检测中烧录固件。 |
| 增强 ELF/MAP 分析 |
固件与故障分析 → 选择 ELF 和可选 GNU MAP,查看函数/变量大小排行、目标文件贡献及内存区域。符号排行不直接相加当作总用量;未知布局保持未知,MAP 不替代完整 ELF 装载映像统计。 |
| 一键故障报告 |
从分析页导出,自动整理工具版本、构建/烧录结果和最近输出,替换常见本地路径、IP、邮箱和令牌。先在本地编辑器预览,检查后选择保存位置,不自动上传;自定义敏感信息仍需人工核对。 |
| 串口调试助手 |
设备与诊断 → 刷新 COM 列表、选择波特率、手动连接;支持 ASCII/HEX、可选 LF/CRLF、收发时间戳和本地日志导出。当前为 8N1,DTR/RTS 默认关闭。显示与保留日志有容量上限,关闭工作台或切换工程会释放端口。 |
| HardFault 分析 |
输入捕获的寄存器 JSON 或 CFSR=0x... 文本,按核心解释有效故障位,使用所选 GCC 旁的 addr2line 和 ELF 定位 PC/LR。M0/M0+ 不虚构 CFSR/HFSR;EXC_RETURN、不精确故障与缺失调试信息明确提示。没有运行时自动栈回溯。 |
| FreeRTOS 任务监控 |
输入已运行的本机 GDB Server 地址,手动连接刷新任务快照。使用 ELF 调试符号读取真实 TCB 名称、状态及优先级;能核实栈边界、增长方向与填充条件时显示剩余高水位(StackType_t 单位),否则显示未知。需要支持 Python 的 GDB、匹配 ELF 与目标固件;只读快照可能暂停目标,读取后尝试分离,不自动轮询。 |
| PostHog 匿名使用统计 |
默认关闭。接收方固定为应用开发者的 PostHog 项目,用户无需创建项目或填写令牌;在“设备与诊断”主动启用并通过原生弹窗授权后才发送。仅允许随机匿名标识、版本、语言、功能与成功状态,尊重 VS Code 总遥测开关;不发送路径、代码、日志、串口数据或芯片序列号。服务仍可看到网络来源 IP;关闭后停止发送并清除本机匿名标识。旧的自填项目授权不沿用,接收项目变更需重新授权。 |
统计接收项目配置(维护者)
打包前在 publisher-telemetry.json 中填写开发者项目的 host(HTTPS 采集地址)和 projectToken(phc_ 项目采集令牌)。配置随插件发布,不从用户设置、工程文件或凭据存储读取接收项目;采集令牌属于客户端公开配置,不能使用个人 API 密钥。缺少或无效的配置会禁用统计,不影响其他功能。用户界面只显示接收方、采集服务和授权开关。该修正仅涉及插件,桌面 EXE 不包含统计。
编译数据库的一键导出作用于当前 CMake 构建目录;另填的数据库目录用于选择已有数据库。不要同时启动多个会争用同一目标的调试/检查会话。新功能已做针对性软件样例检查,所有功能均已在实机上完成验证。
v1.2.1 本地修复
- 补齐仅含 CMake 文件工程的插件激活条件;自动打开工作台仍需通过 STM32 特征识别。
- 操作优先复用用户明确选择且仍有效的工具路径,避免重复扫描;版本清单保留完整发现,所选路径缺失时重新检测。
- 内置脚本缓存采用有限并发校验,在单次校验中共享祖先目录检查;继续逐文件校验哈希、恢复损坏或缺失文件、拒绝链接并清除多余文件。工具清单复用本次发现结果,避免同一请求重复扫描。
- 后台取消回执及启动前取消保留统一的取消标志。
本地安装包:artifacts/vsix/stm32-project-helper-1.2.1-win32-x64.vsix。此本地修复已包含在后续公开版本中。
v1.2.0 功能
- 编译与烧录:在工程配置页直接操作,显示当前配置、构建目录、实际固件、进度和结果。任务仍先确认写入,再执行构建;编译不依赖探针或 OpenOCD。烧录在原生弹窗确认后执行,多个 ELF 时需要选择目标。
- 下载器与高级设置:支持 DAPLink/CMSIS-DAP、ST-Link 和 J-Link;可展开设置 SWD 速度与默认复位、连接时保持复位、SYSRESETREQ。实际能力取决于 OpenOCD、探针及芯片;配置软件不自动检查硬件连接。
- 首次配置向导:依次确认工程、工具、芯片与探针、任务改动。可以切换手动配置,并通过“首次配置向导”按钮或命令重新打开。MDK 工程需先转换为 CMake。
- 自定义配置:从预设、构建缓存和当前 File API 信息提供配置建议,也允许输入安全的自定义名称;预设固定配置时遵从该配置。MDK 转换默认生成的仍是 Debug/Release 预设。
- 错误说明:解析 GCC、CMake、Ninja 和 OpenOCD 输出,保留原文并提供对应建议;日志无法确定的连接问题需要结合实际设备判断。
- Flash/RAM 静态分析:选择实际 ELF,根据分配段、装载映像和链接脚本显示静态区域占用、容量、剩余及段分布。复杂或无法确认的布局显示未知,不把 ELF 文件大小当作占用,也不把静态预留当作运行时堆栈测量。
- 大工程与编辑体验:只读检测和预览基于已保存文件,不要求保存源代码;实际写入与编译继续检查未保存文件。文件列表使用虚拟滚动并保持勾选、搜索与位置;差异按文件选择,关闭后释放缓存。消息不携带文件快照和完整构建日志,历史记录仅发送摘要。
- 环境与清理:自动打开前检查 STM32 特征,支持嵌套工程选择;已失效的工具路径重新检测。取消、超时与扩展关闭使用进程树和 Windows Job 清理后台子进程。
本地构建与界面检查不代表硬件烧录、工具安装和所有工程环境已验证,使用者应在自己的工程与设备上确认结果。
v1.2.0 当时的集成状态(历史记录)
上述 v1.2.0 更新已包含在发布的 VSIX 中,包含前端操作、后台请求、任务生成与中英文提示;此次更新不重新发布桌面 EXE。原有六个功能页面继续保留。
本版不新增 clangd、Cortex-Debug、串口、HardFault、FreeRTOS 在线调试、硬件连接检测、最近工程记忆或统计。仅支持本地 Windows x64;WSL、Remote SSH 和虚拟工作区不支持。SWD 速度允许 1–50000 kHz,实际有效值取决于硬件;不支持的复位/传输组合会明确拒绝。静态内存分析的未知布局保持未知,不表示运行时堆栈占用。
发布前已完成打包与中英文界面查看;按本次交付要求,没有运行功能回归或硬件测试,也没有在本次文档同步后追加检查。功能已集成与功能已通过实机验证是不同状态。
下载与运行要求
| 项目 |
要求 |
| 扩展版本 |
1.2.0 |
| 操作系统 |
本地 Windows x64 |
| 编辑器 |
VS Code 1.95 或更新版本 |
| 工作区 |
本地文件夹,已授予工作区信任 |
| .NET |
VSIX 自带后台运行时,无需另行安装 |
| 构建工具 |
CMake、Ninja、ARM GCC;OpenOCD 用于脚本检查和烧录任务 |
从 v1.4.0 发布页 下载 VSIX 安装包(约 9 MB)。本地打包路径为 artifacts/vsix/stm32-project-helper-1.4.0-win32-x64.vsix。安装包使用经过裁剪的后台运行库,保留全部功能代码、JSON 协议模型与内置 OpenOCD 脚本。
安装
- 下载
stm32-project-helper-1.4.0-win32-x64.vsix 安装包。
- 在 VS Code 中按
Ctrl+Shift+X 打开扩展面板。
- 点击扩展面板右上角的
…,选择“从 VSIX 安装…”,选中下载的文件。
- 安装完成后重新加载 VS Code 窗口。若未出现提示,可通过命令面板执行“Developer: Reload Window”,或关闭并重新打开 VS Code。
- 打开包含
CMakeLists.txt、.ioc 或 MDK .uvprojx 的工程文件夹,并信任该工作区。
默认自动打开工程工作台。也可点击活动栏的蓝色芯片图标,或在命令面板执行“STM32 工程助手:打开”。
更新
准备新版 VSIX,再次执行“从 VSIX 安装…”,覆盖已有扩展后重新加载窗口,无需先卸载。扩展标识保持 myfsillyba.stm32-project-helper;已有工作区工具设置和修改记录继续使用。
桌面程序与 VS Code 扩展分别编号、分别发布。扩展安装文件为 .vsix,桌面运行文件为 .exe。
界面语言
默认跟随 VS Code 的显示语言:中文显示中文界面,其他显示语言使用英文界面。工作台右上角的语言选择器提供“跟随 VS Code / 中文 / English”,也可在设置中调整 stm32ProjectHelper.language。
语言选择覆盖六个功能页面、侧栏、按钮、确认弹窗、进度、软件生成的检测与兼容性说明、构建结果及问题建议。切换时保留填写的配置和文件选择,不修改工程文件;操作进行中暂不切换,当前操作结束后再应用新的语言。
下一次确认写入时,工具管理的任务按当前语言生成:中文为“一键编译 / 一键烧录(DAPLINK)”,英文为“One-click Build / One-click Flash (DAPLINK)”。仅更新工具管理的任务,保留用户任务与注释。既有任务不会因单纯切换界面语言而被改写。
工程路径、芯片和目标名称、用户代码及编译器原始输出保留原文。VS Code 命令面板与扩展设置中的静态标题跟随 VS Code 自身的显示语言。
操作流程
工程配置
- 核对当前工程、芯片识别依据、配置预设、构建预设、构建目录和 OpenOCD 目标脚本。
- 检测到同一种工具的多个安装时,点击“选择版本…”;按版本号和完整路径选择,也可手动指定可执行文件。工具通过验证后保存到当前工作区。
- 点击“确认写入…”。扩展重新计算当前改动,在原生弹窗中列出工程、操作摘要及受影响文件;确认后保存任务和必要的 CMake 辅助文件。
- 点击“运行软件检查”,执行 CMake 配置、实际编译与 OpenOCD 脚本解析。问题显示在 VS Code 的问题面板和“STM32 工程助手”输出频道。
- 编译成功后,从当前构建目标的实际 ELF 列表选择固件,确认烧录任务绑定。
“预览改动”是可选入口,可以查看 VS Code 原生文件差异。直接写入不要求先打开差异页。运行软件检查时若任务尚未配置,扩展会先请求确认并写入任务,再执行构建;编译未通过时保留已写入任务。
工程配置页顶部可直接编译、烧录并查看 Flash/RAM 分析,也可以使用命令面板的对应命令。直接烧录会先编译、选择实际 ELF,再要求原生弹窗确认。原有“终端 → 运行任务”入口仍保留,任务名称随语言和所选下载器生成;默认中文任务为“一键编译 / 一键烧录(DAPLINK)”。软件检查不连接硬件。
添加源文件
选择当前工程内的文件夹和 CMake 目标,扫描后搜索并逐项选择需要注册的 C/C++、汇编及头文件。未勾选文件不加入构建。确认写入后维护 CMakeLists.txt 中对应目标的源文件与包含目录;需要验证时返回工程配置执行软件检查。
加入文件
输入工程内的目标文件夹名称,通过本地文件选择器选择来源文件,预览复制计划后确认复制。目标文件夹已存在时需确认追加;同名文件自动改名,保留来源文件。复制完成后可在“添加源文件”中选择参与构建的文件。
工程转换
仅支持保留 .ioc 与生成源码的 STM32CubeMX 单核 STM32 工程,不安装或调用 CubeMX。
- MDK-ARM → CMake:检查工程,选择
.uvprojx 和构建目标,查看兼容性问题后确认写入。
- CMake → MDK-ARM:选择配置,确认运行 CMake 配置以读取实际构建目标,再选择目标并确认写入 MDK 工程。该检查会在构建目录生成缓存和构建文件。
存在阻止转换的问题时会列出补全说明。转换生成工程与工程编译是两个步骤;生成文件后可运行软件检查。支持范围、CMSIS DSP 库匹配、FreeRTOS 移植层及内存布局限制见 项目说明。
工具管理
支持选择本地工具、修复缺失工具、导入离线 ZIP 包和激活已有安装。下载仅在明确点击并确认后执行。检测到多个已有安装时,先提示选择版本,再按需修复缺失工具。OpenOCD 使用扩展内置的完整 scripts 目录,其路径作为只读信息展示。
修改记录
查看当前工程的修改记录,预览后恢复配置。若文件在备份后已被再次修改,会列出冲突并要求单独确认。恢复也会保存记录。
工程与配置保护
- 保留原有任务、JSONC 注释及工程工具链文件。任务只更新本工具管理的内容。
- ELF 来自当前 CMake 构建配置的可执行目标,不按工程文件夹名称猜测,也不从旧文件中选择最近修改者。
- 所选 CMake、Ninja 与 ARM GCC 使用绝对路径。工具路径或工程位置与旧缓存不一致时,先备份缓存,再重新配置。
- 配置预设固定构建类型时,界面跟随预设;未固定时允许工程提供或手动填写的自定义配置。
- 实际写入、编译等依赖磁盘内容的操作检查当前工作区未保存文件并要求“保存后继续”;只读检测和预览不强制保存。导入流程还检查明确选中的外部来源文件;取消时保留编辑内容。
- 多工作区通过侧栏的文件夹按钮切换,打开另一工作区的源文件也会切换当前工程。耗时操作期间暂停自动跟随编辑器切换。
- 耗时操作支持取消,显示步骤和输出,不生成
.ps1 文件。
扩展设置
| 设置 |
用途 |
stm32ProjectHelper.autoOpen |
工程检测后的自动打开,默认启用 |
stm32ProjectHelper.language |
auto 跟随 VS Code,zh-CN 中文,en 英文;保存为全局界面偏好 |
stm32ProjectHelper.tools.cMake |
CMake 可执行文件路径,留空自动检测 |
stm32ProjectHelper.tools.ninja |
Ninja 可执行文件路径 |
stm32ProjectHelper.tools.compiler |
arm-none-eabi-gcc 可执行文件路径 |
stm32ProjectHelper.tools.openOcd |
OpenOCD 可执行文件路径 |
工具选择与修复结果写入当前工作区的设置,不替换工作区已选的有效工具,也不改写桌面程序保存的全局工具路径。
常见问题
安装后没有显示工作台:确认使用本地 Windows x64 窗口,工程包含受支持的文件且工作区已信任,然后执行“STM32 工程助手:打开”。可通过扩展设置关闭或开启自动打开。
工具显示“待选择”:检测到多个安装,需要明确选择版本。已有工具并不需要因此重新下载。
生成的 ELF 名称与工程文件夹不同:名称由 CMake 构建目标和 OUTPUT_NAME 等配置决定。烧录任务绑定实际生成的固件,无需重命名文件夹。
任务已写入但编译未通过:已写入任务保留。打开问题面板或输出频道定位编译问题,修正后重新运行软件检查或“一键编译”。
Target 脚本可用是否代表硬件已连接:脚本检查只确认软件配置,硬件烧录由“一键烧录(DAPLINK)”任务执行。
从源码打包与检查
需要 Windows x64、.NET 9 SDK 和 Node.js 22 或更新版本。在仓库根目录执行:
cd src/STM32ProjectHelper.VSCode
npm ci
npm run check
npm run package
VSIX 写入 artifacts/vsix。打包只发布独立后台和扩展,不重新发布桌面 EXE。构建产物、依赖和后台二进制不提交到 Git。
本机已安装 CMake、Ninja、ARM GCC 与 OpenOCD 时,可执行正常软件流程:
npm test
npm run smoke
npm test 使用临时工程检查任务写入、真实 ARM 编译、文件管理、恢复、工具选择与双向转换。npm run smoke 使用隔离的普通 VS Code 窗口检查扩展,并确认该检查窗口内的测试写入弹窗;可用 VSCODE_EXECUTABLE_PATH 指定本机 VS Code。检查不连接硬件。
问题反馈与许可证
通过 GitHub Issues 提供扩展版本、VS Code 版本、Windows 版本、操作步骤与相关输出。涉及转换时补充方向、芯片型号及所选目标。
应用源码使用 MIT License。内置 OpenOCD 脚本保留原始版权及许可证声明;第三方工具遵循各自许可证。