概述
开始开发前，先把教程用到的所有软件一次装齐。本教程的编译、烧录等命令全部在 WSL（Ubuntu）终端 中执行，因此环境搭建是第一优先级。
本页完成全部软件安装后，即可开始 STM32 CMake 工程创建。
WSL2 是 Windows 内置的 Linux 运行环境，本教程所有命令（git clone、编译、烧录）都在其中执行。
-
按下
Win键，输入PowerShell，右键 以管理员身份运行。 -
执行命令并回车：
wsl --install -d Ubuntu-22.04若提示找不到发行版，先执行
wsl --update再重试。 -
安装完成后重启电脑，开机自动进入 Ubuntu 终端，按提示设置用户名和密码（记住密码，后续 sudo 要用）。
-
更新软件源并验证：
sudo apt update cat /etc/os-release
安装完成后，打开 Ubuntu 终端（开始菜单搜索 Ubuntu）即可进入 WSL 环境。
WSL 目录小知识：Linux 里的
/mnt/c/就是 Windows 的 C 盘；WSL 内部文件在/home/你的名字/下。
先执行一次
sudo apt update，如果很慢或失败，说明默认软件源在国外，先按下面的"更换国内软件源"操作，再回来安装工具链。
📖 更换国内软件源教程（apt 慢/失败时执行，二选一）
① 清华源（推荐）：
# 备份原配置
sudo cp /etc/apt/sources.list /etc/apt/sources.list.bak
# 替换为清华镜像
sudo sed -i 's@//.*archive.ubuntu.com@//mirrors.tuna.tsinghua.edu.cn@g; s@//security.ubuntu.com@//mirrors.tuna.tsinghua.edu.cn@g' /etc/apt/sources.list
# 更新
sudo apt update
② 阿里源：
sudo cp /etc/apt/sources.list /etc/apt/sources.list.bak
sudo sed -i 's@//.*archive.ubuntu.com@//mirrors.aliyun.com@g; s@//security.ubuntu.com@//mirrors.aliyun.com@g' /etc/apt/sources.list
sudo apt update
换源后 sudo apt update 应快速完成，然后逐个安装下面 4 个工具链（每个都是一个独立复制框，安装一条、验证一条）：
1️⃣ 安装 Git（拉取代码）
sudo apt install -y git
git --version
2️⃣ 安装 ARM 交叉编译器（把 C 编译成 STM32 机器码）
sudo apt install -y gcc-arm-none-eabi
arm-none-eabi-gcc --version
3️⃣ 安装 CMake 与 Ninja（构建系统）
sudo apt install -y cmake ninja-build
cmake --version
ninja --version
4️⃣ 安装 OpenOCD（配合 ST-Link 烧录/调试）
sudo apt install -y openocd
openocd --version
版本要求：gcc-arm-none-eabi ≥ 10.3，cmake ≥ 3.22，ninja ≥ 1.10，openocd ≥ 0.12。四条命令的版本输出都正常，说明工具链安装完成。
顺序很重要：WSL 已在步骤①安装完成。VSCode 的插件分两类——UI 插件装 Windows 端（中文、WSL 扩展），开发插件要装到 WSL 端（C/C++、CMake Tools 等，提供编译和智能提示）。所以必须先连接 WSL，再装开发插件。
-
下载安装 VSCode：https://code.visualstudio.com/（Windows 版，默认安装）。
-
打开 VSCode，点击左侧"扩展"图标，先安装以下 2 个 Windows 端插件：
插件名 发布者 安装端 作用 Chinese (Simplified) Language Pack Microsoft Windows 端 简体中文界面（装完重启 VSCode 生效） WSL Microsoft Windows 端 连接 WSL 的桥梁，必装 
-
点击左下角绿色 远程窗口 按钮 → Connect to WSL，连接成功后左下角显示
WSL: Ubuntu（已进入 WSL 环境）。
-
在 WSL 连接状态下，继续安装以下开发插件（扩展面板会显示"在 WSL: Ubuntu 中安装"，逐个点击安装即可，插件会装到 WSL 端）：
插件名 发布者 安装端 作用 C/C++ Microsoft WSL 端 代码高亮、智能提示（读取 compile_commands.json） CMake Tools Microsoft WSL 端 图形化点按钮编译 Cortex-Debug marus25 WSL 端 STM32 在线调试（配合 OpenOCD + ST-Link）
配置完成（一次性），验证方式：左下角显示 WSL: Ubuntu；扩展面板中 C/C++、CMake Tools 显示已安装到 WSL: Ubuntu。
小提示：
sudo apt update慢或失败时，先按步骤②的换源教程操作再安装工具链。
访问 ST 官网下载页：https://www.st.com/en/development-tools/stm32cubemx.html
-
点击 Download（没有 ST 账号先免费注册一个），下载 Windows 版本（
en.stm32cubemx-win64-v6.x.x.zip）。 -
解压后双击安装程序，一路默认安装。
-
首次启动后安装 F1 固件包：菜单 Help → Manage embedded software packages → 找到 STM32Cube MCU Package for STM32F1 Series → 点 Install（版本 V1.8.7），等待变绿完成。
九章板的 .ioc 文件基于 CubeMX 6.18.0 与 FW_F1 V1.8.7 生成，建议使用相同或更高版本。
Seahi-Serial 是一款 Windows 软件，集串口助手与 WSL 串口/USB 映射于一体：既能查看调试日志、手动发送 MCP 指令，又能把 Windows 的 COM 口/USB 设备挂载进 WSL（解决 WSL2 无法直接访问串口的问题）。
直接下载安装：https://github.com/SeaHi-Mo/Seahi-Serial/releases（下载最新版 Windows 安装包 .exe，双击安装即可）。
使用说明：串口用法见各章节"串口手动测试"部分；调试串口波特率 1500000，AI 模组串口 115200；WSL 映射功能用于串口调试与 ST-Link 烧录。
常见问题与踩坑提示
🔧 wsl --install 提示找不到发行版
原因：WSL 内核/组件未更新
解决：先执行 wsl --update 再重试；或 wsl --install -d Ubuntu（默认最新版）
🔧 WSL 安装后没重启
原因：安装程序要求重启
解决：重启电脑后 Ubuntu 才会出现
🔧 打开 Ubuntu 终端提示未安装
原因：未完成安装流程
解决：重新执行 wsl --install -d Ubuntu-22.04 并重启
🔧 VSCode 左下角没有 WSL 选项 / 连接失败
原因：没装 WSL 扩展或 WSL 版本旧
解决：安装微软 WSL 扩展；确认 wsl --version 显示 WSL2；Win10 老版本需手动开启 WSL2 组件
🔧 sudo apt update 很慢或失败
原因：默认软件源在国外
解决：换国内镜像源（清华/阿里云），再执行安装命令
🔧 arm-none-eabi-gcc --version 显示 9.x
原因：Ubuntu 20.04 等老系统默认版本旧
解决：本教程用 Ubuntu 22.04（默认 10.3+）；老系统可装 xpack 版工具链
🔧 烧录时 ST-Link 识别不到
原因：WSL2 默认无法直接访问 Windows 的 USB 设备
解决：用本步骤⑤安装的 Seahi-Serial 把 ST-Link 映射进 WSL，即可在 WSL 内烧录（Cortex-Debug 图形化或 OpenOCD 命令行，见编译和下载工程）
安装完成后自检
在 WSL 终端执行 git --version && arm-none-eabi-gcc --version && cmake --version && ninja --version && openocd --version，五条命令均有版本输出即工具链就绪。VSCode 左下角显示 WSL: Ubuntu 即环境打通。