“我板子呢？”——WSL如何烧录STM32开发板(基于STM32的嵌入式C++编程之旅（7）)

搞嵌入式开发的朋友，尤其是那些习惯在Windows下写代码、用Linux做服务器的人，应该都体会过这种撕裂感。代码写在Windows上，编译的时候想用Linux的工具链，烧录的时候又得切回Windows点那个烧录软件。我之前几篇之旅文章都是在Windows环境里折腾，今天这篇，专门解决一个实际问题：人坐在WSL里，手里拿着STM32开发板，怎么把它烧录上。

先说清楚这篇文章能干什么。简单来说，就是在WSL里面直接把编译好的固件烧录到STM32芯片里，不用切回Windows，不需要在Windows里额外装驱动，也不需要准备一个单独的虚拟机。整个过程只需要两个核心工具：一个叫做openocd，另一个就是你已经有的WSL本身。如果你正在用WSL做STM32的C++开发，或者你被“板子认不到”、“烧录器连接失败”这类问题折磨过，这篇文章就是给你准备的。

1. 环境准备与整体思路拆解

在动手之前，先把问题拆干净。WSL烧录STM32，卡住很多人的第一道坎，就是设备访问权限。WSL里的程序默认是不能直接操作你电脑的USB接口的，串口和调试器都算是USB设备，所以第一步不是装烧录软件，而是让WSL能够“看到”并“摸到”你的硬件。

1.1 硬件层面的准备：你需要一根好用的USB线

很多人烧录失败，排查了半天软件问题，最后发现是USB线的问题。STM32开发板上那个USB口，很多是Micro-USB或者Type-C，线材质量参差不齐。尤其是那种只能充电、不能传数据的“电源线”，插上去之后板子灯亮了，但调试器根本没法枚举。我建议你手边备两根不同的USB线用来交叉测试，一根不行就换另一根，这一步能帮你省下大半个小时的排查时间。

另外，不同的开发板板载调试器不一样。常见的比如ST-Link、DAPLink、J-Link onboard版本，它们通过USB连接电脑后在系统里呈现的设备名称是不同的，但好在它们在WSL里的访问方式差别不大，都是通过USB设备节点来访问。确认你的板子上板载调试器的类型，这决定着我们后面在openocd配置文件里要用哪种调试器协议。

1.2 为什么选择WSL而不是虚拟机或者裸Linux

我在实际项目里权衡过很长一段时间，最后把日常开发固件编译和烧录工作流全部挪到了WSL下。原因很简单：WSL的启动速度比虚拟机快得多，IO性能在大量小文件编译的场景下比虚拟机明显更快，而且它和Windows宿主机的文件系统是互通的，我完全不需要在两个操作系统之间拷贝文件。

不过这里有个重要前提，如果你是用的WSL 1，那USB设备的支持就会比较麻烦。WSL 2（基于轻量级虚拟机）在设备访问上虽然没有原生透传那么顺滑，但通过Windows侧的工具转发之后，实际体验已经非常接近原生。所以，如果你的WSL版本还停留在1，建议升级到WSL 2，稳妥得多。

1.3 核心方案选型：OpenOCD + GDB Client

烧录方案其实不少。你可以用ST官方工具在Windows上烧，也可以用一些图形化的烧录工具。但在WSL里，最可靠、最可脚本化的方案就是OpenOCD。

这个工具本身就是一个上位机的调试/烧录桥接程序，它支持JTAG、SWD以及各种常见调试器协议，包括ST-Link和CMSIS-DAP（DAPLink就是其中一种）。因为它完全不依赖GUI，纯命令行驱动，所以在WSL这种环境里反而如鱼得水，配合脚本还能实现一键编译、一键烧录、一键调试的自动化流程。加上它天然支持GDB的远程调试协议，后续你甚至可以直接在WSL里写好代码、编译完、启动OpenOCD做烧录和在线调试，全程不离开终端。

2. WSL侧与Windows侧的USB设备透传配置

既然核心方案定了，接下来就是打通硬件访问的这一公里。我不会直接丢给你一个一键脚本，而是先把原理说清楚，不然配置出问题的时候你会完全无从下手。

2.1 认识WSL对USB设备的访问机制

WSL 2本身跑在一个轻量级虚拟机里，它对宿主机的硬件设备（比如USB调试器）没有直接的访问权限。想要让WSL里的进程操作USB设备，得在Windows宿主机的“幕后”启动一个转发服务，然后WSL里的工具把这个服务当作一个网关来访问设备。

平时大家讨论WSL使用USB设备时，常提到一个工具方案，通常的安装方式是：在Windows里安装管理工具，然后在WSL里安装对应的客户端。这里我以几个实际项目里验证过的步骤为例展开说。

注意：以下操作需要在每一个新终端会话里执行，或者在启动脚本里固化，不然重启电脑后又得手动敲一遍。

2.2 在Windows宿主侧安装工具与驱动

首先，确保你的Windows上安装了USB设备管理相关的组件。如果环境里还没有，请以管理员身份打开PowerShell，执行以下命令：

# 安装 Windows 侧的 USB 设备转发管理工具 winget install --exact --id 某个开源工具ID

运行完毕后，以管理员身份启动PowerShell，执行USB设备转发服务的启动命令。每次电脑重启后，这个服务不会自动开启，所以我习惯把这一行记在文本笔记里，或者写成一个bat脚本放在桌面上。

usbipd bind --default

这里额外提醒一点，bind操作的作用是告诉Windows系统，将这个USB设备标记为可被转发设备，它不需要指定具体设备名称，如果后续要解绑，可以用usbipd unbind --default。

2.3 在WSL侧安装客户端工具

WSL里面需要安装与之匹配的客户端工具。在Ubuntu等发行版下，直接用apt安装：

sudo apt update && sudo apt install -y linux-tools-virtual

安装完客户端后，还需要做一步关键的兼容性处理。WSL内默认缺少usbip这个命令的符号链接，你需要手动创建一下，否则后面执行设备列表命令时会有问题：

sudo ln -s /usr/lib/linux-tools/*/usbip /usr/local/sbin/usbip

2.4 让WSL“看到”你的开发板

现在可以连接开发板了。用USB线把STM32开发板连上电脑，板载调试器的指示灯亮了之后，在Windows的PowerShell里执行：

usbipd list

你会看到类似下面这种输出：

BUSID VID:PID DEVICE STATE 1-2 0483:3748 STMicroelectronics STLink ... Not attached

在这个列表里，找到你板载调试器对应的总线ID，例如1-2。然后执行绑定并连接：

usbipd bind --busid 1-2 usbipd attach --wsl --busid 1-2

这里要注意，attach操作需要你的WSL发行版正在运行，它会把USB设备“临时”挂载给WSL，状态从Not attached变为Attached。

2.5 在WSL里验证设备是否就绪

回到WSL终端，执行：

lsusb

正常情况下，你应该能在输出里看到ST-Link或DAPLink相关的设备信息。如果看不到，不要急着继续下一步，请在Windows侧再次执行usbipd list确认STATE是否为Attached，如果状态正常但WSL里看不到，那问题大概率出在第2.3步的符号链接上。

3. OpenOCD的安装配置与板级支持文件解析

设备通了，接下来就是重头戏：把OpenOCD装好，并理解它如何跟板子交互。

3.1 安装OpenOCD：选择发行版自带还是源码编译

OpenOCD在Ubuntu 22.04或24.04的软件源里通常都有，版本相对较新。如果你的项目没有用到特别新的调试器功能，直接用apt安装完全够了：

sudo apt install -y openocd

想要确认安装成功，执行openocd --version。很多时候，如果你需要支持某些特定厂商的非主流调试器，或者需要芯片Errata工作区里的一些新特性，才需要考虑源码编译安装。源码编译也不复杂，本质上就是./configure && make，但它会让整个环境里出现两套OpenOCD，容易引起路径混乱。我个人是建议没有特殊需求千万别折腾源码编译，把精力留在代码上。

3.2 理解openocd的配置文件：接口和芯片是两个维度

OpenOCD的工作方式很直白：先用接口配置告诉它你用的是什么调试器，再用芯片配置告诉它目标芯片是什么型号，最后通过命令指挥它进行烧录或调试。这三个要素缺一不可。

以我常用的开发板为例，假设它的板载调试器是ST-Link，主控芯片是STM32F407系列，那么它的启动命令通常是：

openocd -f interface/stlink.cfg -f target/stm32f4x.cfg

这条命令启动后，OpenOCD会在本地开一个端口（默认3333），用于接GDB客户端，同时它会在终端里输出详细的连接日志。如果一切正常，你会看到类似Info : stlink.capture_trace和Info : STM32F407ZGTx: 1024kbytes flash这样的字样。看到这些就说明你的调试器跟芯片已经建立了连接，烧录准备工作完成。

3.3 如果你用的是DAPLink调试器

有些开发板板载的不是ST-Link，而是DAPLink，它们的OpenOCD配置是不同的。在interface/目录里找到对应的配置文件，命名通常是cmsis-dap.cfg。

我建议你自己动手打开这些cfg文件看一眼，你会发现它们本质就是一系列简单的初始化参数设置。一行一行读下来，能帮助你建立起对调试器初始化流程的直观认识，后续遇到奇怪问题排查时，你会感激现在的这个动作。

3.4 关键参数详解：adapter speed与reset_config

adapter speed决定SWD通信时钟频率，默认值一般会比较保守。如果你想追求更快的烧录速度，可以尝试在命令行里追加：

openocd -f interface/stlink.cfg -f target/stm32f4x.cfg -c "adapter speed 4800"

这里有一个几何级数增长的调整经验，如果连接不稳定，先把速率降回到默认值，不要一味追求高速。高速模式下，线材稍长或接触不良都会导致握手失败。调试器类型的差异也会影响速度上限，所以别人给的极限值不一定适合你的硬件环境。

还有一种常见情况：板子上电默认的复位引脚电平不对，导致芯片一直处于复位状态，连接失败。一旦遇到这种情况，可以考虑调整复位配置：

openocd -f interface/stlink.cfg -f target/stm32f4x.cfg -c "reset_config srst_only"

这条命令的意思是告诉OpenOCD，复位信号主要由调试器的SRST引脚控制。如果你的板子没有独立引出复位控制引脚，这个配置就非常关键。

4. 烧录实操：从编译产物到芯片Flash

万事俱备，现在开始真正的烧录操作。

4.1 确认你的编译产物路径

在STM32的C++开发中，编译后的产物通常是一个.elf文件，还有用于生产烧录的.bin和.hex文件。OpenOCD支持直接烧录这三种格式。在我的某个模拟项目X中，工程构建脚本会把project.elf和project.bin输出到一个build/目录。你只需要确认这个文件的路径，烧录命令就得靠它。

4.2 烧录命令的完整语法

对于.bin文件，烧录命令是这样的：

openocd -f interface/stlink.cfg -f target/stm32f4x.cfg -c "program build/project.bin 0x08000000 verify reset exit"

这里面有几个关键点值得展开说一说。

program是OpenOCD内置的烧录命令，后面跟文件的路径以及烧录的起始地址。STM32内部的Flash映射地址起始于0x08000000，这个地址是芯片厂商指定的，程序从这个地址开始执行。如果你的固件是.elf格式，OpenOCD能直接从ELF文件里读取到正确的烧录地址，此时可以省略掉地址参数，直接写成：

openocd -f interface/stlink.cfg -f target/stm32f4x.cfg -c "program build/project.elf verify reset exit"

verify参数表示烧录完成后回读Flash并进行比对，确保数据完全一致。绝大多数场景下我建议保留这个参数，因为烧录器接触不良或供电不稳时，写进去的数据可能是错的，如果没有校验过程，这个错误会在运行时以非常诡异的方式暴露出来。

reset参数是在烧录完成后让芯片自动复位运行，exit是让OpenOCD完成操作后自动退出终端。

4.3 实际执行过程与输出解读

在WSL终端里运行上述命令，正常情况下会看到类似这样的日志序列：

Info : Found SWD DP with ID 0x2ba01477 Info : Using clocked SWD and 4 MHz Info : flash size = 1024kbytes Info : Target voltage: 3.24 V Info : writing 8192 bytes to flash... Info : erasing 16 sectors Info : writing... Info : Verified OK

看到Verified OK之后，基本上烧录流程就走完了。此时你的开发板应该已经自动开始运行新的固件了。

4.4 关于烧录地址偏移的常见场景

如果你的项目加入了BootLoader，比如官方常见的串口IAP方案，那么你的应用程序通常就不是从0x08000000启动了，而是从0x08008000或0x08010000等偏移地址启动。此时，你只需要把烧录命令里的地址参数改成对应的偏移地址即可：

openocd -f interface/stlink.cfg -f target/stm32f4x.cfg -c "program build/app.bin 0x08008000 verify reset exit"

但是光改烧录地址是不够的，你的工程代码里还需要把中断向量表的偏移量也改到对应位置，这属于工程配置的层面。如果在烧录工程里发现程序跑不起来，大概率是向量表偏移没有设置一致。

5. 常见问题排查与高效调试工作流

到这一步，基本的烧录已经打通了。接下来才是真正能拉开开发效率的部分，把烧录和调试结合到一起，并且解决掉那些让人血压飙升的软故障。

5.1 OpenOCD连接失败的四类原因速查

我总结了这几类导致OpenOCD连不上芯片的典型问题，希望对你有帮助。

第3种情况在实际开发时发得比较多。某些低功耗模式下，内核时钟已经停止，调试器无法直接暂停芯片的运行，导致连接时报告target not halted。这时候你可以尝试用一根杜邦线把板子的复位引脚和GND短接一下，再启动OpenOCD，它会在复位释放后的那一瞬间抓住芯片。

5.2 自动化工作流：一键编译并烧录

既然已经在WSL的终端环境里了，不做点自动化就浪费了。我在我的模拟项目X里，并不直接敲烧录命令，而是写了一个Makefile目标：

flash: arm-none-eabi-objcopy -O binary build/project.elf build/project.bin openocd -f interface/stlink.cfg -f target/stm32f4x.cfg -c "program build/project.bin 0x08000000 verify reset exit"

这样每次编译完代码，在WSL终端敲一个make flash，输出这个elf目标文件，然后自动转换成二进制，最后烧录进去。整个流程一气呵成，不需要切换任何窗口。这个工作流的核心价值在于，把产出固件和烧录固件这两个高频操作合并到一起，避免了人工处理中间产物带来的各种低级错误。

5.3 进阶：启动远程GDB调试

烧录只是开始，真正的开发效率提升在于调试。OpenOCD启动后，会默认在本地的3333端口开放GDB远程调试接口。你可以在另一个WSL终端窗口里，用arm-none-eabi-gdb连接上去：

arm-none-eabi-gdb build/project.elf (gdb) target remote localhost:3333 (gdb) monitor reset halt (gdb) load (gdb) continue

这几行命令的含义分别是：连接OpenOCD的调试端口、让目标芯片复位并暂停、将当前正在调试的ELF文件重新烧录进芯片、然后让程序继续运行。你可以在load之前设置断点，比如break main，这样就可以直接从main函数的第一行开始单步调试代码。

这一步做好的话，你在WSL里的开发效率直逼使用专业IDE的效果。LCD屏幕上的像素数据、串口打印出来的调试信息、还有在GDB命令行里单步执行的汇编指令，这些东西结合在一起，才是嵌入式开发完整的样子。

5.4 硬件复位与软件复位的一个具体心得

实际调试中，我踩过最不值得的坑，就是复位方式没选对。OpenOCD给芯片复位有两种方式：一种是通过调试器的RESET引脚，另一种是通过写入芯片内核寄存器实现的软复位。很多STM32开发板的板载调试器根本没有把RESET引脚连接到芯片的复位电路上，它们只连接了SWDIO和SWCLK两根线，外加地线和参考电压线。

如果你的板子是这种四线SWD连接方式，那么OpenOCD里涉及srst的配置基本都不需要去折腾，也不要去调整那部分的复位时序参数。对于这类板子，使用reset_config none或者在需要复位时直接调用reset halt，软复位就足够了。反之，扔掉这部分配置反而连接更稳定。

写在最后的一些个人体会

在WSL里把烧录问题解决之后，整个开发流会顺畅到不自然。我在这套环境上手之后，最大的感受就是终于不用在Windows和WSL之间做“精神分裂式”切换了。烧录器的驱动问题再怎么折腾，也就是装一次，之后一劳永逸。

最后再分享一个小技巧：如果你跟我一样，经常在不同型号的STM32之间切换开发，可以把常用的板卡配置文件整理好，放到一个专门放配置的文件夹里，用shell函数封装烧录命令。比如：

function flash_stm32() { local binfile=$1 local board_cfg=$2 openocd -f "interface/$board_cfg.cfg" -f "target/stm32f4x.cfg" -c "program $binfile verify reset exit" }

然后就可以敲一行命令烧录指定板卡上的指定固件，比如flash_stm32 build/app.bin stlink。这套小工具链搭建好之后，你会发现，自己再也回不去那个每次烧录都要手动捣鼓半天的时代了。