企业官网建设流程全解析

简介：STM32Cube_FW_F1_V1.8.0 是意法半导体面向 STM32 F1 系列微控制器推出的官方固件库封装包，配套 STM32CubeMX 图形化配置工具，适用于使用 Keil、IAR 进行嵌入式开发的初学者与工程师。它通过 HAL 与 LL 两层标准化 API，帮助开发者快速完成时钟、外设初始化并自动生成工程代码，减少手动配置寄存器的工作量。压缩包共约 2000 个文件，整体 109.82MB，以 C 源码、头文件、HTML 文档、JavaScript 页面及汇编启动文件为主，另含 Keil 与 IAR 工程文件、链接脚本、示例固件与说明文档，覆盖 F1 全系外设驱动与中间件。目前已有 3445 人学习下载。借助该库，读者可获得完整的驱动源码、外设配置示例与工程模板，便于在工业控制、消费电子及物联网项目中直接复用，并对照官方文档排查初始化与编译问题，提升开发效率与代码可移植性。

1. 拿到 F1 的 V1.8.0 固件包，先搞清楚它到底封装了什么

很多人第一次接触 STM32Cube_fw_F1_V1.8.0，是在 CubeMX 里点了几下生成代码，然后发现工程目录里多出一堆 HAL 驱动文件，却说不清这些文件和标准外设库到底什么关系。这个包本质上是 ST 官方为 F1 系列（STM32F103、F105、F107 等）提供的一整套固件封装：底层 HAL 驱动、LL 驱动、CMSIS 设备头文件、板级支持包 BSP、以及一堆按外设分类的例程。CubeMX 负责图形化配置引脚和时钟，生成初始化代码，而真正干活的函数实现全在这个固件包里。它解决的核心问题是：不用再对着寄存器手册一行行写配置，把外设初始化、中断处理、时钟树配置这些重复劳动封装成可移植的 API。适合谁？适合正在用 F103 做产品、又不想被标准库绑死、希望后续能平滑迁移到 F4/F7 的嵌入式开发者。但要注意，V1.8.0 是 F1 系列较新的一个版本，和早期 V1.0.x 在 HAL 层有 API 变动，直接拿旧教程抄代码大概率编译不过。

2. 固件包目录结构与 CubeMX 生成工程的对应关系

2.1 顶层目录里哪些该进工程、哪些只做参考

解压 STM32Cube_fw_F1_V1.8.0 后，顶层通常能看到几个关键目录。Drivers 放的是 CMSIS 和 STM32F1xx_HAL_Driver，这是必须进工程的；Middlewares 放的是 USB、FatFs、FreeRTOS 等中间件，按需取用；Projects 里是按开发板分类的例程，每个例程都有 MDK-ARM、STM32CubeIDE、IAR 等不同工具链的工程文件；Utilities 是 BSP 和组件驱动。我一般只把 Drivers 和 Middlewares 里实际用到的部分拷进自己的工程树，Projects 只用来对照参考，不直接改。

一个典型的 CubeMX 生成工程目录长这样：

MyProject/ ├── Core/ │ ├── Inc/ │ │ ├── main.h │ │ ├── stm32f1xx_hal_conf.h │ │ └── stm32f1xx_it.h │ └── Src/ │ ├── main.c │ ├── stm32f1xx_it.c │ └── system_stm32f1xx.c ├── Drivers/ │ ├── CMSIS/ │ │ ├── Device/ST/STM32F1xx/Include/ │ │ └── Include/ │ └── STM32F1xx_HAL_Driver/ │ ├── Inc/ │ └── Src/ ├── Middlewares/ └── MDK-ARM/ 或 STM32CubeIDE/

关键点在于 stm32f1xx_hal_conf.h 这个文件，它决定哪些 HAL 模块被编译进来。CubeMX 生成时会根据你使能的外设自动裁剪，但手动改工程时经常忘了同步这个文件，导致链接时报一堆 undefined reference。

2.2 用 CubeMX 重新生成时如何锁定 V1.8.0 的 HAL 版本

CubeMX 本身不绑定固件包版本，它是在你创建工程时从本地固件库列表里选。如果本地装了多个 F1 固件包，需要在 CubeMX 的 Help → Manage embedded software packages 里确认 STM32Cube MCU Package for STM32F1 的版本是 V1.8.0。选中后新建工程，生成的代码就会引用这个版本的 HAL。

但这里有个坑：CubeMX 生成的工程默认只拷贝用到的 HAL 源文件，如果你后续手动添加了外设初始化代码，却没有在 CubeMX 里重新生成，那新外设的 HAL 源文件不会自动加进工程。常见做法是，在 CubeMX 里把所有可能用到的外设都先使能一遍，生成后再手动裁剪，或者干脆把 STM32F1xx_HAL_Driver/Src 下所有 .c 文件都加进工程，靠链接器剔除未使用的函数。后者编译慢一点，但省心。

2.3 从标准库迁移到 HAL 时最容易被忽略的三个文件

如果你是从旧的标准外设库（SPL）迁过来的，有三个文件必须重点看。第一个是 stm32f1xx_hal_conf.h，里面有一堆 #define HAL_XXX_MODULE_ENABLED，少一个就编译不过。第二个是 stm32f1xx_hal_msp.c，MSP 是 MCU Support Package 的缩写，负责外设时钟使能和 GPIO 复用配置，CubeMX 会自动生成，但手动改的时候容易漏掉。第三个是 stm32f1xx_it.c，中断服务函数从 SPL 的写法变成了 HAL 的统一入口，比如 SysTick_Handler 里要调 HAL_IncTick()，否则 HAL_Delay() 会卡死。

/* stm32f1xx_it.c 中 SysTick 中断必须这样写 */ void SysTick_Handler(void) { HAL_IncTick(); /* 必须调用，否则 HAL_Delay 永远阻塞 */ HAL_SYSTICK_IRQHandler(); }

逻辑说明：HAL_IncTick() 负责累加全局 tick 计数，HAL_Delay() 就是靠轮询这个计数实现延时的。如果中断里不调用它，uwTick 永远不增长，HAL_Delay 就会死循环。参数上没什么可调的，但要注意 HAL_SYSTICK_IRQHandler() 在 V1.8.0 里是弱定义，一般不需要改。

3. 用 CubeMX + V1.8.0 固件包点灯的最小可复现流程

3.1 新建工程到生成代码的完整操作链

打开 CubeMX，选择 MCU 型号，比如 STM32F103C8T6。在 Pinout 视图里找到 PC13，设为 GPIO_Output。在 Clock Configuration 里把 HSE 设为 Crystal/Ceramic Resonator，然后配置 PLL，让 SYSCLK 跑到 72MHz。在 Project Manager 里给工程起名，Toolchain 选 MDK-ARM 或 STM32CubeIDE，Code Generator 里勾上“Copy only necessary library files”。点 GENERATE CODE，CubeMX 会从 V1.8.0 固件包里抽取需要的 HAL 文件，生成完整工程。

生成的 main.c 里，MX_GPIO_Init() 已经帮你配好了 PC13 的输出模式。你只需要在 while(1) 里加两行：

/* main.c 主循环里闪烁 PC13 */ while (1) { HAL_GPIO_TogglePin(GPIOC, GPIO_PIN_13); /* 翻转 PC13 电平 */ HAL_Delay(500); /* 延时 500ms */ }

逻辑说明：HAL_GPIO_TogglePin 内部读 ODR 寄存器再取反写回，比先读再写更原子。HAL_Delay 的参数单位是毫秒，依赖 SysTick 中断。注意 PC13 在 F103 上驱动能力有限，只能灌电流，接 LED 时要串限流电阻，别直接灌。

3.2 时钟树配置里 PLL 倍频参数怎么算

F103 的时钟树是：HSE（通常 8MHz）→ PLL 输入分频 → PLL 倍频 → SYSCLK。CubeMX 里 HSE 选 8MHz，PLL Source 选 HSE，PLL Mul 选 9 倍频，得到 72MHz。AHB 不分频，APB1 分频系数 2（最高 36MHz），APB2 不分频（72MHz）。这些参数在 Clock Configuration 界面里是图形化的，但底层对应的是 RCC_CFGR 寄存器的位域。

如果你用的是 12MHz 晶振，PLL Mul 要改成 6，才能得到 72MHz。改完之后 CubeMX 会自动重新计算各总线频率，如果某个外设频率超限，它会标红。常见错误是 APB1 上挂了定时器，却忘了 APB1 定时器时钟是总线频率的 2 倍（当分频系数不为 1 时），算波特率或定时周期时容易翻车。

3.3 生成后用串口打印验证 HAL 版本号

想确认当前工程用的确实是 V1.8.0 的 HAL，可以在 main 里打印 HAL_GetHalVersion() 的返回值。先配好 USART1，然后在 main 初始化后加：

/* 通过串口打印 HAL 版本，波特率 115200 */ uint32_t hal_ver = HAL_GetHalVersion(); printf("HAL Version: %lu.%lu.%lu\r\n", (hal_ver >> 24) & 0xFF, /* 主版本 */ (hal_ver >> 16) & 0xFF, /* 次版本 */ (hal_ver >> 8) & 0xFF); /* 补丁版本 */

逻辑说明：HAL_GetHalVersion() 返回一个 32 位整数，高字节是主版本，依次往下。V1.8.0 对应返回 0x01080000。printf 需要重定向 fputc 到 USART1，否则不会输出。参数上注意波特率要和串口工具一致，F103 在 72MHz 下 USART1 挂 APB2，波特率寄存器算出来的误差很小。

4. 避坑：V1.8.0 固件包在 CubeMX 工程里最容易翻车的五个点

4.1 现象：编译报错 “stm32f1xx_hal.h: No such file or directory”

原因：CubeMX 生成工程时，头文件搜索路径没有正确添加，或者你手动移动了 Drivers 目录的位置。V1.8.0 的 HAL 头文件在 Drivers/STM32F1xx_HAL_Driver/Inc 下，CMSIS 设备头文件在 Drivers/CMSIS/Device/ST/STM32F1xx/Include 下。解决：在 IDE 的 include path 里把这两个路径加进去，同时确认 stm32f1xx_hal_conf.h 所在的 Core/Inc 也在路径里。

4.2 现象：HAL_Delay 卡死，程序停在 while 循环里出不来

原因：SysTick 中断没有正确使能，或者中断优先级配置被其他中断打乱。V1.8.0 的 HAL 默认用 SysTick 做时基，HAL_Init() 里会调 HAL_InitTick()。如果你在 HAL_Init() 之前就关了全局中断，或者后来改了 SysTick 优先级导致它被屏蔽，HAL_Delay 就会死等。解决：确认 stm32f1xx_it.c 里有 SysTick_Handler，且里面调了 HAL_IncTick()。检查 NVIC 优先级分组，别把 SysTick 优先级设得比还高的抢占优先级还低。

4.3 现象：串口收发正常，但进不了接收中断

原因：V1.8.0 的 HAL 串口中断处理和标准库不同，它用 HAL_UART_Receive_IT() 启动接收，然后在 USART1_IRQHandler 里调 HAL_UART_IRQHandler()。如果你只写了中断服务函数却没调 HAL 的 IRQHandler，或者没在初始化后调用 HAL_UART_Receive_IT()，中断就不会触发。解决：在 main 里初始化完串口后，先调一次 HAL_UART_Receive_IT(&huart1, &rx_byte, 1)，然后在 stm32f1xx_it.c 的 USART1_IRQHandler 里调 HAL_UART_IRQHandler(&huart1)。

4.4 现象：GPIO 输出电平不对，万用表量出来一直是高或一直是低

原因：CubeMX 里 GPIO 模式选错了。比如你想推挽输出，却选成了开漏；或者你想输出高电平点亮 LED，却忘了在 GPIO 初始化里设默认电平。V1.8.0 的 HAL_GPIO_Init 里，GPIO_InitStruct.Pull 和 GPIO_InitStruct.Mode 要匹配。解决：推挽输出选 GPIO_MODE_OUTPUT_PP，开漏选 GPIO_MODE_OUTPUT_OD。默认电平在 HAL_GPIO_WritePin 里设，或者在 CubeMX 的 GPIO 配置界面里直接指定 Initial Output Level。

4.5 现象：从 V1.7.0 升级到 V1.8.0 后，原来的 USB 代码编译报错

原因：V1.8.0 对 USB 中间件和 HAL PCD 驱动做了 API 调整，比如某些回调函数的参数类型变了，或者结构体成员改名了。解决：不要直接替换 Drivers 目录就完事，要把 Middlewares/ST/STM32_USB_Device_Library 也一起更新到配套版本。然后对照 V1.8.0 的例程，把回调函数签名改过来。如果项目紧，可以先锁在 V1.7.0，等 USB 功能稳定后再迁。

5. 进阶：用 LL 驱动绕过 HAL 的性能损耗，以及版本锁定技巧

5.1 什么时候该用 LL 而不是 HAL

V1.8.0 固件包里同时包含 HAL 和 LL 两套驱动。HAL 的好处是抽象层次高、可移植性好，但代价是代码体积大、执行路径长。比如 HAL_GPIO_TogglePin 内部有参数检查、状态判断，而 LL_GPIO_TogglePin 直接操作寄存器。在中断频率高或者时序要求严的场景，比如软件模拟 SPI、高速 PWM 捕获，我一般会混用 LL。CubeMX 生成代码时可以选择“LL”模式，但更常见的做法是 HAL 初始化 + LL 操作。

/* 混用示例：HAL 初始化 GPIO，LL 翻转电平 */ MX_GPIO_Init(); /* HAL 初始化，配好时钟和模式 */ while (1) { LL_GPIO_TogglePin(GPIOC, LL_GPIO_PIN_13); /* 直接操作寄存器，无参数检查 */ LL_mDelay(500); /* LL 的延时，基于 SysTick */ }

逻辑说明：LL_GPIO_TogglePin 是个宏或者内联函数，直接写 BSRR 寄存器，比 HAL 快很多。LL_mDelay 和 HAL_Delay 共用 SysTick，但实现更轻量。参数上注意 LL 的引脚定义是 LL_GPIO_PIN_x，和 HAL 的 GPIO_PIN_x 数值一样，但类型不同，别混用。

5.2 把固件包版本写进工程，避免团队协作时版本漂移

团队里几个人共用一套代码，最怕的是有人用 V1.8.0，有人用 V1.7.0，编译出来的行为不一致。我的习惯是在工程根目录放一个 version.md，记录当前用的固件包版本、CubeMX 版本、以及关键配置截图。同时在代码里加一个编译期断言：

/* 在 main.h 里加版本检查，编译期报错 */ #if (HAL_GetHalVersion() != 0x01080000) #error "HAL version mismatch! Expected V1.8.0" #endif

但 HAL_GetHalVersion() 是运行时函数，不能用在预处理里。更实际的做法是直接检查 stm32f1xx_hal.h 里的 HAL_VERSION 宏：

#include "stm32f1xx_hal.h" #if (HAL_VERSION_MAIN != 1) || (HAL_VERSION_SUB1 != 8) || (HAL_VERSION_SUB2 != 0) #error "HAL version mismatch! Expected V1.8.0" #endif

逻辑说明：HAL_VERSION_MAIN、HAL_VERSION_SUB1、HAL_VERSION_SUB2 是 V1.8.0 头文件里定义的宏，编译时就能检查。这样任何人拉了代码，只要固件包版本不对，编译直接失败，比运行时发现问要好。

5.3 用 CubeMX 的 .ioc 文件做配置版本管理

.ioc 文件是 CubeMX 工程的配置描述，里面记录了引脚分配、时钟树、外设参数。把它和代码一起提交到版本控制，每次改配置都留痕。但要注意，.ioc 文件里不包含固件包版本信息，它只记录你选了哪个系列的包。所以换固件包版本时，.ioc 不会自动更新，需要手动在 CubeMX 里重新选一次，再生成代码。我一般会在 .ioc 同目录放一个 readme，写明“本工程基于 STM32Cube_fw_F1_V1.8.0 生成，CubeMX 版本不低于 6.x”。

最后说个血泪教训：有一次赶项目，直接从别人那拷了一份 F1 的 HAL 驱动，没注意是 V1.6.0 的，结果 USB 枚举死活不成功，查了两天才发现是版本不对。从那以后，我拿到任何 F1 工程，第一件事就是看 stm32f1xx_hal.h 里的版本宏，确认是不是 V1.8.0。这个习惯帮我省了很多后悔药。希望帮到你。

本文还有配套的精品资源，点击获取