简介：ST官方例程包.rar是意法半导体面向STM32F103RCT6发布的官方例程合集，适合嵌入式初学者、应用工程师以及参加电子竞赛的学生使用。压缩包整体34.22MB，共收录1737个文件，其中626个C源码与470个头文件构成代码主体，并配有Keil和STM32CubeIDE工程文件、启动汇编、说明文档、固件镜像、配置脚本等，另含RAR子包、DFU固件与BAT批处理工具，目录结构清楚，可按模块查找。例程覆盖GPIO输入输出、外部中断、定时器、UART串口、ADC采集、PWM输出、I2C与SPI通信等常用外设，同时提供HAL库和LL库两套接口，并给出初始化流程、外设配置和中断管理代码。其中GPIO示例演示引脚模式配置与读写，UART示例演示串口收发，ADC示例演示多通道采样与转换，适合对照学习底层原理，也可直接移植到实际项目。目前已有812人学习下载，是一份值得常备的官方参考资料。
1. ST官方例程包.rar：一个压缩包解决"芯片外设不会用"的入门难题
某开发者第一次拿到 ST 官方例程包.rar，解压后看见几十个文件夹，第一反应是懵——这跟想象中"一个例程一个 .c 文件"完全不一样。其实这个压缩包就是 ST 官方为自家芯片准备的全家桶：里面有芯片启动代码、外设驱动库、中间件和一堆针对官方开发板的示例工程。它的价值不是让你直接抄某个 demo，而是让你搞清楚"这颗芯片的每个外设到底该怎么操作"。只要你会读电路图、会改引脚号，就能把官方的板子例程迁移到自己的设计上。这篇笔记适合刚入手 STM32 的新手，也适合被库版本和工程结构绕晕的熟手——我会把从解压到移植的完整路径捋一遍，并标出最容易翻车的几个点。
2. 获取与解压：先搞清楚"官方例程包"里到底装了什么
2.1 从官网挑对型号：例程包不是通用的
ST 官方例程包按芯片系列分门别类，比如针对主流系列、低功耗系列、无线系列都有各自独立的压缩包。选错系列是第一步就踩坑的大问题，常见做法是打开 ST 官网的"工具与软件"页面，根据你板子上的芯片型号关键字去搜对应系列包。
比如你的芯片是某系列 MCU，就要找该系列对应的例程包名，不要因为"看着像"就下载相邻系列的包。每个压缩包的解压目录里，顶层文件夹名字中会带系列标识。下载时优先选后缀为 .rar 或 .zip 的完整包，不要只下单个工程文件，否则缺失底层驱动，后面编译会报一大堆找不到头文件的错误。
挑选时注意区分"标准外设库"和"HAL 库"两个时代的产品。标准外设库早期案例多，但已停止更新；HAL 库是现在的主流，配合 ST 官方的图形配置工具使用。如果你用的是近几年新出的芯片，直接选择 HAL 库版本的例程包。我一般会看压缩包内 Release_Notes 文件的日期，选更新时间最近的稳定版本，而不是最新的实验版本。
2.2 解压后的目录结构：每个文件夹各管哪一块
拿到正确的压缩包后，不要急着双击打开。在 Linux 或 Windows 下用命令行解压，能避免资源管理器中途崩溃导致文件不完整。以 Linux 下解压 rar 为例：
# 安装工具（如果还没有） sudo apt install unrar # 解压到指定目录，保持目录结构完整 unrar x ST官方例程包.rar -d ~/stm32_workspace逻辑说明：unrar x会保留包内原始路径，-d指定解压目标目录。解压后建议用tree命令快速看一层结构：
cd ~/stm32_workspace/ST官方例程包 tree -L 2输出大致如下（不同系列略有差异）：
. ├── Drivers │ ├── CMSIS │ └── STM32XX_HAL_Driver ├── Middlewares │ ├── ST │ └── Third_Party ├── Projects │ ├── 某官方评估板 │ └── 模板工程 └── Utilities逻辑说明：Drivers/CMSIS是芯片核心支持文件，包括内核寄存器定义和系统启动文件；Drivers/STM32XX_HAL_Driver是 HAL 外设驱动源码，每个外设对应一组 .c/.h 文件。Projects里是官方评估板的示例工程，按外设或应用场景分文件夹。Middlewares存放 USB、文件系统、RTOS 等中间件。Utilities则放一些通用评估板组件。
参数说明：如果你只需要某个外设的例程，完全可以只拷贝Projects下的对应子文件夹，但Drivers必须整个保留，因为工程依赖底层驱动。不要把Utilities下的私有组件拷进自己的项目，它们经常依赖特定评估板的引脚定义。
2.3 用校验和和版本说明验证文件完整性
压缩包下载中断、解压软件版本过旧，都可能让例程包里的某个文件损坏。损坏文件在编译时才暴露，表现为莫名其妙的语法错误。我习惯在解压前先校验哈希值，官网下载页面通常会给出 SHA-256 值。
# 计算压缩包哈希 sha256sum ST官方例程包.rar逻辑说明：将计算出的值与官网公布值对比。如果一致，说明下载过程完整；不一致就重新下载，不要继续解压。
解压后，第一件事是打开根目录的Release_Notes.html或readme.txt，在里面确认三件事：这个包适用于哪些具体芯片型号、需要哪个版本的编译工具链、有没有已知问题。参数说明：很多例程包对 IDE 版本有隐性要求，比如某个编译环境版本太旧会无法识别-mcpu=cortex-m4编译选项。我见过有人拿着新例程包配老编译器，报错一屏，实际上只是内核选项不认识。
注意：不要只拷走 Projects 里的源文件就扔了 Drivers，HAL 库是一整套互相调用的代码，缺一个文件都会让编译链条断裂。
3. 把第一个例程跑起来：最小系统工程的编译与下载
3.1 直接开官方工程 vs 用图形工具生成：两条路径怎么选
官方例程包里的 Projects 目录放着各种现成工程，适合先烧进板子验证功能。但直接打开官方工程的一个问题是，里面有很多针对评估板的配置，比如特定引脚、外部晶振频率、LED 所在 GPIO，这些都跟你的最小系统板不一样。
另一条路径是用官方图形配置工具从零生成工程，它能选芯片型号、配置时钟树、勾选外设，然后自动生成初始化代码和 IDE 工程。这条路径对新手更友好，但它的缺点是你对底层依赖关系理解不深，出了问题往往不知道去哪改。
我建议两条路线都走一遍：先打开官方例程包里的现成工程烧录，确认硬件工具链没问题；再用图形工具生成一个最小工程，对比官方工程看看配置文件差异。这里以手工搭建最小工程为例，因为这样才能彻底看清例程包内部的依赖关系，也方便后续脱离图形工具做定制。
3.2 从例程包抽取最小工程骨架
假设你要在某个 STM32 系列上跑一个闪灯程序。手工建工程时，需要从例程包复制两类文件：一是Drivers下的 CMSIS 和 HAL 驱动；二是Projects/模板工程下的启动文件、链接脚本和系统时钟初始文件。
# 建自己的工程目录 mkdir -p my_project/{Core,Drivers} # 复制模板工程里的启动文件、链接脚本和系统文件 cp -r ST官方例程包/Projects/某模板工程/Startup/ my_project/Core/ cp -r ST官方例程包/Projects/某模板工程/Src/main.c my_project/Core/ # 复制整个驱动目录（按需保留 HAL 也能精简） cp -r ST官方例程包/Drivers/ my_project/逻辑说明：Startup文件夹里是汇编写的启动文件（比如startup_stm32xxxxx.s）和链接脚本（.ld文件），这两者决定程序入口和内存布局。main.c可以不加，最后自己写，但复制过来作参考能减少初始错误。
参数说明：链接脚本里的FLASH和RAM起始地址与容量必须和你的芯片型号一致。如果复制的模板工程针对的是高密度芯片而你用的是低密度，需要到对应Device文件夹下找正确的.ld文件。这一步的坑在第五章细说。
3.3 最小闪灯程序：从初始化到翻转
写好main.c，最简 LED 闪烁逻辑如下：
#include "main.h" int main(void) { HAL_Init(); // 初始化HAL库，设置中断优先级分组 SystemClock_Config(); // 配置系统时钟（内部HSI，默认频率） __HAL_RCC_GPIOA_CLK_ENABLE(); // 打开GPIOA的时钟 GPIO_InitTypeDef GPIO_InitStruct = {0}; GPIO_InitStruct.Pin = GPIO_PIN_5; // 选择PA5 GPIO_InitStruct.Mode = GPIO_MODE_OUTPUT_PP; // 推挽输出 GPIO_InitStruct.Pull = GPIO_NOPULL; // 无上下拉 GPIO_InitStruct.Speed = GPIO_SPEED_FREQ_LOW; // 低速即可 HAL_GPIO_Init(GPIOA, &GPIO_InitStruct); while (1) { HAL_GPIO_TogglePin(GPIOA, GPIO_PIN_5); // 翻转电平 HAL_Delay(500); // 延时500ms } }逻辑说明：HAL_Init()必须最先调用，它初始化内部时基和中断分组。SystemClock_Config()在这里只配成默认内部时钟，不依赖外部晶振，适合没有任何时钟电路的最小系统板。GPIO 初始化分成两步：先使能外设时钟，再填好GPIO_InitTypeDef结构体。
参数说明：Pin支持多个引脚按位或，比如GPIO_PIN_5 | GPIO_PIN_6。Mode可选GPIO_MODE_OUTPUT_PP（推挽输出）、GPIO_MODE_OUTPUT_OD（开漏输出）等。驱动 LED 一般用推挽；驱动 I2C 这类需要线与的场合才用开漏。Speed在低速信号下选LOW能减少功耗和噪声，高速通信再调高。
编译时用arm-none-eabi-gcc和工程里的Makefile：
CROSS_COMPILE ?= arm-none-eabi- CC = $(CROSS_COMPILE)gcc CFLAGS = -mcpu=cortex-m4 -mthumb -DSTM32F407xx -DUSE_HAL_DRIVER -I Drivers/CMSIS/include -I Drivers/STM32XX_HAL_Driver/Inc -I Core LDFLAGS = -T Core/STM32F407ZGTx_FLASH.ld OBJECTS = Core/startup.o Core/main.o逻辑说明：-DSTM32F407xx是芯片型号宏，HAL 库和启动文件都靠它选择设备头文件。-DUSE_HAL_DRIVER告诉代码使用 HAL 库。链接脚本-T要指向你的型号。编译命令arm-none-eabi-gcc $(CFLAGS) -c每个源文件，最后链接生成.bin。
烧录用 ST-Link 工具：
st-flash write build/my_project.bin 0x08000000逻辑说明：0x08000000是 STM32 内部 Flash 的起始地址。如果下载失败，先检查 ST-Link 与板子的 SWD 接线是否正确，尤其注意 3.3V、GND、SWDIO、SWCLK 四根线。参数说明：某些板子复位电容太大导致连接不上，可以尝试给板子断电再上电时立刻执行写命令。
4. 移植到你自己的板子：引脚、时钟和外设的改法
4.1 先看原理图再动手：引脚重映射的流程
官方例程包里的工程是为官方评估板写的，LED 可能在 PB0，你的板子在 PA5。直接烧进去不亮很正常，因为引脚不对。移植的第一步不是改代码，而是打开你自己的板子原理图，确认 LED、按键、串口这些外设挂在哪个引脚上，然后对照芯片数据手册的Alternate Function Mapping表，确认该引脚是否支持你需要的复用功能。
/* 从官方默认的PB0改成PA5 */ GPIO_InitStruct.Pin = GPIO_PIN_5; GPIO_InitStruct.Mode = GPIO_MODE_OUTPUT_PP; HAL_GPIO_Init(GPIOA, &GPIO_InitStruct);逻辑说明：只改引脚号是不够的，还要把HAL_GPIO_Init的第一个参数从GPIOB改成GPIOA，并把上面__HAL_RCC_GPIOB_CLK_ENABLE()改成__HAL_RCC_GPIOA_CLK_ENABLE()。如果漏掉时钟使能，写寄存器时表现为程序跑飞或进 HardFault。
参数说明：如果是串口等复用功能，还要额外设置Alternate字段，例如GPIO_InitStruct.Alternate = GPIO_AF7_USART1。你可以在数据手册的引脚定义表里查到该引脚的 AF 号。这里常见误区是只改引脚不写复用号，导致功能不生效。
4.2 外部晶振和 PLL 时钟配置：不同板子的时钟树差异
官方评估板上通常有 8MHz 或 25MHz 外部晶振，你的核心板可能用的是内部 RC 振荡器，或者外部晶振频率不一样。如果直接跑官方例程，系统会按 8MHz 计算 PLL 倍频，但你的晶振是 12MHz，最后系统频率会偏得离谱，串口波特率就乱了。最稳妥的改法是先看板子原理图上晶振标注频率。
void SystemClock_Config(void) { RCC_OscInitTypeDef RCC_OscInitStruct = {0}; RCC_ClkInitTypeDef RCC_ClkInitStruct = {0}; /* 配置外部晶振为12MHz */ RCC_OscInitStruct.OscillatorType = RCC_OSCILLATORTYPE_HSE; RCC_OscInitStruct.HSEState = RCC_HSE_ON; RCC_OscInitStruct.HSEFreq = RCC_HSE_12MHz; // 如果你用的HAL版本需要 RCC_OscInitStruct.PLL.PLLState = RCC_PLL_ON; RCC_OscInitStruct.PLL.PLLSource = RCC_PLLSOURCE_HSE; RCC_OscInitStruct.PLL.PLLM = 6; // 12MHz/6=2MHz RCC_OscInitStruct.PLL.PLLN = 168; // 2MHz*168=336MHz RCC_OscInitStruct.PLL.PLLP = 2; // 336MHz/2=168MHz 系统时钟 RCC_OscInitStruct.PLL.PLLQ = 7; // USB时钟用 HAL_RCC_OscConfig(&RCC_OscInitStruct); RCC_ClkInitStruct.ClockType = RCC_CLOCKTYPE_SYSCLK | RCC_CLOCKTYPE_HCLK | RCC_CLOCKTYPE_PCLK1 | RCC_CLOCKTYPE_PCLK2; RCC_ClkInitStruct.SYSCLKSource = RCC_SYSCLKSOURCE_PLLCLK; HAL_RCC_ClockConfig(&RCC_ClkInitStruct, FLASH_LATENCY_5); }逻辑说明：PLL 参数是按目标系统频率反推的，PLLM是预分频，PLLN是倍频系数，PLLP是系统时钟分频。如果你用的是无外部晶振的最小系统板，可以把HSEState改成RCC_HSI_ON，并将PLLSource改为RCC_PLLSOURCE_HSI。
参数说明：不同芯片系列的 PLL 结构不一样，有的需要PLLM、PLLN、PLLP，有的还有PLLR。不要照搬其他系列的数值，务必参照目标芯片的参考手册里的Clock Tree章节。另外，改系统时钟后，HAL_Delay()的延时会跟着变，因为它是基于 SysTick 的，而 SysTick 时钟源与 HCLK 关联。如果发现串口乱码或延时不准，多半是系统时钟没配置到预期值。
4.3 外设驱动裁剪：用不到的模块怎么关
官方例程包里的 HAL 驱动默认把几乎所有外设都编译进去，这会让 Flash 占用变大。你在自己的项目里可能只需要 GPIO、UART、SPI，可以通过配置文件裁剪掉不需要的模块，减少编译时间和存储占用。
/* stm32f1xx_hal_conf.h 中按需注释 */ // #define HAL_ADC_MODULE_ENABLED #define HAL_SPI_MODULE_ENABLED #define HAL_UART_MODULE_ENABLED // #define HAL_CAN_MODULE_ENABLED // #define HAL_I2C_MODULE_ENABLED逻辑说明：这些宏开关控制对应外设驱动源文件是否被编译。注释掉不需要的模块后，相关 API 就不存在了，如果代码里仍调用，编译会报"未定义"。因此裁剪前先确认自己的启动代码里没有用到这些外设。参数说明：有些中间件依赖特定外设，比如 USB 依赖HAL_PCD_MODULE_ENABLED，需要一并打开。
注意：裁剪驱动时，不要动
HAL_RCC_MODULE_ENABLED和HAL_CORTEX_MODULE_ENABLED，这两项是系统运行的基础。我见过有人为了省空间把HAL_RCC关了，结果整个芯片时钟都起不来，现象比外设不工作更隐蔽。
5. 避坑：官方例程包最常见的 5 个翻车现场
5.1 芯片型号与例程包系列不匹配
现象：编译时出现Device/STM32F4xx.h: No such file or directory，或者链接时大量undefined reference to 'SystemInit'。
原因：你解压的是 F1 系列的例程包，却用 F4 系列芯片的启动文件和链接脚本。CMSIS 头文件是按系列区分的，内部代码通过#if defined(STM32F407xx)等宏选择寄存器定义。宏不对，头文件路径自然找不到。
解决：重新下载对应系列的例程包。如果实在不想重新下载，可以只替换Drivers/CMSIS/Device/ST下的设备头文件，但这很容易带来源文件和头文件不匹配。最稳妥是完整下载正确系列的包。
5.2 工程路径和文件名带中文
现象：编译报fatal error: cannot open source file "..\核心\main.c": Invalid argument，或者烧录时提示找不到文件。
原因：一些编译器和调试器对非 ASCII 路径支持不好，尤其是 Windows 下使用官方 IDE 或 GCC 工具链时，中文路径中的字符会被错误编码。压缩包解压后默认文件夹名可能是中文，或者你自己建的工程目录用了中文名。
解决：把整个工程目录移到纯英文路径下，例如C:\Users\dev\STM32\my_project。同时检查环境变量里有没有包含中文的路径。我一般会把临时文件目录和工程路径都设为英文，避免很多莫名其妙的报错。
5.3 HAL 库模块宏未开启导致外设 API 缺失
现象：调用HAL_ADC_Start()后编译报implicit declaration of function，或直接显示HAL_ADC_Start未定义。
原因：HAL 库通过stm32xx_hal_conf.h中的模块开关决定哪些外设驱动被编译进项目。如果你复制的工程配置里#define HAL_ADC_MODULE_ENABLED被注释掉了，那么 ADC 的源文件不会被编译，头文件中对应的函数声明也不会生效。
解决：打开stm32xx_hal_conf.h，确认需要的模块宏是#define状态，而不是// #define。每个模块对应一组HAL_XXX_MODULE_ENABLED。如果工程里同时有多个源文件包含该配置文件，注意不要改错了副本。
5.4 烧录时连接失败或 Flash 下载超时
现象：点烧录按钮后，工具提示Error: Flash Download failed - Target DLL has been cancelled，或者No target connected。
原因：最常见是 ST-Link 的 SWD 四根线接触不良，也有可能是板子电源带不动调试器，导致目标芯片电压跌落。还有一种是目标板上的复位电路电容过大，导致调试器无法在复位窗口内握手。
解决：先用万用表测 ST-Link 输出的 3.3V 是否稳定。然后检查 SWDIO、SWCLK 是否接反，这两个信号线没有标准颜色，很容易按个人习惯接错。如果还不行，按住板子复位按键，在启动烧录命令瞬间松开，这招能绕过复位时序问题。给板子外接独立 3.3V 电源也能解决部分供电不足问题。
5.5 HAL 库版本混用：旧标准库和新库的冲突
现象：编译大量报macro "XXX" passed 2 arguments, but takes just 1或者conflicting types for 'GPIO_Init'。
原因：早期标准外设库（SPL）的函数名和参数表与 HAL 库完全不同。有些移植者图省事，把旧项目里的代码直接拖进新例程包工程，导致两个库的头文件互相包含，编译时同时认了两种定义。
解决：确定你的项目整体采用哪一套库。新设计建议全用 HAL 库，老代码需要重写外设初始化部分。如果确实要复用旧代码，可以封装一层适配函数，把 SPL 风格的调用映射为 HAL 调用。但不要同时把两个库的源码都加进编译列表，这是典型的自找麻烦。
6. 进阶：把官方例程抽成你自己的驱动层
等你跑通了几十个官方例程，会发现一个问题：每次换芯片或换板子，都要重新改 GPIO 引脚、时钟、外设参数。早期我直接在官方 demo 上改，结果一批项目维护起来很痛苦。后来养成的习惯是，从例程包里抽基础代码，封装成自己的bsp_驱动层。
/* bsp_led.h */ typedef struct { GPIO_TypeDef *port; uint16_t pin; } Led_Handle_t; void BSP_LED_Init(Led_Handle_t *led, GPIO_TypeDef *port, uint16_t pin); void BSP_LED_On(Led_Handle_t *led); void BSP_LED_Off(Led_Handle_t *led);/* bsp_led.c */ #include "bsp_led.h" void BSP_LED_Init(Led_Handle_t *led, GPIO_TypeDef *port, uint16_t pin) { GPIO_InitTypeDef GPIO_InitStruct = {0}; led->port = port; led->pin = pin; __HAL_RCC_GPIOA_CLK_ENABLE(); // 实际应该按port判断 GPIO_InitStruct.Pin = pin; GPIO_InitStruct.Mode = GPIO_MODE_OUTPUT_PP; GPIO_InitStruct.Speed = GPIO_SPEED_FREQ_LOW; HAL_GPIO_Init(port, &GPIO_InitStruct); }逻辑说明：这样设计后，板子上的 LED 引脚只在一个地方初始化，换板子时改main.c里的参数即可，不用动驱动内部逻辑。同理可以封装 UART、按键、I2C 等。这些驱动层代码可以从官方例程的函数原型出发，但去掉与评估板耦合的部分。
参数说明：注意 LED 驱动初始化时，如果 LED 是低电平点亮，On/Off函数里的写入电平要反过来。不能想当然用高电平点亮。
最后说一句我的教训：尽量别把官方例程包里的全部文件都拷贝进自己项目，只要保持Drivers加自己的应用层结构，升级固件包时只需要替换Drivers/CMSIS和Drivers/STM32XX_HAL_Driver，应用层代码几乎不用动。这样后续跟上官方修复版本就容易得多，希望帮到你。
本文还有配套的精品资源，点击获取
