本教程默认你是零基础新手，会尽量把每一步写清楚。你可以一边看一边操作，不需要先掌握完整理论。

一、教程简介

这篇教程带你从零创建一个 STM32 最小工程。最终你会得到一个能编译、能下载、能闪灯、后续能继续扩展的工程模板。

【此处配图：STM32 开发板、ST-Link、电脑软件环境总览图】

二、目录导航

  1. 前置准备
  2. 安装和打开 STM32CubeMX
  3. 新建 STM32 工程
  4. 配置调试接口和时钟
  5. 配置 LED 引脚
  6. 生成 Keil 工程
  7. 用 Keil 编译和下载
  8. 用 VSCode 编辑代码
  9. 新手易错点
  10. 常见问题 FAQ
  11. 总结

三、前置准备

1. 需要准备的硬件

  1. STM32 开发板：任意常见开发板都可以，比如 STM32F103、STM32F407。
  2. ST-Link 下载器：用于把程序下载到芯片里。
  3. USB 数据线：连接开发板或下载器。
  4. 电脑：Windows 系统最适合新手跟着操作。

2. 需要安装的软件

  1. STM32CubeMX：用于图形化配置芯片。
  2. Keil MDK：用于编译、下载和调试。
  3. 芯片支持包：Keil 里需要安装对应 STM32 系列 Pack。
  4. VSCode：用于更舒服地写代码，可选但推荐。

【此处配图：软件安装列表截图】

四、详细步骤

步骤 1：打开 STM32CubeMX

  1. 双击打开 STM32CubeMX。
  2. 进入主界面后，点击 ACCESS TO MCU SELECTOR。
  3. 在搜索框输入你的芯片型号，例如 STM32F103C8T6。
  4. 选中芯片后，点击 Start Project。

注意事项：

  • 芯片型号必须和你开发板上的主控一致。
  • 如果不知道芯片型号，可以看芯片表面的丝印。

步骤 2：配置调试接口

  1. 左侧找到 System Core。
  2. 点击 SYS。
  3. 找到 Debug。
  4. 选择 Serial Wire。

为什么必须这样做？

如果不打开 Serial Wire，后面可能无法用 ST-Link 下载和调试程序。

【此处配图：SYS Debug 选择 Serial Wire 的截图】

步骤 3：配置时钟

  1. 左侧点击 RCC。
  2. 如果开发板有外部晶振，HSE 选择 Crystal/Ceramic Resonator。
  3. 如果你不确定有没有外部晶振，可以先保持默认。
  4. 切换到顶部 Clock Configuration 页面。
  5. 确认红色报错全部消失。

新手建议：

第一次学习不要追求最高频率，能正常运行最重要。

步骤 4：配置 LED 引脚

  1. 查开发板原理图，找到 LED 对应的 GPIO，例如 PC13。
  2. 在芯片引脚图上点击 PC13。
  3. 选择 GPIO_Output。
  4. 左侧进入 GPIO，确认该引脚模式是输出。

【此处配图：PC13 配置成 GPIO_Output 的截图】

步骤 5：设置工程名称和 IDE

  1. 点击顶部 Project Manager。
  2. Project Name 填写：stm32_minimal_template。
  3. Project Location 选择一个英文路径，例如 D:\STM32_Project。
  4. Toolchain / IDE 选择 MDK-ARM。
  5. 点击 GENERATE CODE。

避坑要点：

  • 路径尽量不要有中文。
  • 路径不要太深。
  • 工程名不要有空格。

步骤 6：用 Keil 打开工程

  1. 进入生成的工程目录。
  2. 打开 MDK-ARM 文件夹。
  3. 双击 .uvprojx 文件。
  4. Keil 打开后，先点击编译按钮。
  5. 如果显示 0 Error，说明工程生成成功。

步骤 7：编写闪灯代码

在 main.c 中找到 while (1)，写入：

while (1)
{
  HAL_GPIO_TogglePin(GPIOC, GPIO_PIN_13);
  HAL_Delay(500);
}

如果你的 LED 不是 PC13，要把 GPIOC 和 GPIO_PIN_13 改成你的引脚。

步骤 8：下载程序

  1. 插上 ST-Link。
  2. Keil 点击 Options for Target。
  3. 进入 Debug。
  4. 选择 ST-Link Debugger。
  5. 点击 Settings，确认能识别 ST-Link。
  6. 点击下载按钮。
  7. 观察 LED 是否闪烁。

【此处配图：Keil ST-Link 设置截图】

步骤 9：用 VSCode 编辑代码

  1. 打开 VSCode。
  2. 点击 File -> Open Folder。
  3. 选择 STM32 工程根目录。
  4. 安装 C/C++ 插件。
  5. 以后可以用 VSCode 写代码，用 Keil 编译下载。

五、新手易错点

  1. 忘记打开 Serial Wire：会导致 ST-Link 连接失败。
  2. 芯片型号选错：工程能生成，但下载或外设配置会异常。
  3. LED 引脚写错：程序下载成功但灯不闪。
  4. 工程路径有中文：Keil 可能出现奇怪编译错误。
  5. 没有安装芯片 Pack：Keil 打开工程后无法识别芯片。

六、常见问题 FAQ

Q1：编译时报错找不到头文件怎么办？

先确认工程是 CubeMX 正常生成的，不要手动移动 Core 和 Drivers 文件夹。如果移动过，建议重新生成工程。

Q2：下载失败怎么办？

检查 ST-Link 接线、驱动、供电，以及 CubeMX 里是否开启 Serial Wire。

Q3：LED 不闪怎么办？

先确认 LED 引脚是否正确，再确认 LED 是高电平亮还是低电平亮。有些板子 PC13 输出低电平才亮。

Q4：VSCode 可以直接代替 Keil 吗？

可以，但新手建议先用 Keil 跑通，再慢慢学习 CMake、OpenOCD 和 VSCode 调试。

七、总结

你现在已经完成了一个 STM32 最小工程模板。后续做串口、I2C、FreeRTOS、传感器项目，都可以从这个模板继续扩展。

八、温馨提示

新手学习 STM32 时，不要同时改很多地方。建议每完成一个小功能就保存工程，并记录“我改了哪里、看到什么现象”。这样后面出问题时，你能快速退回到上一版。