01 - 环境配置（Windows 原生）

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

---

目录

• 目标受众与前置知识
• 操作系统要求
• 硬件准备清单
• 软件安装
• ST-Link 驱动安装
• VSCode 扩展安装
• 环境验证
• 常见问题排查

---

目标受众与前置知识

目标受众

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

• 从未接触过 STM32 开发
• 可能有一定的 C 语言编程经验
• 希望在 Windows 原生环境下进行嵌入式开发

前置知识要求

知识领域	具体要求
C 语言基础	变量、数据类型、控制流程、函数、指针基础
基本电子概念	了解电压、电流、GND、VCC 的基本含义
Windows 基本操作	能够使用文件资源管理器、命令提示符或 PowerShell

有帮助但非必需

• GCC/GDB 工具链的基本使用经验
• Arduino 或其他开发板的使用经验
• 命令行操作经验

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

---

操作系统要求

推荐平台

平台	推荐程度	说明
Windows 10/11（原生）	推荐	本教程重点讲解
WSL 2	替代方案	参见 WSL 环境配置教程
Linux (Ubuntu/Debian)	替代方案	参见 WSL 教程中的 Linux 部分
macOS	替代方案	可通过 Homebrew 安装工具链

系统版本要求

要求	最低版本
Windows 10	2004（20H2）或更高
Windows 11	任意版本
可用磁盘空间	约 3 GB（工具链 + 项目依赖）

---

硬件准备清单

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

必需硬件

硬件	型号/规格	参考价格	说明
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 工具链	交叉编译（含 Make）	官网下载安装
CMake (3.16+)	构建系统	官网下载安装
OpenOCD	烧录和调试	xPack 预编译二进制
Git	版本控制	官网下载安装
VSCode	代码编辑器	官网下载安装
ST-Link 驱动	USB 设备驱动	ST 官网下载

推荐安装目录

为避免路径中的空格导致问题，建议将工具统一安装到无空格路径：

C:\Tools\
├── gcc-arm\          # ARM GCC 工具链（含 make）
└── openocd\          # OpenOCD

重要：避免安装到 C:\Program Files\ 等包含空格的路径，否则某些工具可能出现兼容性问题。

---

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

ARM GCC 工具链是编译 STM32 代码的核心工具，包含编译器（arm-none-eabi-gcc）、调试器（arm-none-eabi-gdb）、以及构建工具（make）等。

下载

1. 访问 ARM 官方下载页面：ARM GNU Toolchain Downloads
2. 找到最新版本的 arm-gnu-toolchain（选择 ...-mingw-w64-i686-arm-none-eabi.exe 或 .zip）
3. 下载 Windows (mingw-w64) 版本的安装程序

安装

使用安装程序（推荐）：

1. 运行下载的 .exe 安装程序
2. 安装路径建议改为：C:\Tools\gcc-arm（避免空格）
3. 勾选 "Add path to environment variable"（添加到环境变量）
4. 完成安装

手动安装（.zip 版本）：

1. 解压到 C:\Tools\gcc-arm
2. 将 C:\Tools\gcc-arm\bin 添加到系统 PATH（见下方说明）

验证安装

打开新的命令提示符或 PowerShell 窗口：

arm-none-eabi-gcc --version

预期输出：

arm-none-eabi-gcc (Arm GNU Toolchain 13.2.Rel1 (Build arm-13-7.1)) 13.2.1 20231009
Copyright (C) 2023 Free Software Foundation, Inc.
...

提示：ARM GCC 工具链的 Windows (mingw-w64) 版本已自带 make，无需单独安装。

---

步骤 2：安装 CMake 构建系统

CMake 用于生成项目的构建文件。

下载与安装

1. 访问 CMake 官网下载页
2. 下载 Windows x64 Installer (.msi)
3. 运行安装程序
4. 安装时务必勾选 "Add CMake to the system PATH for all users"

验证安装

cmake --version

预期输出：

cmake version 3.28.1

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

确保版本号 >= 3.16。如果版本过低，请重新下载最新版。

---

步骤 3：安装 OpenOCD

OpenOCD 是用于通过 ST-Link 烧录和调试 STM32 的工具。

下载

1. 访问 xPack OpenOCD Releases
2. 下载最新版本的 Windows x64 压缩包：xpack-openocd-0.12.0-?-win32-x64.zip

安装

1. 解压到 C:\Tools\openocd
2. 确保 C:\Tools\openocd\bin\openocd.exe 存在
3. 将 C:\Tools\openocd\bin 添加到系统 PATH

验证安装

openocd --version

预期输出：

xPack Open On-Chip Debugger 0.12.0-... (2024-??-??-??)
...

说明：xPack 版本的 OpenOCD 是社区维护的预编译版本，功能与官方 OpenOCD 完全一致，只是版本号带有 xPack 后缀。

---

步骤 4：安装 Git

Git 用于克隆项目仓库和管理代码版本。

下载与安装

1. 访问 Git for Windows
2. 下载并运行安装程序
3. 安装选项建议保持默认
4. 确保勾选 "Git from the command line and also from 3rd-party software"

验证安装

git --version

预期输出：

git version 2.43.0.windows.1

---

步骤 5：安装 Visual Studio Code

VSCode 是本教程推荐的代码编辑器和调试 IDE。

下载与安装

1. 访问 VSCode 官网
2. 下载 Windows 版本安装包
3. 运行安装程序
4. 建议勾选以下选项：
   • 添加"通过 Code 打开"操作到 Windows 资源管理器文件上下文菜单
   • 添加"通过 Code 打开"操作到 Windows 资源管理器目录上下文菜单
   • 将 Code 注册为支持的文件类型的编辑器
   • 添加到 PATH

验证安装

code --version

预期输出：显示 VSCode 版本号。

---

配置系统 PATH 环境变量

如果某些工具安装时未自动添加到 PATH，需要手动配置。

手动添加 PATH 的步骤

1. 按 Win + R，输入 sysdm.cpl，回车
2. 点击 "高级" 选项卡
3. 点击 "环境变量" 按钮
4. 在 "系统变量" 区域，找到并选中 Path，点击 "编辑"
5. 点击 "新建"，添加以下路径（根据实际安装位置调整）：
   • C:\Tools\gcc-arm\bin
   • C:\Tools\openocd\bin
6. 点击 "确定" 保存
7. 关闭并重新打开所有命令行窗口（PATH 更改需要新终端才生效）

验证 PATH 配置

打开新的命令提示符，运行：

where arm-none-eabi-gcc
where openocd
where make
where cmake

说明：make 已包含在 ARM GCC 工具链中，其路径与 arm-none-eabi-gcc 相同。

每条命令都应输出对应的可执行文件路径。

重要：每次修改 PATH 后，必须重新打开终端窗口才能生效。已打开的 VSCode 也需要重启。

---

ST-Link 驱动安装

提示：如果您之前已经使用过 ST-Link（如在 Keil、STM32CubeIDE 等开发环境中），驱动通常已经配置完成，无需重复安装。可以直接跳到 环境验证 确认设备是否正常识别。

在 Windows 上使用 ST-Link 调试器，需要安装 ST 官方 USB 驱动。

步骤 1：下载驱动

1. 访问 ST 官方驱动下载页：STSW-LINK009
2. 可能需要注册/登录 ST 账号
3. 下载驱动压缩包

步骤 2：安装驱动

1. 解压下载的压缩包
2. 根据您的系统运行对应的安装程序：
   • 64 位系统（大多数现代电脑）：运行 dpinst_amd64.exe
   • 32 位系统：运行 dpinst_x86.exe
3. 按照安装向导完成驱动安装

步骤 3：验证驱动

1. 通过 USB 连接 ST-Link 调试器到电脑
2. 按 Win + X，选择 "设备管理器"
3. 在 "通用串行总线设备" 下查找：
   • "STMicroelectronics STLink dongle"（官方 ST-Link）
   • 或类似名称的设备
4. 确认设备图标没有警告标志（黄色感叹号）

设备管理器
└── 通用串行总线设备
    └── STMicroelectronics STLink dongle  ✓ 正常

克隆版 ST-Link 的驱动处理

部分 ST-Link 克隆版使用不同的 USB VID/PID，Windows 无法通过 STSW-LINK009 识别。此时需要使用 Zadig 工具替换驱动：

1. 下载 Zadig
2. 运行 Zadig，在菜单中选择 Options → List All Devices
3. 在下拉列表中找到 ST-Link 相关设备
4. 将驱动替换为 WinUSB
5. 点击 Replace Driver 或 Install Driver
6. 重新插拔 ST-Link

注意：使用 Zadig 替换驱动后，ST-Link 将不再被 ST 官方工具（如 STM32CubeProgrammer）识别。如果需要恢复，需要通过 Zadig 将驱动改回 ST 官方驱动。

---

VSCode 扩展安装

必需扩展

安装以下 VSCode 扩展用于 ARM 开发和调试：

方法一：命令行安装

code --install-extension marus25.cortex-debug
code --install-extension ms-vscode.cpptools
code --install-extension ms-vscode.cmake-tools

方法二：VSCode 内安装

1. 打开 VSCode
2. 按 Ctrl + Shift + X 打开扩展面板
3. 搜索并安装以下扩展：

扩展名称	扩展 ID	用途
Cortex-Debug	marus25.cortex-debug	ARM Cortex-M 调试支持
C/C++	ms-vscode.cpptools	C/C++ 语言支持
CMake Tools	ms-vscode.cmake-tools	CMake 构建集成

Cortex-Debug 路径配置

在 Windows 上，Cortex-Debug 需要找到 arm-none-eabi-gdb 和 openocd。

首选方案（推荐）：将 ARM GCC 和 OpenOCD 的 bin 目录添加到系统 PATH（参见配置系统 PATH 环境变量）。Cortex-Debug 会自动在 PATH 中查找所需工具。

备用方案：如果 PATH 方式不生效，可以在 VSCode 的 settings.json 中手动指定路径：

1. 在 VSCode 中按 Ctrl + Shift + P
2. 输入 "Preferences: Open Settings (JSON)"
3. 添加以下配置（路径根据实际安装位置调整）：

{
    "cortex-debug.armToolchainPath": "C:/Tools/gcc-arm/bin",
    "cortex-debug.openOCDPath": "C:/Tools/openocd/bin/openocd.exe"
}

注意：路径中的反斜杠需要使用正斜杠（/）或双反斜杠（\\）。

---

环境验证

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

验证清单

1. 验证 ARM GCC 工具链

arm-none-eabi-gcc --version
arm-none-eabi-gdb --version

两个命令都应输出版本号信息。

2. 验证 CMake

cmake --version

确认版本 >= 3.16。

3. 验证 Make（已包含在 ARM GCC 中）

make --version

说明：make 随 ARM GCC 工具链一起安装，无需单独配置。

4. 验证 OpenOCD

openocd --version

5. 验证 Git

git --version

6. 验证 VSCode 扩展

code --list-extensions | findstr "cortex-debug cpptools cmake-tools"

预期输出：

marus25.cortex-debug
ms-vscode.cmake-tools
ms-vscode.cpptools

7. 验证 ST-Link 设备

1. 连接 ST-Link 到 USB 端口
2. 打开设备管理器（Win + X → M）
3. 确认 "通用串行总线设备" 下出现 ST-Link 设备

---

编译验证

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

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

:: 初始化子模块
git submodule update --init --recursive

:: 进入模板项目目录
cd project\0_template

:: 创建构建目录
mkdir build
cd build

:: 配置项目（必须指定生成器）
cmake -G "MinGW Makefiles" ..

:: 编译项目
make

重要：Windows 上必须指定 CMake 生成器为 "MinGW Makefiles"。如果省略 -G 参数，CMake 可能默认使用 Visual Studio 生成器，导致编译失败。

预期输出：

[100%] Built target STM32F1.elf
Generating STM32F1.bin
   text    data     bss     dec     hex filename
   1234     108    1024    2366     93e STM32F1.elf

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

---

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

:: 在 build 目录中执行
make flash

预期输出：

Open On-Chip Debugger 0.12.0
...
Info : clock speed 1000 kHz
Info : STLINK V2J14S0 (API v2) VID:PID 0483:3748
Info : Target voltage: 3.2V
...
** Programming Started **
** Programming Finished **
** Verify Started **
** Verified OK **

如果烧录成功，说明 OpenOCD 和 ST-Link 驱动配置正确。

---

常见问题排查

问题 1：arm-none-eabi-gcc 不是内部或外部命令

症状：

'arm-none-eabi-gcc' 不是内部或外部命令，也不是可运行的程序或批处理文件。

解决方案：

1. 确认 ARM GCC 已安装：检查安装目录（如 C:\Tools\gcc-arm\bin）下是否有 arm-none-eabi-gcc.exe
2. 确认 PATH 已配置：

   where arm-none-eabi-gcc

3. 如果 PATH 中没有，按照 配置系统 PATH 环境变量 手动添加
4. 关闭并重新打开命令行窗口

---

问题 2：CMake 生成了 Visual Studio 项目

症状：运行 cmake .. 后，build 目录中出现了 .sln 或 .vcxproj 文件。

解决方案：

这是 CMake 在 Windows 上默认使用 Visual Studio 生成器导致的。必须显式指定生成器：

:: 删除旧的 build 目录
rmdir /s /q build
mkdir build
cd build

:: 指定 MinGW Makefiles 生成器
cmake -G "MinGW Makefiles" ..

重要：本教程所有涉及 cmake 的命令都需要加 -G "MinGW Makefiles" 参数。

---

问题 3：OpenOCD 找不到 ST-Link 设备

症状：

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

解决方案：

1. 检查 USB 连接是否牢固
2. 打开设备管理器，确认 ST-Link 是否被识别
3. 如果设备管理器中显示为 "未知设备"：
   • 安装 STSW-LINK009 驱动（参见 ST-Link 驱动安装）
   • 或使用 Zadig 替换驱动为 WinUSB
4. 如果使用的是克隆版 ST-Link，几乎肯定需要使用 Zadig

---

问题 4：Cortex-Debug 找不到 GDB

症状：

GDB executable "arm-none-eabi-gdb" was not found.
Please configure "cortex-debug.armToolchainPath" correctly.

解决方案：

方法一（首选）：确认 arm-none-eabi-gdb.exe 所在目录已添加到系统 PATH：

where arm-none-eabi-gdb

如果找到路径，重启 VSCode 再试。

方法二：在 VSCode 的 settings.json 中手动指定：

{
    "cortex-debug.armToolchainPath": "C:/Tools/gcc-arm/bin"
}

---

问题 5：make 命令无法识别

症状：

'make' 不是内部或外部命令，也不是可运行的程序或批处理文件。

解决方案：

1. 确认 ARM GCC 工具链已正确安装并添加到 PATH：

   where arm-none-eabi-gcc
   where make

   make 应与 arm-none-eabi-gcc 位于同一 bin 目录下。
2. 如果 PATH 中没有，按照 配置系统 PATH 环境变量 添加 C:\Tools\gcc-arm\bin
3. 如果安装了 MinGW，也可以尝试使用 mingw32-make 替代：

   mingw32-make

---

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

症状：

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

解决方案：

:: 确保已克隆 third_party 子模块
cd C:\path\to\ST-Forge
git submodule update --init --recursive

:: 检查 HAL 库是否存在
dir third_party\STM32CubeF1\Drivers\STM32F1xx_HAL_Driver\Inc\

---

问题 7：路径中包含空格导致编译失败

症状：

No such file or directory

且项目路径包含 Program Files 等空格。

解决方案：

将项目克隆到无空格的路径：

:: 避免这样
cd C:\Users\My User\Documents\My Projects\ST-Forge

:: 推荐这样
cd C:\Projects\ST-Forge
:: 或
cd D:\Dev\ST-Forge

---

快速参考

安装路径汇总

工具	推荐安装路径	需添加到 PATH 的子目录
ARM GCC（含 Make）	C:\Tools\gcc-arm	bin\
CMake	默认（安装时勾选 PATH）	自动
OpenOCD	C:\Tools\openocd	bin\
Git	默认	自动
VSCode	默认	自动

常用命令速查

操作	命令
验证 ARM GCC	arm-none-eabi-gcc --version
验证 CMake	cmake --version
验证 Make	make --version
验证 OpenOCD	openocd --version
查看 PATH	where <命令名>
配置项目	cmake -G "MinGW Makefiles" ..
编译项目	make
烧录固件	make flash

---

下一步

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

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

---

参考资料

• ARM GNU Toolchain 下载
• CMake 官方下载
• xPack OpenOCD Releases
• Git for Windows
• VSCode 官网
• STSW-LINK009 驱动下载
• Zadig USB 驱动工具
• OpenOCD 官方文档

---

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