简介：STM32Cube_FW_F1_V1.8.0 是意法半导体面向 STM32F1 系列微控制器推出的官方固件库，属于 STM32Cube 生态的核心组成，适合嵌入式初学者、工程师及高校师生用于外设驱动开发与项目快速原型搭建。包内集成 HAL 与 LL 双层次驱动，覆盖 ADC、CAN、DMA、GPIO、I2C、SPI、TIM、USART 等常用外设，并附带 USB OTG、FatFS、FreeRTOS 等中间件、丰富应用示例及 HAL/LL 参考文档，兼容 Keil MDK、IAR 与 GCC ARM 等主流开发环境。资源以 rar 压缩包形式提供，整体约 95.73MB，文件类型以驱动源码、头文件、示例工程与说明文档为主，便于按外设模块检索与移植。目前已有 1088 人学习下载，读者可借助其完整驱动接口、中间件与示例代码，减少底层硬件细节投入，将精力集中于物联网、工业控制、消费电子等应用逻辑设计，同时配合 STM32CubeMX 图形化配置快速生成初始化代码，提升开发效率。
1. 拿到 STM32Cube_FW_F1_V1.8.0 之后：它到底是什么，能帮你省掉哪些重复劳动
如果你手上有一块 STM32F1 系列的板子，比如最常见的 F103C8T6 最小系统板，或者某个老项目里还在跑的 F103ZET6 工控板，那你大概率绕不开一个东西：STM32Cube_FW_F1。这个包不是某一个单独的库，而是 ST 官方为 F1 全系准备的一整套固件包，里面同时塞了 HAL 库、LL 库、CMSIS 设备支持、板级支持包 BSP、一堆外设例程，以及每个外设的独立工程模板。V1.8.0 这个版本号意味着它是 F1 系列 Cube 固件包里比较靠后的一版，HAL 的 API 已经稳定，例程覆盖也全，不像早期版本那样动不动就缺某个外设的示例。
很多人第一次拿到这个 rar 会有点懵，解压出来目录一大堆，不知道从哪进。其实你只需要盯住几个关键路径：Drivers 下面放的是 HAL 和 CMSIS，Projects 下面按板子和外设分好了例程，Middlewares 里是 USB、FatFs、FreeRTOS 这类中间件。它解决的核心问题就一个：你不用再从零去写寄存器配置，也不用去网上东拼西凑某个外设的初始化代码，官方已经把 GPIO、UART、SPI、I2C、ADC、TIM、CAN、USB 这些常用外设的初始化流程和中断处理都封装好了。适合谁？适合正在用 F1 做产品原型的嵌入式工程师，也适合刚学完 51 想往 ARM 上走的同学，因为 HAL 的抽象层次比直接怼寄存器友好得多。
2. 拆包与目录结构：先搞清楚每个文件夹是干什么的
2.1 解压后的顶层目录与核心文件
把 STM32Cube_FW_F1_V1.8.0.rar 解压到一个路径里不带中文和空格的目录，比如 D:\STM32\F1_V1.8.0。解压完你会看到这么几个顶层文件夹：
| 目录名 | 里面装了什么 | 你什么时候会用到 |
|---|---|---|
| Drivers | CMSIS 内核头文件、设备启动文件、HAL 驱动源码、LL 驱动源码 | 每个工程都要引用，编译时必带 |
| Projects | 按官方评估板分目录的例程，每个例程有 MDK-ARM、STM32CubeIDE、IAR 等工程 | 想快速验证某个外设时直接打开对应工程 |
| Middlewares | USB Device/Host 库、FatFs 文件系统、FreeRTOS、STemWin | 需要文件系统、RTOS 或 USB 通信时 |
| Utilities | 一些辅助组件，比如 LCD 驱动、音频接口 | 跑官方板子的显示例程时会用到 |
这里有个血泪经验：很多人解压完直接去 Projects 里找自己芯片对应的例程，结果发现官方例程都是按评估板命名的，比如 STM3210E-EVAL，跟你手上的最小系统板引脚对不上。这时候不要硬改例程的引脚，而是去 Drivers 里把 HAL 源码拿出来，自己新建工程，用 CubeMX 生成初始化代码，再把 HAL 驱动加进去。这样引脚配置是你自己的，HAL 版本又是 V1.8.0 这一套，不会出现版本错配。
2.2 用 CubeMX 配合固件包生成工程
如果你不想手动拷贝文件，最省事的做法是用 STM32CubeMX 来生成工程。打开 CubeMX，在 Help 菜单里找到 Manage embedded software packages，把 F1 的固件包路径指向你解压出来的目录。具体操作是：
# 假设你解压到了 D:\STM32\F1_V1.8.0 # 在 CubeMX 的包管理界面里，选择 From Local，然后定位到： D:\STM32\F1_V1.8.0 # CubeMX 会自动识别出版本号 V1.8.0，并把它列为可用包这一步的逻辑是让 CubeMX 知道本地已经有一份完整的固件包，不用再去线上下载。参数上要注意，CubeMX 对路径里的空格和中文很敏感，如果你解压到 C:\Users\某某\Desktop\新建文件夹，大概率识别失败。我一般会统一放在 D:\STM32\ 下面，版本号作为子目录名，这样以后换版本也不会乱。
识别成功之后，新建工程选好芯片型号，比如 STM32F103C8Tx，然后在 Project Manager 里把 Toolchain 设成 MDK-ARM 或 STM32CubeIDE，生成代码时 CubeMX 会自动从你指定的固件包里拷贝 HAL 驱动和 CMSIS 文件到工程目录。这样出来的工程，HAL 版本就是 V1.8.0，不会出现你本地装的是 V1.7.0 但 CubeMX 给你生成 V1.8.0 代码的尴尬情况。
2.3 手动搭建工程时的文件拷贝清单
有些老项目用的是 Makefile 或者自己写的链接脚本，不用 CubeMX，那就得手动拷贝文件。下面是我常用的最小文件集，以 F103C8T6 为例：
# 从固件包里拷贝到你的工程目录 # 1. CMSIS 内核相关 cp Drivers/CMSIS/Device/ST/STM32F1xx/Source/Templates/gcc/startup_stm32f103xb.s 你的工程/startup/ cp Drivers/CMSIS/Device/ST/STM32F1xx/Include/stm32f103xb.h 你的工程/inc/ cp Drivers/CMSIS/Include/core_cm3.h 你的工程/inc/ cp Drivers/CMSIS/Include/cmsis_compiler.h 你的工程/inc/ # 2. HAL 驱动 cp Drivers/STM32F1xx_HAL_Driver/Src/stm32f1xx_hal.c 你的工程/src/ cp Drivers/STM32F1xx_HAL_Driver/Src/stm32f1xx_hal_gpio.c 你的工程/src/ cp Drivers/STM32F1xx_HAL_Driver/Src/stm32f1xx_hal_rcc.c 你的工程/src/ cp Drivers/STM32F1xx_HAL_Driver/Src/stm32f1xx_hal_uart.c 你的工程/src/ cp Drivers/STM32F1xx_HAL_Driver/Src/stm32f1xx_hal_cortex.c 你的工程/src/ cp Drivers/STM32F1xx_HAL_Driver/Inc/stm32f1xx_hal.h 你的工程/inc/ cp Drivers/STM32F1xx_HAL_Driver/Inc/stm32f1xx_hal_gpio.h 你的工程/inc/ cp Drivers/STM32F1xx_HAL_Driver/Inc/stm32f1xx_hal_uart.h 你的工程/inc/ cp Drivers/STM32F1xx_HAL_Driver/Inc/stm32f1xx_hal_rcc.h 你的工程/inc/ cp Drivers/STM32F1xx_HAL_Driver/Inc/stm32f1xx_hal_cortex.h 你的工程/inc/这里的关键是启动文件要选对型号。startup_stm32f103xb.s 对应的是中容量 F103，如果你用的是 F103ZE 这种大容量，要换成 startup_stm32f103xe.s。HAL 驱动也不是全拷就好，用不到的模块可以不拷，但 stm32f1xx_hal.c 和 stm32f1xx_hal_cortex.c 是基础，必须带上。拷贝完之后，在 stm32f1xx_hal_conf.h 里把用到的模块宏打开，比如 #define HAL_GPIO_MODULE_ENABLED，不然编译会报一堆未定义。
3. HAL 库初始化流程：从 SystemClock 到外设配置的完整链路
3.1 时钟树配置与 SystemClock_Config 的生成逻辑
F1 的时钟配置是很多新手翻车的地方。HAL 库把时钟初始化封装在 SystemClock_Config 函数里，这个函数一般由 CubeMX 生成，但如果你手动写，就要搞清楚几个关键参数：HSE 外部晶振频率、PLL 倍频系数、AHB/APB 分频。以常见的 8MHz 外部晶振、目标 72MHz 主频为例，配置逻辑是这样的：
void SystemClock_Config(void) { RCC_OscInitTypeDef RCC_OscInitStruct = {0}; RCC_ClkInitTypeDef RCC_ClkInitStruct = {0}; // 使能 HSE，并配置 PLL：HSE 8MHz / 2 * 9 = 36MHz? 不对，F1 的 PLL 源是 HSE 不分频 // 实际是 HSE 8MHz * 9 = 72MHz，PLLMUL 设为 9 倍频 RCC_OscInitStruct.OscillatorType = RCC_OSCILLATORTYPE_HSE; RCC_OscInitStruct.HSEState = RCC_HSE_ON; RCC_OscInitStruct.HSEPredivValue = RCC_HSE_PREDIV_DIV1; RCC_OscInitStruct.HSIState = RCC_HSI_ON; RCC_OscInitStruct.PLL.PLLState = RCC_PLL_ON; RCC_OscInitStruct.PLL.PLLSource = RCC_PLLSOURCE_HSE; RCC_OscInitStruct.PLL.PLLMUL = RCC_PLL_MUL9; if (HAL_RCC_OscConfig(&RCC_OscInitStruct) != HAL_OK) { Error_Handler(); } // 配置 AHB、APB1、APB2 分频 // AHB = 72MHz, APB1 = 36MHz, APB2 = 72MHz RCC_ClkInitStruct.ClockType = RCC_CLOCKTYPE_HCLK | RCC_CLOCKTYPE_SYSCLK | RCC_CLOCKTYPE_PCLK1 | RCC_CLOCKTYPE_PCLK2; RCC_ClkInitStruct.SYSCLKSource = RCC_SYSCLKSOURCE_PLLCLK; RCC_ClkInitStruct.AHBCLKDivider = RCC_SYSCLK_DIV1; RCC_ClkInitStruct.APB1CLKDivider = RCC_HCLK_DIV2; RCC_ClkInitStruct.APB2CLKDivider = RCC_HCLK_DIV1; if (HAL_RCC_ClockConfig(&RCC_ClkInitStruct, FLASH_LATENCY_2) != HAL_OK) { Error_Handler(); } }这段代码里最容易搞错的是 FLASH_LATENCY 参数。72MHz 主频下，F1 的 Flash 需要 2 个等待周期，也就是 FLASH_LATENCY_2。如果你设成 FLASH_LATENCY_0，程序跑起来会随机死机，而且这种死机很难查，因为不是每次都触发。另一个坑是 HSE 起振失败。有些便宜的最小系统板晶振负载电容不对，HAL_RCC_OscConfig 会返回 HAL_ERROR，然后进 Error_Handler 死循环。这时候你要么换晶振，要么在代码里加一段 HSE 失败后自动切到 HSI 的兜底逻辑，但 HSI 精度差，串口波特率会偏，只能应急。
3.2 GPIO 与 UART 的 HAL 初始化模板
时钟配好之后，外设初始化就是套模板。以 UART1 为例，PA9 做 TX，PA10 做 RX，波特率 115200：
UART_HandleTypeDef huart1; void MX_USART1_UART_Init(void) { huart1.Instance = USART1; huart1.Init.BaudRate = 115200; huart1.Init.WordLength = UART_WORDLENGTH_8B; huart1.Init.StopBits = UART_STOPBITS_1; huart1.Init.Parity = UART_PARITY_NONE; huart1.Init.Mode = UART_MODE_TX_RX; huart1.Init.HwFlowCtl = UART_HWCONTROL_NONE; huart1.Init.OverSampling = UART_OVERSAMPLING_16; if (HAL_UART_Init(&huart1) != HAL_OK) { Error_Handler(); } } // 在 main 里调用 HAL_UART_Init 之前，要先配置 GPIO void HAL_UART_MspInit(UART_HandleTypeDef* uartHandle) { GPIO_InitTypeDef GPIO_InitStruct = {0}; if(uartHandle->Instance == USART1) { __HAL_RCC_USART1_CLK_ENABLE(); __HAL_RCC_GPIOA_CLK_ENABLE(); GPIO_InitStruct.Pin = GPIO_PIN_9; GPIO_InitStruct.Mode = GPIO_MODE_AF_PP; GPIO_InitStruct.Speed = GPIO_SPEED_FREQ_HIGH; HAL_GPIO_Init(GPIOA, &GPIO_InitStruct); GPIO_InitStruct.Pin = GPIO_PIN_10; GPIO_InitStruct.Mode = GPIO_MODE_INPUT; GPIO_InitStruct.Pull = GPIO_NOPULL; HAL_GPIO_Init(GPIOA, &GPIO_InitStruct); } }HAL_UART_MspInit 是 HAL 库的回调机制，HAL_UART_Init 内部会自动调用它。很多人不知道这个机制，把 GPIO 配置写在 main 里，结果 HAL_UART_Init 执行时 GPIO 还没配好，串口发不出数据。正确的顺序是：先调 HAL_UART_Init，它内部会触发 MspInit，你在 MspInit 里配 GPIO 和时钟。这个设计的好处是外设初始化逻辑和板级引脚配置分离，换板子时只改 MspInit 就行。
3.3 中断优先级与 NVIC 配置的注意事项
F1 的中断优先级分组默认是 NVIC_PRIORITYGROUP_4，也就是 4 位抢占优先级，0 位子优先级。HAL 库的 HAL_Init 里会调 HAL_NVIC_SetPriorityGrouping(NVIC_PRIORITYGROUP_4)。如果你用 FreeRTOS，这个分组要改成 NVIC_PRIORITYGROUP_4 之外的值，因为 FreeRTOS 需要子优先级来做临界区管理。具体改法是在 main 里 HAL_Init 之后、RTOS 初始化之前调：
HAL_NVIC_SetPriorityGrouping(NVIC_PRIORITYGROUP_4); // 裸机用这个 // 或者 FreeRTOS 下用： HAL_NVIC_SetPriorityGrouping(NVIC_PRIORITYGROUP_4); // 实际上 FreeRTOS 推荐 GROUP_4 也行，但要注意 configPRIO_BITS中断优先级的坑在于：如果你在中断里调用了 HAL_Delay，而 HAL_Delay 依赖 SysTick 中断，SysTick 的优先级又比当前中断低，那就会死锁。血泪经验是，中断服务函数里尽量只做标志位设置，把耗时操作丢到主循环。HAL 库的 HAL_UART_Receive_IT 和 HAL_UART_Transmit_IT 都是中断方式，但它们的回调函数 HAL_UART_RxCpltCallback 里也不要放 HAL_Delay。
4. 避坑与常见问题排查：那些让你调一晚上的细节
4.1 现象：程序下载后不运行，调试器显示停在 HardFault_Handler
原因：最常见的是启动文件选错，或者链接脚本里的 RAM 大小和实际芯片不符。F103C8T6 只有 20KB RAM，如果你用了 F103ZE 的链接脚本，栈空间分配过大，一上电就溢出。另一个原因是中断向量表偏移没设对，如果你用了 bootloader，APP 区的起始地址不是 0x08000000，就要在 system_stm32f1xx.c 里改 VECT_TAB_OFFSET。
解决：先确认启动文件型号，再检查链接脚本的 RAM 和 Flash 长度。用调试器看 HardFault 时的 LR 和 PC 寄存器值，能定位到具体出错的函数。如果是向量表问题，在 main 里调 SCB->VTOR = FLASH_BASE | VECT_TAB_OFFSET。
4.2 现象：串口打印乱码，但波特率设置没错
原因：HSE 晶振实际频率和代码里写的不一致。比如板子上焊的是 12MHz 晶振，但代码按 8MHz 算 PLL，主频就不是 72MHz，串口分频值跟着错。还有一种可能是 HSI 被误当成了时钟源，HSI 的精度只有 1% 左右，高波特率下累积误差会导致乱码。
解决：用示波器或者逻辑分析仪测一下 PA8 引脚（MCO 输出），看实际主频是多少。如果手头没仪器，就在代码里把 SystemCoreClock 变量通过串口打出来，对比预期值。确认晶振频率后，改 HSE_VALUE 宏和 PLL 倍频系数。
4.3 现象：HAL_UART_Transmit 阻塞发送时程序卡死
原因：HAL_UART_Transmit 默认是阻塞模式，内部用 while 循环等 TXE 和 TC 标志。如果串口引脚被复用成了其他功能，或者 USART 时钟没使能，标志位永远不置位，就死循环了。还有一种情况是发送长度超过了硬件缓冲区，但 F1 的 UART 没有 FIFO，HAL 库会逐字节发，一般不会因为长度卡死。
解决：先确认 __HAL_RCC_USART1_CLK_ENABLE() 被调用了，再检查 GPIO 复用模式是不是 GPIO_MODE_AF_PP。如果用的是重映射引脚，比如 USART1 重映射到 PB6/PB7，还要调 __HAL_AFIO_REMAP_USART1_ENABLE()。
4.4 现象：ADC 采样值跳动很大，或者一直是 0
原因：ADC 的参考电压不稳，或者采样时间设得太短。F1 的 ADC 时钟最高 14MHz，如果 APB2 分频后超过这个值，采样结果会不准。另外，如果引脚配置成了模拟输入但没关掉施密特触发器，也会有漏电流。
解决：在 CubeMX 里把 ADC 时钟分频设成 6 分频或 8 分频，保证 ADC_CLK 不超过 14MHz。采样时间根据信号源阻抗来调，一般设 55.5 个周期以上。引脚模式选 GPIO_MODE_ANALOG，不要选 GPIO_MODE_INPUT。
4.5 现象：I2C 通信卡在 HAL_I2C_Master_Transmit 超时
原因：I2C 总线上没有上拉电阻，或者从设备地址搞错了。F1 的 I2C 外设有个已知问题：在某些错误状态下，BUSY 标志会一直置位，导致后续传输全部超时。这个在官方勘误手册里有提，但很多人不知道。
解决：硬件上确保 SDA 和 SCL 各有 4.7k 上拉电阻。软件上，如果 BUSY 标志卡住，可以尝试手动复位 I2C 外设：先 __HAL_I2C_DISABLE，再 __HAL_I2C_ENABLE，然后重新初始化。更彻底的做法是切到软件 I2C，用 GPIO 模拟时序，虽然慢但稳定。
5. 进阶用法：用 LL 库替代 HAL 做精简工程，以及版本回退技巧
5.1 LL 库与 HAL 库的取舍
V1.8.0 里同时带了 HAL 和 LL 两套驱动。HAL 的好处是抽象层次高，移植方便，但代码体积大，中断里执行时间长。LL 库更接近寄存器操作，适合对性能和代码尺寸敏感的场景。比如你要做一个 10kHz 的 PWM 输出，用 HAL 的 HAL_TIM_PWM_Start 会有几十个周期的开销，而 LL 库直接写 TIMx->CCR1 寄存器，几乎零开销。
我一般会在同一个工程里混用：初始化用 HAL，因为 CubeMX 生成的就是 HAL 代码；中断服务函数里用 LL 操作寄存器，减少执行时间。比如串口接收中断：
void USART1_IRQHandler(void) { if (LL_USART_IsActiveFlag_RXNE(USART1) && LL_USART_IsEnabledIT_RXNE(USART1)) { uint8_t data = LL_USART_ReceiveData8(USART1); // 直接存到环形缓冲区，不调 HAL 的回调 ringbuf_put(&rx_buf, data); } }这样中断里只有几行代码，不会因为 HAL 的回调层层嵌套导致响应变慢。但要注意，LL 库的头文件要单独包含 stm32f1xx_ll_usart.h，而且 LL 和 HAL 不能同时操作同一个外设的同一个寄存器，否则状态会乱。
5.2 从 V1.8.0 回退到旧版本的注意事项
有些老项目用的是 V1.6.0 或 V1.7.0 的 HAL，直接换成 V1.8.0 可能会编译报错，因为 HAL 的 API 有细微变化。比如 V1.8.0 里 HAL_GPIO_Init 的参数检查更严格，如果你传了非法的 GPIO_Pin 值，会直接进 Error_Handler，而旧版本可能只是忽略。
回退或升级时，先看固件包根目录下的 Release_Notes.html，里面列了每个版本的变化。重点看 HAL 的 API 变更部分。如果只是小版本升级，一般改几个宏定义就行。如果是大版本跨越，建议用 CubeMX 重新生成工程，然后把你的应用代码挪过去，不要手动改 HAL 源码。
5.3 验证固件包完整性的一个习惯
最后说一个我自己的习惯：每次拿到新的固件包，解压后先跑一遍官方例程，确认 HAL 版本和芯片匹配。具体做法是打开 Projects\STM32F103RB-Nucleo\Examples\GPIO\GPIO_IOToggle 这个例程，编译下载，看板子上的 LED 能不能正常闪烁。如果能闪，说明固件包完整、工具链配置正确、芯片型号选对了。这一步花不了五分钟，但能省掉后面很多玄学问题。从那以后我每次换固件包版本，都强制走一遍这个例程验证，希望帮到你。
本文还有配套的精品资源，点击获取
