STM32 调试配置器 是专为 STM32 开发者设计的下一代 Visual Studio Code 扩展。它提供了超现代的图形界面，用于智能高效地管理和生成 Cortex-Debug 配置文件 (launch.json)。
此扩展通过智能环境感知和用户友好的界面大大简化了 STM32 调试配置的复杂性，让开发者能够专注于代码而不是繁琐的配置细节。
- 🚀 零配置：自动检测 OpenOCD 安装和配置文件
- 🎨 现代界面：清爽、直观的界面，支持深色/浅色主题
- 🌍 多语言：完全支持中英文界面
- 🔍 智能搜索：接口和目标文件的高级搜索功能
- 📊 实时监控：调试会话期间的实时变量监控
- 🔧 灵活配置：支持多种 GDB 服务器（OpenOCD、J-Link、pyOCD 等）
- 专用活动栏图标，一键访问
- 无需在命令面板中搜索
- 即时访问调试配置
- 实时显示调试配置
- 快速访问最近使用的配置
- 可视化管理和编辑调试配置
- 一键快捷操作
- 自动路径检测：智能扫描常见的 OpenOCD 安装位置
- 自定义路径支持：配置自定义 OpenOCD 可执行文件路径
- 文件浏览器：内置文件浏览器选择 OpenOCD 可执行文件
- 接口文件搜索：实时搜索和过滤接口配置文件
- 目标文件搜索：智能搜索目标配置文件，即时过滤
- 调试期间动态添加/删除监控变量
- 直观的变量管理界面
- 实时变量状态更新
- 可配置更新频率以优化性能
- 基于系统设置自动检测语言
- 中英文间无缝切换
- 本地化界面元素和消息
- 持久化语言偏好
- OpenOCD（推荐）
- J-Link GDB Server
- pyOCD
- ST-Link GDB Server
- ST-Util
- 无需手动编辑 JSON
- 直观的表单式配置
- 实时验证和反馈
- 常用设置的自动完成
- 自动检测 Cortex-Debug 扩展
- 提示缺少的依赖项
- 自动或手动指定 .elf 文件路径
- 无需额外插件独立运行
- 智能更新
launch.json，保留现有配置 - 自动配置全局 Cortex-Debug 设置
- 消除手动配置步骤
- 配置持久化和历史记录
- Visual Studio Code：1.80.0 或更高版本
- Cortex-Debug 扩展：必需依赖项（自动检测）
- OpenOCD：推荐用于 STM32 调试（可选，但推荐）
- 打开 Visual Studio Code
- 进入扩展视图（
Ctrl+Shift+X或Cmd+Shift+X） - 搜索 "STM32 Debug Configurator by zuolan"
- 点击 安装
- 如提示重新加载 VS Code
- 从 发布页面 下载最新的
.vsix文件 - 打开 VS Code
- 进入扩展视图
- 点击 "..." 菜单并选择 "从 VSIX 安装..."
- 选择下载的
.vsix文件 - 重新加载 VS Code
- 安装 Cortex-Debug：如未安装，扩展会提示您
- 安装 OpenOCD（推荐）：
- Windows：从 OpenOCD 发布页面 下载
- macOS：
brew install openocd - Linux：
sudo apt-get install openocd（Debian/Ubuntu）
- 配置 OpenOCD 路径（如果未自动检测）：
- 打开 VS Code 设置
- 搜索 "stm32-configurator.openocdPath"
- 设置 OpenOCD 可执行文件的路径
- 在 VS Code 中打开您的 STM32 项目
- 点击活动栏中的 STM32 调试配置器图标（左侧边栏）
- 配置您的调试设置：
- 选择 .elf 文件来源（自动/手动）
- 选择 GDB 服务器（推荐 OpenOCD）
- 选择接口文件（使用搜索过滤）
- 选择目标文件（使用搜索过滤）
- 根据需要配置其他选项
- 点击"生成配置"按钮
- 使用 VS Code 的运行和调试视图开始调试
自动检测模式（需要 ST 的 STM32 扩展）：
- 自动从构建输出中找到 .elf 文件
- 无需手动配置路径
手动模式：
- 指定 .elf 文件的确切路径
- 支持工作区变量如
${workspaceFolder} - 示例：
${workspaceFolder}/build/Debug/myproject.elf
路径配置：
- 点击"浏览"选择 OpenOCD 可执行文件
- 点击"扫描"重新检测系统 PATH 中的 OpenOCD
- 或在设置中手动输入路径
接口文件选择：
- 点击接口文件下拉菜单
- 使用搜索框过滤选项（例如，输入 "stlink" 查找 ST-Link 接口）
- 从过滤结果中选择您的调试器接口
- 常见接口：
stlink.cfg- ST-Link V2/V3cmsis-dap.cfg- CMSIS-DAP 兼容调试器jlink.cfg- J-Link 调试器
目标文件选择：
- 点击目标文件下拉菜单
- 使用搜索框按芯片系列过滤（例如，"f4" 查找 STM32F4 系列）
- 选择您的具体 MCU 目标
- 示例：
stm32f4x.cfg- STM32F4 系列stm32h7x.cfg- STM32H7 系列stm32g0x.cfg- STM32G0 系列
SVD 文件（可选）：
- 提供外设寄存器描述
- 在调试会话中启用寄存器视图
- MCU 的 .svd 文件路径
适配器速度：
- 默认：4000 kHz
- 较低值以提高稳定性（500-1000 kHz）
- 较高值以提高速度（最高 10000 kHz）
LiveWatch 变量：
- 启用 LiveWatch 复选框
- 添加要监控的变量：
- 点击"添加变量"
- 输入变量名
- 支持全局变量、结构成员
- 配置更新频率（1-100 采样/秒）
扩展支持多个调试配置：
- 为不同目标生成不同配置
- 每个配置都以唯一名称保存
- 从树视图访问最近配置
- 轻松在配置间切换
| 设置 | 类型 | 默认值 | 描述 |
|---|---|---|---|
stm32-configurator.openocdPath |
string | "" | OpenOCD 可执行文件的自定义路径 |
stm32-configurator.language |
enum | "en" | 显示语言（en/zh） |
扩展在 .vscode/launch.json 中生成完整的调试配置：
{
"version": "0.2.0",
"configurations": [
{
"name": "STM32 Debug",
"type": "cortex-debug",
"request": "launch",
"servertype": "openocd",
"cwd": "${workspaceFolder}",
"executable": "${workspaceFolder}/build/Debug/project.elf",
"configFiles": [
"interface/stlink.cfg",
"target/stm32f4x.cfg"
],
"svdFile": "${workspaceFolder}/STM32F407.svd",
"openOCDLaunchCommands": [
"adapter speed 4000"
],
"liveWatch": {
"enabled": true,
"samplesPerSecond": 4
}
}
]
}主要的 webview 面板提供了直观的表单来配置所有调试设置：
- 清爽现代的设计，支持主题
- 实时验证和反馈
- 可搜索的文件选择下拉菜单
- 按不同配置方面组织的有序部分
活动栏侧边栏显示：
- 当前调试配置
- 最近配置历史记录
- 快速操作按钮
- 配置状态指示器
动态变量管理界面：
- 动态添加/删除变量
- 配置更新频率
- 活动变量的可视化反馈
| 平台 | 支持 | 备注 |
|---|---|---|
| Windows | ✅ 完全支持 | 自动检测 STM32CubeIDE 安装 |
| macOS | ✅ 完全支持 | 支持 Homebrew OpenOCD |
| Linux | ✅ 完全支持 | 检测包管理器安装 |
Windows：
- STM32CubeIDE 安装
C:\OpenOCD\C:\Program Files\OpenOCD\%USERPROFILE%\AppData\中的 xPack 安装
macOS/Linux：
- 系统 PATH
/usr/local/bin//opt/openocd/- 用户主目录安装
问题：扩展无法找到 OpenOCD 解决方案：
- 从官方发布页面安装 OpenOCD
- 使用"浏览"按钮手动选择 OpenOCD 可执行文件
- 或在 VS Code 设置中设置路径：
stm32-configurator.openocdPath
问题：下拉列表为空 解决方案：
- 确保 OpenOCD 路径配置正确
- 点击"扫描"刷新 OpenOCD 检测
- 检查 OpenOCD 安装是否包含配置文件
问题：调试会话启动失败 解决方案：
- 从市场安装 Cortex-Debug 扩展
- 确保 GDB 已安装并在 PATH 中
- 验证 .elf 文件路径正确
- 检查调试控制台的具体错误消息
问题：搜索框不过滤结果 解决方案：
- 确保在搜索框中输入，而不是下拉菜单
- 等待过滤生效
- 用 × 按钮清除搜索重置
调试会话期间有用的 OpenOCD 命令：
monitor reset halt # 复位并停止目标
monitor flash erase_address 0x08000000 0x100000 # 擦除闪存
monitor flash write_image erase firmware.elf # 编程闪存
monitor reset run # 复位并运行
- OpenOCD scripts 目录识别覆盖更多打包方式：之前只检查
<root>/share/openocd/scripts和<root>/scripts，遇到从 GitHub 下载的 win32-x64 包多嵌一层openocd/（C:\Program Files\openocd\openocd\scripts\）的解压结构时，cfg 选择器一直空。新增对OPENOCD_SCRIPTS环境变量、<root>/openocd/scripts、<root>/openocd/share/openocd/scripts、<binDir>/scripts的识别，并以 installRoot 为起点递归两层兜底搜索；候选要求同时含interface/和target/子目录避免误命中
- 修复 Marketplace 安装后所有命令报
command 'xxx' not found的致命问题：src/services/index.ts的 barrel 文件意外再导出了./toolchainDetectionService.test，编译产物里out/services/index.js因此require('./toolchainDetectionService.test')；.vscodeignore已把*.test.js从 vsix 排除，导致激活时Cannot find module异常，activate()整个挂掉，所有命令注册都跑不到。dev (F5) 因为 out/ 完整不受影响，只有发布版本受波及
- 扩展首次安装时 webview UI 默认显示中文；如果 VS Code 本身是英文界面则自动切换为英文
- Marketplace 详情页默认显示中文 README（原英文版本迁到
README_en.md） - 已经手动切换过语言的用户保留原选择，不会被强制覆盖
- 1.0.0 CHANGELOG 移除错误列入的内部开发条目（未影响实际功能）
首个稳定版本。本次自动化重做将"读 .ioc → 找工具链 → 选 cfg → 输出 launch.json"全链路从手动填表升级为打开即用。
- STM32 设备自动检测：扫描工作区里
.ioc/.cproject/CMakeLists.txt，自动填型号（如STM32H743ZITx），下方显示来源文件 - 固件文件自动扫描：发现
build/Debug等目录下所有.elf/.axf/.bin/.hex，按 Debug > Release、elf > axf > hex > bin 排序后下拉选择 - OpenOCD cfg 模态选择器：点击接口/目标输入框 → 弹出居中对话框，顶部搜索 + 滚动列表 + 当前值高亮 + ↑↓/Enter/Esc 键盘操作 + 背景模糊
- 多工具链候选下拉：列出所有检测到的 ARM 工具链（STM32 官方扩展 bundle 各版本、PATH、cortex-debug 用户配置、其他常见路径），下拉切换无需重新扫描
- STM32 官方扩展 bundle 优先识别：
%LOCALAPPDATA%\stm32cube\bundles\gnu-tools-for-stm32\<ver>自动转成${env:LOCALAPPDATA}/...可移植格式写入 launch.json - target.cfg / interface.cfg 智能匹配：根据设备型号推 target（
STM32H7 → stm32h7x.cfg）；接口默认cmsis-dap.cfg → stlink.cfg；用户手动选择后不再覆盖 - SWD / JTAG 传输方式选择：影响
interface字段和openOCDLaunchCommands的transport select gdbPath自动写入：根据工具链 bin 推导，ST bundle 走可移植形式
- 12 列响应式 grid + 卡片布局，替代原来的长竖条。卡片：项目 / 目标设备 / GDB Server / ARM 工具链 / 高级选项
- 编号徽章、统一间距阶梯、native VS Code 颜色变量、自定义下拉箭头、status / info 卡视觉重做
armToolchainPath修正为 bin 目录（cortex-debug 期望的格式），之前错写成gcc.exe完整路径- 生成的 launch.json 补全
serverpath/interface/showDevDebugOutput/transport select，空 SVD 不再写入 - 不再生成
${command:st-stm32-ide-debug-launch...}这种依赖 ST 扩展的字符串 - 修复 webview 消息丢失 race（
onDidReceiveMessage注册时机过晚导致 cfg 下拉一直空） - 修复
expandPath通配符*在路径中段时 baseDir 算偏一级的 bug - 修复多个未定义全局（
stateManager/createStateIndicator/validateGenerationData）导致 webview 初始化崩溃 - 修复 target / interface 智能填充被默认选中误判为"用户已选过"
- 修复语言切换 dropdown 与实际 UI 不一致
- 📚 文档和打包更新：同步所有版本的README版本信息和更新日志
- 📦 包优化：清理VSIX包，排除开发文件和文档
- ✅ 版本一致性：确保package.json、README和GitHub发布版本对齐
- 🔄 改进发布流程：完善打包和发布工作流程
- 🔧 强化 OpenOCD 配置验证：增强配置验证机制，防止配置错误
- ⚡ 改进错误处理：更好的错误检测和用户反馈
- 🛡️ 增强调试可靠性：提高调试配置生成过程的稳定性
- ✅ 完善验证逻辑：更全面的OpenOCD路径和配置检查
- 🔧 ARM工具链完整集成：完整的ARM GNU工具链检测和配置
- 🎯 智能路径检测：多策略工具链发现，跨平台支持
- 📚 用户友好设置：直接下载链接和引导式配置流程
- ⚙️ 自动配置服务：一键完整环境设置
- 🌐 路径标准化：跨平台路径处理和正斜杠标准化
- 🔧 版本升级和功能优化
- ➕ 添加部分操作和功能完善
- 🔍 增强了接口和目标文件的搜索功能
- 📁 添加了 OpenOCD 可执行文件选择的文件浏览器
- 🌍 改进了本地化支持
- 🐛 错误修复和性能改进
- 🎯 添加了活动栏集成
- 📊 实现了 LiveWatch 变量监控
- 🌐 添加了多语言支持（中英文）
- 🔧 改进了 OpenOCD 路径检测
- ✨ 主要功能更新
- 🎨 新的现代界面设计
- 📁 添加了树视图侧边栏
- 🔄 配置持久化
- 🚀 首次公开发布
- 📝 基础配置生成
- 🔧 OpenOCD 集成
欢迎贡献！请随时提交问题和拉取请求。
- 克隆仓库：
git clone https://github.com/zuoliangyu/stm32-configurator-by-zuolan.git- 安装依赖：
npm install- 在 VS Code 中打开：
code stm32-configurator-by-zuolan- 按
F5在新的扩展开发主机窗口中运行扩展
npm run test:all # 运行所有测试
npm run test:unit # 运行单元测试
npm run test:coverage # 运行带覆盖率的测试- Cortex-Debug - 提供调试框架
- OpenOCD - STM32 调试支持
- VS Code 团队 - 出色的扩展 API
- STM32 社区 - 反馈和建议
特别感谢所有帮助改进此扩展的贡献者和用户！
本项目基于 MIT 许可证 - 详情请参阅 LICENSE 文件。