从零配置STM32 HAL库：cubeMX 6.12安装、固件包离线导入与F103点灯实战

前言

开发 STM32 主要有三种路子：最原始但效率拉满的寄存器开发；效率次之、难度适中的标准库开发；以及上手最简单但程序效率相对较低的 HAL 库开发。

如果你刚开始接触 STM32 ，直接拥抱 HAL 库意味着你可以“速通”外设配置，快速看到效果。但这会让你错失大量与底层硬件亲密接触的机会，代码功力很难得到真正锤炼。所以对新手来说，我还是建议先从标准库学起，由下往上搭建知识体系。而在企业开发中，为了团队协作效率与环境统一，HAL 库确实是主流选择。

提到 HAL 库的开发效率，就不能不提 cubeMX ——这款 ST 官方出品的图形化配置工具，能省去繁琐的库函数导入与外设初始化步骤。只需要动动鼠标，就能生成一个结构干净的 HAL 库工程。本文就来手把手带你：安装 cubeMX、配置相关固件包，并完成 STM32 基本工程环境的搭建。

Part 1 开始之前

HAL 库本质上和标准库一样，是一套函数库， cubeMX 只是一个图形化代码生成器。因此最终我们还是需要 Keil 来完成编译。请确保你的 Keil 环境已经就绪，并且安装好了对应芯片的设备包。如果还没配置好，可以参照相关指引完成 Keil 的安装与芯片包支持。

相关资料包可以直接准备好，里面包含了 cubeMX 安装程序及部分常用芯片的离线固件包。由于 cubeMX 官方下载门槛略高，直接从资料包里获取会更省心。

Part 2 cubeMX 的安装

要使用 HAL 库，第一件事自然是搭好开发环境，这就需要先安装 cubeMX 。

找到资料包中的 cubeMX 文件夹，双击 SetupSTM32CubeMX-6.12.1-Win.exe 启动安装引导。

在弹出的安装模式选择窗口中，选择 “Install for me only (recommended)” 即可。

接着点击 Next 进入许可协议界面。

勾选 “I accept the terms of this license agreement.” 同意协议，并点击 Next。

在新的页面中，继续勾选 “I have read and understood the ST Terms of Use.”，然后点击 Next。

接下来需要选择安装路径。注意 cubeMX 对中文非常敏感，路径中绝对不能出现中文或特殊字符。设置好后点击 Next。

如果点击 Next 后弹出“目录已存在”的警告，确认后覆盖即可。如果提示“目录非空且不是之前版本的安装目录”，则需要清空该文件夹或新建一个空目录。

接下来是快捷方式选项，建议全勾上，方便在开始菜单和桌面都能找到。然后点击 Next。

随后进入文件复制阶段，耐心等待进度条走完。

进度走到 100% 后，点击 Next，然后点击 Done 即可完成安装。

Part 3 cubeMX 的更新与固件包安装

与很多 IDE 不同， cubeMX 的版本最好保持较新的状态。新版本向下兼容旧工程，反之则不行。

打开 cubeMX ，在菜单栏点击 Help。

在下拉菜单中，选择 Check for Updates。

在弹出的 Check Update Manager 窗口中，勾选需要更新的 cubeMX 本体或固件包，然后点击 Install。如果列表为空，说明当前已是最新版。

下载过程可能会因为网络问题失败，必要时得借助一些正向代理工具。如果实在更新不了也不用慌，资料包里提供的版本已经很新了。

固件包的概念

固件包是 cubeMX 支持特定 STM32 系列芯片的基础。比如你想生成 STM32F1 的 HAL 库工程，就必须先装好 F1 的固件包。安装方式分为在线安装和离线安装。

在线安装

在 Help 菜单中找到并点击 Manage embedded software packages。

打开 Embedded Software Packages Manager 窗口。在这里可以找到几乎所有的 STM32 系列。以 F1 为例，展开 STM32F1。

勾选你想要的版本（推荐最新版），然后点击 Install。

下载可能会因网络卡住，如果一直失败，可以跳到下面的离线安装。

安装成功后，固件包前面的小框会变色。

解决潜在的中文路径隐患

无论你用哪种方式安装，都必须确保 Windows 用户名没有中文。打开 C:\Users目录（显示为“用户”但也只是显示名，本质是 Users），确认你的用户文件夹名是纯英文。如果包含中文， cubeMX 生成代码时报错几乎是必然的，需要新建一个英文账户来操作。

查看文件夹属性，会发现“用户”对应的真实路径其实是 C:\Users。

离线安装

你需要知道一个关键路径：C:\Users\你的用户名\STM32Cube\Repository。这个目录就是 cubeMX 存放固件包的地方。

直接将资料包中 cubeMX固件包 文件夹里提供的常用系列固件包，复制到上面那个 Repository 目录下。

复制完成后重启 cubeMX，固件包就被识别了。

如果离线包没有你需要的型号，可以去 ST 在 GitHub 上的开源主页下载。项目主页地址可以在 ST 官方页面找到（主页往下滑就能看到所有系列的固件包）。

比如点击 STM32CubeF7 进入仓库，然后点击绿色的 Code 按钮，选择 Download ZIP 即可。

将下载并解压得到的 STM32CubeF7-master 文件夹复制到 Repository 目录，然后重启 cubeMX 就会自动加载。

Part 4 cubeMX 新建工程（以 STM32F103C8T6 为例）

前面的准备工作都就绪后，就该创建真正的工程了。

芯片选型

启动 cubeMX ，在首页点击 ACCESS TO MCU SELECTOR。

在弹出的芯片选择器中，左上角搜索框输入 STM32F103C8T6。

在结果列表中双击该芯片，即进入配置界面。

基本配置：时钟、调试接口与 GPIO

工程创建完毕，先把一些“保底配置”做好，让芯片能跑起来。

1. 使能外部高速时钟 (HSE)

在左侧 Categories 栏找到 System Core > RCC。在 RCC Mode and Configuration 面板中，将 High Speed Clock (HSE) 设置为 Crystal/Ceramic Resonator。

2. 配置系统时钟

切换到顶部的 Clock Configuration 选项卡。这块看起来复杂，但 cubeMX 让它变得很简单。看不懂时钟树也没关系，直接在 HCLK (MHz) 输入框里敲入 72 并回车， cubeMX 就会自动为你配置好锁相环 (PLL) 分频/倍频参数，生成 72MHz 系统主时钟。

注意：输入频率不要超过芯片手册规定的最高工作频率，否则芯片可能罢工甚至永久损坏。

3. 配置调试接口

回到 Pinout & Configuration 选项卡。在 System Core 下点击 SYS，将 Debug 选项配置为 Serial Wire。否则 PA13 和 PA14 可能被禁用，导致下次烧录失败。

4. 配置 GPIO 点灯

完成了核心配置，我们点个灯验证一下。在右侧芯片引脚图上找到 PC13 （通常接最小系统板的 LED ），单击它，在弹出的菜单中选择 GPIO_Output。

接着在左侧 Categories 栏点击 GPIO，在下方列表中找到并选中刚才配置的 PC13。在 GPIO Configuration 面板中：

• GPIO output level: 可选 Low 或 High，决定上电后的初始电平。
• GPIO mode: 选 Output Push Pull (推挽输出)，具备直接驱动 LED 的能力。
• GPIO Pull-up/Pull-down: 根据需要选择，一般选 No pull-up and no pull-down。
• Maximum output speed: 点灯对速度要求不高，选 Low 就行。

工程生成

点击 Project Manager 选项卡。

1. Project Name: 填入 LED （不要有中文）。
2. Project Location: 选定你的工程根目录，整个路径不能有中文。
3. Toolchain / IDE: 必须选择 MDK-ARM，Min Version 默认即可。

接着切换到 Code Generator 选项卡：

1. 在 STM32Cube MCU packages and embedded software packs 区域，勾选 Copy all used libraries into the project folder。
2. 在 Generated files 区域，勾选 Generate peripheral initialization as a pair of '.c/.h' files per peripheral （为每个外设单独生成 .c/.h 文件）。

所有配置完成后，回到顶部，点击 GENERATE CODE。

如果生成失败，八成是因为路径包含中文或指定芯片的固件包没有正确安装。如果生成成功，会弹出 Code Generation 对话框，点击 Open Project 即可自动用 Keil 打开。

代码验证与点灯

在 Keil 中，直接点击编译（Build），通常应该是 0 Error(s), 0 Warning(s)。这说明 HAL 库的纯净工程已经搭建成功。

打开 Application/User/Core/main.c 文件，找到主循环：

  /* Infinite loop */
  /* USER CODE BEGIN WHILE */
  while (1)
  {
    /* USER CODE END WHILE */

    /* USER CODE BEGIN 3 */
  }
  /* USER CODE END 3 */

特别提醒： cuBeMX 生成的代码中有很多类似 /* USER CODE BEGIN ... */ 和 /* USER CODE END ... */ 的标记，你的代码一定要写在这两个标记之间。否则，下次重新生成代码时，写在别处的代码就会被无情覆盖。

在 while 循环内加入点灯逻辑：

  /* USER CODE BEGIN 3 */
  HAL_GPIO_TogglePin(GPIOC, GPIO_PIN_13);
  HAL_Delay(500);
  /* USER CODE END 3 */

这段代码实现了 PC13 引脚电平每 500 毫秒翻转一次，达到 LED 闪烁的效果。

再次编译并下载到开发板。如果一切正常，你应该能看到 LED 灯稳定地闪烁。

如果 LED 没有反应，可以检查硬件连接、调试器连接，或进入调试模式观察程序运行状态。

至此，一个基于 cubeMX 的 STM32 HAL 库工程就算搭建完毕并跑通了第一个程序。

结语

cubeMX 的强大之处在于它能图形化地处理几乎所有 STM32 外设的初始化配置，这确实为我们省下了大把敲初始化代码的时间。但 HAL 库对底层高度封装，也给后续的深度定制带来了一点小麻烦。

至于选哪个库，完全取决于你的项目和自身阶段。希望本篇教程帮你顺利跨过了环境搭建这道坎。感谢阅读！

如果你觉得本文对你有帮助，欢迎点赞、收藏并转发给身边需要的伙伴。也欢迎在评论区交流你在搭建环境时遇到的各种疑难杂症。

在云栈社区，你还能找到更多经过验证的 STM32 避坑指南与嵌入式技术文档，助你在嵌入式开发之路上少走弯路。