01 - 环境配置

本章目标：从零开始搭建完整的 STM32F103C8T6 开发环境，确保您能够顺利编译、烧录和调试项目。

📋 目录

目标受众与前置知识
操作系统要求
硬件准备清单
软件依赖安装
USB 权限配置
环境验证
常见问题排查
附录：其他平台配置

🎯 目标受众与前置知识

目标受众

本教程专为 嵌入式开发初学者 设计，假设您：

从未接触过 STM32 开发
可能有一定的 C 语言编程经验
希望从零开始系统学习嵌入式开发

前置知识要求

在开始配置环境之前，请确保您具备以下基础知识：

必要条件

知识领域	具体要求
C 语言基础	变量、数据类型、控制流程、函数、指针基础
基本电子概念	了解电压、电流、GND、VCC 的基本含义
命令行操作	能够在终端中执行基本命令（cd、ls、mkdir 等）

有帮助但非必需

GCC/GDB 工具链的基本使用经验
Arduino 或其他开发板的使用经验
Linux 操作系统基础

💡 提示：如果您对 C 语言不太熟悉，建议先学习 C 语言入门教程。

💻 操作系统要求

平台	推荐程度	说明
Linux (Ubuntu/Debian)	⭐⭐⭐⭐⭐ 强烈推荐	原生支持，配置最简单，性能最佳
WSL (Windows Subsystem for Linux)	⭐⭐⭐⭐ 推荐	Windows 用户的最佳选择，需要额外配置 USB
Windows 原生	⭐⭐ 可用	需要额外安装工具，配置较复杂
macOS	⭐⭐ 可用	可通过 Homebrew 安装工具链

本教程重点

本教程将 重点讲解 Linux 和 WSL 平台 的配置过程。Windows 和 macOS 用户请参考附录：其他平台配置。

系统版本要求

平台	最低版本要求
Ubuntu	20.04 LTS 或更高
Debian	10 (Buster) 或更高
WSL	WSL 2 (推荐)
Windows	Windows 10 2004+ 或 Windows 11

🔧 硬件准备清单

在开始软件配置之前，请确保您已准备好以下硬件：

必需硬件

硬件	型号/规格	参考价格	说明
Blue Pill 开发板	STM32F103C8T6	¥10-20	核心开发板
ST-Link V2 调试器	ST-Link V2 (克隆版即可)	¥15-30	用于烧录和调试
USB 数据线	Micro USB 或 Mini USB	¥5-10	为开发板供电
跳线	母对母杜邦线 4 根	¥2-5	连接 ST-Link 和开发板

可选硬件

硬件	用途	说明
面包板	原型搭建	方便连接外设
LED 灯珠	基础实验	测试 GPIO 输出
USB 转 TTL 模块	串口调试	用于 printf 调试输出

硬件连接说明

ST-Link 与 Blue Pill 的连接方式：

ST-Link V2          Blue Pill (STM32F103C8T6)
┌─────────┐         ┌──────────────┐
│  SWDIO  │ ─────── │ SWDIO (PA13) │
│  SWCLK  │ ─────── │ SWCLK (PA14) │
│  GND    │ ─────── │ GND          │
│  3.3V   │ ─────── │ 3.3V (可选)  │
└─────────┘         └──────────────┘

⚠️ 注意：
请确保 ST-Link 的 3.3V 引脚仅在开发板未通过 USB 供电时连接
同时使用两个电源可能导致电流倒灌，损坏开发板

📦 软件依赖安装

安装概览

本节将安装以下软件组件：

组件	版本要求	用途
ARM GCC 工具链	arm-none-eabi-gcc	交叉编译
CMake	3.16+	构建系统
Make	任意版本	构建工具
OpenOCD	0.10.0+	烧录和调试
VSCode	最新版	代码编辑器
Cortex-Debug 扩展	最新版	VSCode 调试扩展

Linux (Ubuntu/Debian) 安装步骤

步骤 1：更新系统软件包

bash

# 更新软件包列表
sudo apt update

# 升级已安装的软件包（可选但推荐）
sudo apt upgrade -y

步骤 2：安装 ARM GCC 交叉编译工具链

bash

# 安装 ARM GCC 工具链
sudo apt install -y gcc-arm-none-eabi

# 验证安装
arm-none-eabi-gcc --version

预期输出：

arm-none-eabi-gcc (Ubuntu 10.3.0-1ubuntu1) 10.3.0
Copyright (C) 2020 Free Software Foundation, Inc.
...

步骤 3：安装 CMake 构建系统

bash

# 安装 CMake（Ubuntu 20.04+ 默认版本 >= 3.16）
sudo apt install -y cmake

# 验证安装
cmake --version

预期输出：

cmake version 3.16.3
CMake suite maintained and supported by Kitware (kitware.com/CMake).

💡 提示：如果您的系统 CMake 版本低于 3.16，请参考安装最新版 CMake 小节。

步骤 4：安装 Make 构建工具

bash

# 安装 make
sudo apt install -y make

# 验证安装
make --version

步骤 5：安装 OpenOCD 调试工具

bash

# 安装 OpenOCD
sudo apt install -y openocd

# 验证安装
openocd --version

预期输出：

Open On-Chip Debugger 0.10.0
...

步骤 6：安装其他依赖工具

bash

# 安装 git（版本控制）
sudo apt install -y git

# 安装 build-essential（包含编译工具）
sudo apt install -y build-essential

步骤 7：安装 Visual Studio Code

方法一：通过 Snap 安装（推荐）

bash

# 安装 VSCode
sudo snap install code --classic

方法二：通过 apt 安装

bash

# 添加 Microsoft GPG 密钥
wget -qO- https://packages.microsoft.com/keys/microsoft.asc | gpg --dearmor > packages.microsoft.gpg
sudo install -D -o root -g root -m 644 packages.microsoft.gpg /etc/apt/keyrings/packages.microsoft.gpg

# 添加 VSCode 软件源
sudo sh -c 'echo "deb [arch=amd64,arm64,armhf signed-by=/etc/apt/keyrings/packages.microsoft.gpg] https://packages.microsoft.com/repos/code stable main" > /etc/apt/sources.list.d/vscode.list'

# 安装 VSCode
sudo apt update
sudo apt install -y code

步骤 8：安装 VSCode 扩展

bash

# 安装 Cortex-Debug 扩展（用于 ARM 调试）
code --install-extension marus25.cortex-debug

# 安装 C/C++ 扩展（推荐）
code --install-extension ms-vscode.cpptools

# 安装 CMake Tools 扩展（推荐）
code --install-extension ms-vscode.cmake-tools

WSL (Windows Subsystem for Linux) 安装步骤

WSL 用户需要先完成 Linux 部分的安装，然后额外配置 USB 设备访问。

步骤 1：安装 WSL 2

在 Windows PowerShell（管理员）中执行：

powershell

# 启用 WSL 功能
wsl --install

# 或者指定安装 Ubuntu
wsl --install -d Ubuntu-22.04

安装完成后，重启 Windows 并完成 Ubuntu 的初始化设置。

步骤 2：在 WSL 中安装软件依赖

进入 WSL 终端后，执行与 Linux 安装步骤相同的命令。

bash

# 在 WSL 终端中执行
sudo apt update
sudo apt install -y gcc-arm-none-eabi cmake make openocd git build-essential

步骤 3：安装 VSCode（Windows 端）

在 Windows 系统中安装 VSCode：

访问 VSCode 官网
下载 Windows 版本安装包
运行安装程序，选择默认选项

步骤 4：安装 VSCode 扩展

在 Windows 的 VSCode 中安装以下扩展：

powershell

# 在 Windows PowerShell 中执行
code --install-extension marus25.cortex-debug
code --install-extension ms-vscode.cpptools
code --install-extension ms-vscode.cmake-tools

步骤 5：安装 WSL 扩展（连接 WSL）

powershell

# 安装 WSL 扩展，使 VSCode 能够访问 WSL 文件系统
code --install-extension ms-vscode-remote.remote-wsl

🔌 USB 权限配置

Linux 原生系统 USB 权限配置

Linux 系统默认限制普通用户访问 USB 设备，需要配置 udev 规则。

方法一：创建 udev 规则（推荐）

bash

# 创建 ST-Link udev 规则文件
sudo tee /etc/udev/rules.d/49-stlinkv2.rules > /dev/null << 'EOF'
# ST-Link V2
SUBSYSTEMS=="usb", ATTRS{idVendor}=="0483", ATTRS{idProduct}=="3748", MODE:="0666"
# ST-Link V2-1
SUBSYSTEMS=="usb", ATTRS{idVendor}=="0483", ATTRS{idProduct}=="374b", MODE:="0666"
# ST-Link V3
SUBSYSTEMS=="usb", ATTRS{idVendor}=="0483", ATTRS{idProduct}=="374f", MODE:="0666"
SUBSYSTEMS=="usb", ATTRS{idVendor}=="0483", ATTRS{idProduct}=="3753", MODE:="0666"
EOF

# 重新加载 udev 规则
sudo udevadm control --reload-rules

# 触发规则生效
sudo udevadm trigger

# 提示用户重新插拔设备
echo "请重新插拔 ST-Link 设备以使权限生效"

方法二：临时权限设置（每次重启后需重新执行）

bash

# 查找 ST-Link 设备
lsusb | grep -i ST-LINK

# 设置设备权限（需要每次重新插拔后执行）
sudo chmod 666 /dev/bus/usb/$(lsusb | grep -i "ST-LINK" | awk '{print $2}')/$(lsusb | grep -i "ST-LINK" | awk '{print $4}' | sed 's/://')

验证 USB 权限

bash

# 连接 ST-Link 后，检查设备是否被识别
lsusb | grep -i ST-LINK

# 预期输出类似：
# Bus 001 Device 005: ID 0483:3748 STMicroelectronics ST-LINK/V2

WSL USB 权限配置

WSL 无法直接访问 Windows 的 USB 设备，需要使用 usbipd-win 工具进行 USB 设备转发。

步骤 1：在 Windows 端安装 usbipd-win

在 Windows PowerShell（管理员）中执行：

powershell

# 使用 winget 安装（Windows 11 自带）
winget install --interactive --exact dorssel.usbipd-win

# 或使用 Chocolatey 安装
# choco install usbipd

步骤 2：在 WSL 中安装 USB 支持

bash

# 在 WSL 终端中执行
sudo apt install -y linux-tools-generic hwdata

# 创建 usbip 命令链接
sudo update-alternatives --install /usr/local/bin/usbip usbip /usr/lib/linux-tools/*-generic/usbip 20

步骤 3：附加 USB 设备到 WSL

在 Windows PowerShell（管理员）中执行：

powershell

# 列出所有 USB 设备
usbipd wsl list

# 找到 ST-Link 设备的 BUSID（例如：1-2）
# 附加设备到 WSL
usbipd wsl attach --busid <BUSID>

# 例如：
# usbipd wsl attach --busid 1-2

步骤 4：在 WSL 中验证设备

bash

# 在 WSL 终端中检查设备
lsusb | grep -i ST-LINK

# 预期输出：
# Bus 001 Device 005: ID 0483:3748 STMicroelectronics ST-LINK/V2

步骤 5：设置 WSL USB 权限

bash

# 创建权限设置脚本（参考项目中的 chmod_usb.sh）
cat > ~/chmod_usb.sh << 'EOF'
#!/bin/bash
BUSDEV=$(lsusb | grep -i ST-LINK | awk '{print "/dev/bus/usb/"$2"/"substr($4,1,3)}')

if [ -z "$BUSDEV" ]; then
    echo "没有找到 ST-Link 设备，请先在 Windows 侧执行 usbipd attach"
    exit 1
fi

echo "找到 ST-Link 设备: $BUSDEV"
sudo chmod 666 $BUSDEV
echo "权限已设置为 666"
EOF

# 添加执行权限
chmod +x ~/chmod_usb.sh

# 每次附加 USB 后执行此脚本
~/chmod_usb.sh

⚠️ 注意：WSL 中每次重新附加 USB 设备后，都需要重新设置权限。

✅ 环境验证

完成所有安装后，请按照以下步骤验证环境配置是否正确。

验证清单

1. 验证 ARM GCC 工具链

bash

# 检查编译器版本
arm-none-eabi-gcc --version

# 预期输出包含版本号，例如：
# arm-none-eabi-gcc (Ubuntu 10.3.0-1ubuntu1) 10.3.0

2. 验证 CMake 版本

bash

# 检查 CMake 版本（需要 >= 3.16）
cmake --version

# 预期输出：
# cmake version 3.16.3（或更高版本）

3. 验证 Make 工具

bash

# 检查 make
make --version

# 预期输出包含版本号

4. 验证 OpenOCD

bash

# 检查 OpenOCD
openocd --version

# 预期输出：
# Open On-Chip Debugger 0.10.0（或更高版本）

5. 验证 VSCode 扩展

bash

# 列出已安装的 VSCode 扩展
code --list-extensions | grep -E "cortex-debug|cpptools|cmake-tools"

# 预期输出：
# marus25.cortex-debug
# ms-vscode.cpptools
# ms-vscode.cmake-tools

6. 验证 USB 设备识别

bash

# 连接 ST-Link 后检查
lsusb | grep -i ST-LINK

# 预期输出：
# Bus 001 Device XXX: ID 0483:3748 STMicroelectronics ST-LINK/V2

编译验证

使用项目模板进行编译测试：

bash

# 克隆项目（如果尚未克隆）
git clone <your-repo-url> ST-Forge
cd ST-Forge

# 进入模板项目目录
cd project/0_template

# 创建构建目录
mkdir -p build
cd build

# 配置项目
cmake ..

# 编译项目
make

# 预期输出包含：
# [100%] Built target STM32F1.elf
# Generating STM32F1.bin

如果编译成功，说明 ARM GCC 工具链和 CMake 配置正确。

烧录验证（需要连接硬件）

bash

# 在 build 目录中执行
make flash

# 预期输出包含：
# Open On-Chip Debugger 0.10.0
# ...
# target halted due to debug-request
# ...
# ** Programming Finished **

如果烧录成功，说明 OpenOCD 和 USB 权限配置正确。

🔧 常见问题排查

问题 1：arm-none-eabi-gcc 命令未找到

症状：

bash: arm-none-eabi-gcc: command not found

解决方案：

bash

# 检查是否已安装
dpkg -l | grep arm-none-eabi

# 如果未安装，执行安装
sudo apt install -y gcc-arm-none-eabi

# 如果已安装但找不到，检查 PATH
echo $PATH
# 应包含 /usr/bin

# 手动添加到 PATH（如果需要）
export PATH=$PATH:/usr/bin

问题 2：CMake 版本过低

症状：

CMake Error at CMakeLists.txt:1 (cmake_minimum_required):
  CMake 3.16 or higher is required.  You are running version 3.10.2

解决方案：

bash

# 方法一：使用 Kitware 官方源安装最新版
wget -O - https://apt.kitware.com/keys/kitware-archive-latest.asc 2>/dev/null | gpg --dearmor - | sudo tee /usr/share/keyrings/kitware-archive-keyring.gpg >/dev/null
sudo apt update
sudo apt install -y kitware-archive-keyring
sudo rm /usr/share/keyrings/kitware-archive-keyring.gpg
sudo apt update
sudo apt install -y cmake

# 方法二：使用 pip 安装
pip install cmake --upgrade

# 方法三：使用 snap 安装
sudo snap install cmake --classic

问题 3：OpenOCD 找不到 ST-Link

症状：

Error: libusb_open() failed with LIBUSB_ERROR_ACCESS
Error: no device found

解决方案：

bash

# 检查 USB 设备
lsusb | grep -i ST-LINK

# 如果设备存在但无法访问，配置 udev 规则
# 参考 [USB 权限配置](#linux-原生系统-usb-权限配置) 章节

# 重新加载规则后重新插拔设备
sudo udevadm control --reload-rules
sudo udevadm trigger

问题 4：WSL 无法访问 USB 设备

症状：

lsusb: cannot open /dev/bus/usb/001/001, Permission denied

解决方案：

bash

# 确保在 Windows 端已附加设备
# 在 Windows PowerShell（管理员）中：
usbipd wsl list
usbipd wsl attach --busid <BUSID>

# 在 WSL 中设置权限
~/chmod_usb.sh

# 或手动设置
sudo chmod 666 /dev/bus/usb/$(lsusb | grep -i "ST-LINK" | awk '{print $2}')/$(lsusb | grep -i "ST-LINK" | awk '{print $4}' | sed 's/:/''/')

问题 5：编译时找不到头文件

症状：

fatal error: stm32f1xx_hal.h: No such file or directory

解决方案：

bash

# 确保已克隆 third_party 子模块
cd ST-Forge
git submodule update --init --recursive

# 检查 HAL 库是否存在
ls third_party/STM32CubeF1/Drivers/STM32F1xx_HAL_Driver/Inc/

问题 6：VSCode 无法调试

症状：

调试按钮灰色
无法启动调试会话

解决方案：

确保已安装 Cortex-Debug 扩展
检查 launch.json 配置是否正确
确保 OpenOCD 正在运行

bash

# 验证扩展安装
code --list-extensions | grep cortex-debug

# 如果未安装
code --install-extension marus25.cortex-debug

📚 附录：其他平台配置

Windows 原生系统

安装 ARM GCC 工具链

访问 ARM Developer 网站
下载 Windows 版本的安装包
运行安装程序，选择默认选项
将安装路径添加到系统 PATH（例如：C:\Program Files (x86)\GNU Tools Arm Embedded\9 2019-q4-major\bin）

安装 CMake

访问 CMake 官网
下载 Windows 安装包
安装时选择 "Add CMake to system PATH"

安装 OpenOCD

访问 OpenOCD 官网
下载 Windows 版本
解压到 C:\openocd
添加 C:\openocd\bin 到系统 PATH

安装 ST-Link 驱动

访问 ST 官网
下载 ST-Link 驱动
安装驱动程序

macOS 系统

使用 Homebrew 安装

bash

# 安装 Homebrew（如果尚未安装）
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 安装 ARM GCC
brew install --cask gcc-arm-embedded

# 安装 CMake
brew install cmake

# 安装 OpenOCD
brew install openocd

# 安装 make
brew install make

验证安装

bash

# 验证 ARM GCC
arm-none-eabi-gcc --version

# 验证 CMake
cmake --version

# 验证 OpenOCD
openocd --version

📝 安装命令汇总

Linux (Ubuntu/Debian) 一键安装

bash

# 完整安装脚本
sudo apt update && \
sudo apt install -y gcc-arm-none-eabi cmake make openocd git build-essential && \
code --install-extension marus25.cortex-debug && \
code --install-extension ms-vscode.cpptools && \
code --install-extension ms-vscode.cmake-tools && \
sudo tee /etc/udev/rules.d/49-stlinkv2.rules > /dev/null << 'EOF'
SUBSYSTEMS=="usb", ATTRS{idVendor}=="0483", ATTRS{idProduct}=="3748", MODE:="0666"
SUBSYSTEMS=="usb", ATTRS{idVendor}=="0483", ATTRS{idProduct}=="374b", MODE:="0666"
SUBSYSTEMS=="usb", ATTRS{idVendor}=="0483", ATTRS{idProduct}=="374f", MODE:="0666"
SUBSYSTEMS=="usb", ATTRS{idVendor}=="0483", ATTRS{idProduct}=="3753", MODE:="0666"
EOF
sudo udevadm control --reload-rules && \
sudo udevadm trigger && \
echo "环境配置完成！请重新插拔 ST-Link 设备。"

WSL 一键安装

bash

# WSL 内部安装脚本
sudo apt update && \
sudo apt install -y gcc-arm-none-eabi cmake make openocd git build-essential linux-tools-generic hwdata && \
sudo update-alternatives --install /usr/local/bin/usbip usbip /usr/lib/linux-tools/*-generic/usbip 20 && \
cat > ~/chmod_usb.sh << 'EOF'
#!/bin/bash
BUSDEV=$(lsusb | grep -i ST-LINK | awk '{print "/dev/bus/usb/"$2"/"substr($4,1,3)}')
if [ -z "$BUSDEV" ]; then
    echo "没有找到 ST-Link 设备，请先在 Windows 侧执行 usbipd attach"
    exit 1
fi
echo "找到 ST-Link 设备: $BUSDEV"
sudo chmod 666 $BUSDEV
echo "权限已设置为 666"
EOF
chmod +x ~/chmod_usb.sh && \
echo "WSL 环境配置完成！请在 Windows 端安装 usbipd-win 并附加 USB 设备。"

🎉 下一步

恭喜您完成环境配置！接下来建议：

验证环境：按照环境验证章节确认所有工具正常工作
了解项目结构：继续阅读 02_project_structure
编译第一个项目：尝试编译模板项目
烧录测试：将固件烧录到开发板

📖 参考资料

上一章：教程索引 | 下一章：项目结构

01 - 环境配置 ​

📋 目录 ​

🎯 目标受众与前置知识 ​

目标受众 ​

前置知识要求 ​

必要条件 ​

有帮助但非必需 ​

💻 操作系统要求 ​

推荐平台 ​

本教程重点 ​

系统版本要求 ​

🔧 硬件准备清单 ​

必需硬件 ​

可选硬件 ​

硬件连接说明 ​

📦 软件依赖安装 ​

安装概览 ​

Linux (Ubuntu/Debian) 安装步骤 ​

步骤 1：更新系统软件包 ​

步骤 2：安装 ARM GCC 交叉编译工具链 ​

步骤 3：安装 CMake 构建系统 ​

步骤 4：安装 Make 构建工具 ​

步骤 5：安装 OpenOCD 调试工具 ​

步骤 6：安装其他依赖工具 ​

步骤 7：安装 Visual Studio Code ​

步骤 8：安装 VSCode 扩展 ​

WSL (Windows Subsystem for Linux) 安装步骤 ​

步骤 1：安装 WSL 2 ​

步骤 2：在 WSL 中安装软件依赖 ​

步骤 3：安装 VSCode（Windows 端） ​

步骤 4：安装 VSCode 扩展 ​

步骤 5：安装 WSL 扩展（连接 WSL） ​

🔌 USB 权限配置 ​

Linux 原生系统 USB 权限配置 ​

方法一：创建 udev 规则（推荐） ​

方法二：临时权限设置（每次重启后需重新执行） ​

验证 USB 权限 ​

WSL USB 权限配置 ​

步骤 1：在 Windows 端安装 usbipd-win ​

步骤 2：在 WSL 中安装 USB 支持 ​

步骤 3：附加 USB 设备到 WSL ​

步骤 4：在 WSL 中验证设备 ​

步骤 5：设置 WSL USB 权限 ​

✅ 环境验证 ​

验证清单 ​

1. 验证 ARM GCC 工具链 ​

2. 验证 CMake 版本 ​

3. 验证 Make 工具 ​

4. 验证 OpenOCD ​

5. 验证 VSCode 扩展 ​

6. 验证 USB 设备识别 ​

编译验证 ​

烧录验证（需要连接硬件） ​

🔧 常见问题排查 ​

问题 1：arm-none-eabi-gcc 命令未找到 ​

问题 2：CMake 版本过低 ​

问题 3：OpenOCD 找不到 ST-Link ​

问题 4：WSL 无法访问 USB 设备 ​

问题 5：编译时找不到头文件 ​

问题 6：VSCode 无法调试 ​

📚 附录：其他平台配置 ​

Windows 原生系统 ​

安装 ARM GCC 工具链 ​

安装 CMake ​

安装 OpenOCD ​

安装 ST-Link 驱动 ​

macOS 系统 ​

使用 Homebrew 安装 ​

验证安装 ​

📝 安装命令汇总 ​

Linux (Ubuntu/Debian) 一键安装 ​

WSL 一键安装 ​

🎉 下一步 ​

📖 参考资料 ​

01 - 环境配置

📋 目录

🎯 目标受众与前置知识

目标受众

前置知识要求

必要条件

有帮助但非必需

💻 操作系统要求

推荐平台

本教程重点

系统版本要求

🔧 硬件准备清单

必需硬件

可选硬件

硬件连接说明

📦 软件依赖安装

安装概览

Linux (Ubuntu/Debian) 安装步骤

步骤 1：更新系统软件包

步骤 2：安装 ARM GCC 交叉编译工具链

步骤 3：安装 CMake 构建系统

步骤 4：安装 Make 构建工具

步骤 5：安装 OpenOCD 调试工具

步骤 6：安装其他依赖工具

步骤 7：安装 Visual Studio Code

步骤 8：安装 VSCode 扩展

WSL (Windows Subsystem for Linux) 安装步骤

步骤 1：安装 WSL 2

步骤 2：在 WSL 中安装软件依赖

步骤 3：安装 VSCode（Windows 端）

步骤 4：安装 VSCode 扩展

步骤 5：安装 WSL 扩展（连接 WSL）

🔌 USB 权限配置

Linux 原生系统 USB 权限配置

方法一：创建 udev 规则（推荐）

方法二：临时权限设置（每次重启后需重新执行）

验证 USB 权限

WSL USB 权限配置

步骤 1：在 Windows 端安装 usbipd-win

步骤 2：在 WSL 中安装 USB 支持

步骤 3：附加 USB 设备到 WSL

步骤 4：在 WSL 中验证设备

步骤 5：设置 WSL USB 权限

✅ 环境验证

验证清单

1. 验证 ARM GCC 工具链

2. 验证 CMake 版本

3. 验证 Make 工具

4. 验证 OpenOCD

5. 验证 VSCode 扩展

6. 验证 USB 设备识别

编译验证

烧录验证（需要连接硬件）

🔧 常见问题排查

问题 1：arm-none-eabi-gcc 命令未找到

问题 2：CMake 版本过低

问题 3：OpenOCD 找不到 ST-Link

问题 4：WSL 无法访问 USB 设备

问题 5：编译时找不到头文件

问题 6：VSCode 无法调试

📚 附录：其他平台配置

Windows 原生系统

安装 ARM GCC 工具链

安装 CMake

安装 OpenOCD

安装 ST-Link 驱动

macOS 系统

使用 Homebrew 安装

验证安装

📝 安装命令汇总

Linux (Ubuntu/Debian) 一键安装

WSL 一键安装

🎉 下一步

📖 参考资料