WSL 配置 STM32Cube 开发环境

环境：Windows + WSL Ubuntu
目标：在 WSL 里安装 STM32Cube 命令行工具链，并配合 VS Code 的 STM32Cube 扩展完成 CMake 工程编译

开头

这次配置 STM32Cube 开发环境时，我一开始以为 ST 官网下载的是 .deb 包。因为 WSL 是 Ubuntu，按直觉当然应该下载 Linux / Debian / Ubuntu 对应的安装包。

结果下载下来以后发现，它并不是一个普通的 .deb 文件，而是一个安装脚本，也就是 .sh 文件。

这点有点容易误导人。但实际安装并不难：给脚本执行权限，运行它，按提示装完，再到 VS Code 里安装 STM32Cube 相关扩展，就可以尝试编译 CMake 工程了。

需要安装什么

STM32 在 VS Code / CMake 里的开发环境，核心一般是这几块：

• STM32CubeCLT：ST 的命令行工具集，包含编译、调试、烧录相关工具
• STM32CubeMX：用于生成初始化代码和工程配置
• VS Code STM32Cube 扩展：在 VS Code 里识别和管理 STM32 工程
• CMake / Ninja：实际构建工具

在 WSL Ubuntu 里，先装基础依赖：

sudo apt update
sudo apt install -y cmake ninja-build make git

如果后面要处理 USB 烧录调试，可能还需要额外配置 udev 或 USB 透传。但只做编译的话，先不用把问题想太大。USB透传我推荐用WSL-dashboard，配置非常方便。

从 ST 官网下载安装包

去 ST 官网下载 STM32CubeCLT 的 Linux 版本。传送门

下载时可能会看到 Debian / Ubuntu 相关描述，所以容易以为拿到的是 .deb。但实际文件可能是一个 .sh 安装脚本，例如类似：

st-stm32cubeclt_1.21.0_27995_20260219_1804_amd64.deb_bundle.sh

文件名以实际下载为准。

把它放到 WSL 能访问的位置。建议复制到 WSL 自己的目录里，例如：

mkdir -p ~/Downloads/stm32
cd ~/Downloads/stm32

如果文件在 Windows 下载目录，可以从 /mnt/c/Users/.../Downloads/ 复制过来。不过我喜欢在Windows打开资源管理器直接拖过去。

运行安装脚本

给脚本执行权限：

chmod +x ./st-stm32cubeclt_*.sh

然后运行：

sudo ./st-stm32cubeclt_*.sh

安装过程中按 ST 的提示走就行。

安装 VS Code 的 STM32Cube 扩展

VS Code用于STM32开发可以说是极为方便，是嵌入式开发不得不品鉴的一环😋。

WSL 里的命令行工具装好以后，打开 VS Code。

推荐用 Remote - WSL （VS Code左下角有个形如 > < 的图标，点击之后选择自己的WSL） 打开项目目录：

code .

然后在 VS Code 扩展里安装 ST 官方的 STM32Cube 相关扩展。装好后，扩展会识别 STM32Cube / CMake 工具链，并尝试接管工程配置、构建和调试入口。

这个拓展名字就叫STM32Cube，实际上是一个拓展包，里面大大小小我估计有十几个拓展，不用管，会自动装上的。

这里的关键是：VS Code 当前窗口要运行在 WSL 环境里，而不是普通 Windows 本地窗口。否则它可能找不到 WSL 里安装的工具链。

创建或打开 STM32 CMake 工程

如果用 STM32CubeMX 生成工程，工具链类型选择 CMake。

生成后，进入工程目录：

cd ~/git-projects/your_stm32_project

尝试配置和编译：

cmake -S . -B build -G Ninja
cmake --build build

如果 VS Code 的 STM32Cube 扩展已经识别工程，也可以直接用扩展提供的 Build 按钮或命令。VS Code的编译按钮在 Cmake拓展-生成 的旁边。

这次踩到的小点

1. 下载的不是 .deb

WSL 是 Ubuntu，所以一开始想到 .deb 很正常。但 ST 官网给的 Linux 安装包可能是 .sh。这种情况下不用 apt install ./xxx.deb，而是：

chmod +x xxx.sh
sudo ./xxx.sh

2. PATH 不一定自动配置好

安装成功不代表终端马上能找到 arm-none-eabi-gcc。如果命令找不到，先用 find /opt/st 找实际位置，再写 PATH。

3. 编译和烧录是两件事

在 WSL 里编译 STM32 CMake 工程相对直接。烧录和调试要看 ST-Link 是否能进 WSL。

如果要把 ST-Link 接给 WSL，通常需要 Windows 侧的 usbipd-win。不想折腾的话，也可以先 WSL 编译，Windows 侧烧录。

一个最小验证流程

装好后，可以按这个顺序检查：

cmake --version
ninja --version
arm-none-eabi-gcc --version

然后进入 STM32 CMake 工程：

cmake -S . -B build -G Ninja
cmake --build build

如果能生成固件文件，比如 .elf、.bin 或 .hex，说明编译链路基本通了。

小结

这套 STM32Cube on WSL 的配置路径可以压缩成几步：

1. 在 Ubuntu 里安装 CMake、Ninja、Git 等基础工具
2. 从 ST 官网下载 Linux 版 STM32CubeCLT
3. 如果下载下来是 .sh，就用 chmod +x 后运行安装脚本
4. 检查 arm-none-eabi-gcc、CMake、Ninja 是否可用
5. 在 VS Code 里安装 STM32Cube 扩展
6. 用 WSL 窗口打开 STM32 CMake 工程并尝试编译

这次最值得记住的是：不要被文件后缀骗到。Ubuntu 环境里不一定永远是 .deb，ST 给 .sh 安装脚本也很常见。能编译成功，就说明主链路已经跑通了。