从零开始搭建STM32工程：深入理解Keil MDK下的C项目构建机制
你有没有过这样的经历？拿到一块新的STM32开发板，兴冲冲打开Keil，想新建一个空工程写点代码点亮LED，结果编译报错一堆“undefined symbol Reset_Handler”、“SystemInit not found”，甚至程序下载进去后根本不运行？
别急——这并不是你的代码有问题，而是你还没真正搞清楚嵌入式项目的底层骨架是如何搭建的。大多数初学者依赖现成例程或CubeMX生成代码，却对背后的关键组件一知半解。一旦脱离模板，寸步难行。
今天，我们就抛开一切自动化工具，手把手带你用Keil MDK 从零创建一个标准的 STM32 C 工程，并深入剖析每一个核心模块的技术本质。目标是让你不仅能“跑起来”，还能说得出“为什么能跑”。
为什么不能直接写main()就行？
在PC上写C程序，main()是起点；但在嵌入式系统中，CPU加电后的第一件事，并不是跳转到main()，而是执行一系列底层初始化操作：
- 设置堆栈指针（SP）
- 初始化静态变量（.data段复制、.bss清零）
- 配置时钟系统
- 建立中断向量表
这些任务都发生在main()调用之前，由几个关键文件协同完成。忽略它们，哪怕最简单的GPIO控制也无法正常工作。
所以，一个可运行的STM32工程，至少需要以下四个核心组成部分：
1. 启动文件（Startup File）
2. CMSIS层支持（core + system）
3. 正确的链接脚本（Scatter Load File）
4. Keil中的目标配置与编译选项
下面我们逐个拆解。
关键模块详解：每个字节都至关重要
1. 启动文件 —— MCU启动的“第一把钥匙”
当你按下复位按钮，STM32芯片从Flash地址0x08000000开始取指令。这个地方存放的，正是中断向量表，而它的实现就在启动文件里。
以startup_stm32f103xb.s为例（适用于STM32F103C8T6等64KB Flash型号），它本质上是一段汇编代码，主要做三件事：
（1）定义中断向量表
AREA RESET, DATA, READONLY EXPORT __Vectors __Vectors DCD __initial_sp ; 栈顶地址 DCD Reset_Handler ; 复位处理函数 DCD NMI_Handler DCD HardFault_Handler ...⚠️ 注意：第一个入口必须是
__initial_sp，也就是RAM末尾地址（如0x20005000），这是硬件规定的启动流程。
（2）实现Reset_Handler
Reset_Handler PROC EXPORT Reset_Handler [WEAK] IMPORT SystemInit IMPORT __main LDR R0, =SystemInit BLX R0 ; 先调用SystemInit() LDR R0, =__main BX R0 ; 再跳转到__main（最终进入main） ENDP这里的关键在于：SystemInit()必须先于main()执行，否则时钟未配置，外设全废。
（3）提供弱符号中断服务例程
所有中断处理函数默认为空且声明为[WEAK]，意味着你可以用自己的函数覆盖它：
NMI_Handler PROC EXPORT NMI_Handler [WEAK] B . ; 空循环 ENDP📌常见坑点提醒：
- 若使用了错误的启动文件（比如把xc当作xb使用），Flash大小定义不符，可能导致.text段溢出；
- 如果删除了SystemInit的调用，HSE不会启用，默认使用HSI 8MHz，影响定时精度。
2. CMSIS 层 —— 统一内核编程接口的标准
CMSIS（Cortex Microcontroller Software Interface Standard）是Arm为Cortex-M系列推出的一套标准化软件接口，目的就是让不同厂商的MCU在访问内核寄存器时保持一致。
它的两大核心文件是：
core_cm3.h（针对M3内核）
这个头文件定义了：
- 内核外设结构体（NVIC、SCB、SysTick等）
- 访问内联函数（如__enable_irq()、__disable_irq()）
- 数据类型统一（uint32_t等）
例如，你想关闭全局中断，只需调用：
__disable_irq(); // 编译后展开为 CPSID i无需再记晦涩的汇编指令。
system_stm32f1xx.c和.h
这是ST基于CMSIS扩展的系统级初始化文件，其中最重要的函数就是SystemInit()。
我们来看一段关键代码：
void SystemInit(void) { /* 复位RCC到默认状态 */ RCC->CR |= (uint32_t)0x00000001; // 开启HSI RCC->CFGR &= (uint32_t)0xF8FF0000; // 清除时钟配置位 RCC->CR &= (uint32_t)0xFEF6FFFF; // 关闭PLL、CSS、HSE旁路 RCC->CR &= (uint32_t)0xFFFBFFFF; // 关闭HSE RCC->CFGR &= (uint32_t)0xFF80FFFF; // 清除USB预分频 ... #ifdef VECT_TAB_SRAM SCB->VTOR = SRAM_BASE | VECT_TAB_OFFSET; #else SCB->VTOR = FLASH_BASE | VECT_TAB_OFFSET; #endif }✅ 提示：如果你换了外部晶振（比如原来是8MHz HSE，现在换成16MHz），一定要修改
HSE_VALUE宏，否则SystemCoreClock会算错！
3. 链接脚本（.sct 文件）—— 决定代码住哪儿
链接脚本决定了程序各部分在物理内存中的布局。Keil MDK 使用.sct文件进行分散加载（scatter loading）。
对于 STM32F103C8T6（64KB Flash + 20KB RAM），典型的.sct配置如下：
LR_IROM1 0x08000000 0x00010000 { ; Load Region: Flash (64KB) ER_IROM1 0x08000000 0x00010000 { *.o(.vectab) ; 向量表 *(+RO) ; 代码和只读数据 } RW_IRAM1 0x20000000 0x00005000 { ; Run Region: SRAM (20KB) *(+RW) ; 已初始化变量 (.data) *(+ZI) ; 未初始化变量 (.bss) .stack +0 UNINIT 0x00000400 ; 堆栈区预留1KB，不初始化 } }🔍 解读要点：
-.text和.rodata放在 Flash 中；
-.data在程序启动时从Flash复制到SRAM；
-.bss在启动时被清零；
-.stack和.heap明确分配空间，避免栈溢出。
🚨致命错误示例：
若误将 IROM1 Size 设为0x20000（128KB），但实际Flash只有64KB，则超出部分无法烧录，程序可能崩溃或无法下载。
实战步骤：一步步创建你的第一个空工程
下面是在 Keil uVision5 中手动创建 STM32F103C8T6 工程的完整流程。
第一步：新建项目
- 打开 Keil μVision；
- Project → New μVision Project；
- 选择保存路径，命名为
BareMetal_LED； - 选择芯片型号：
STM32F103C8（确保已安装 STM32F1xx DFP 包）；
💡 如何确认DFP已安装？菜单栏 Pack Installer → 搜索 “STM32F1” → 查看是否已安装最新版本。
第二步：添加必要源文件
右键 “Source Group 1” → Add Existing Files…
你需要添加以下三个关键文件（可在 Keil 安装目录或 ST 提供的库中找到）：
-startup_stm32f103xb.s（启动文件）
-system_stm32f1xx.c（系统初始化）
- 自己创建的main.c
✅ 推荐做法：建立清晰目录结构，如：
Project/ ├── Core/ │ ├── startup_stm32f103xb.s │ ├── system_stm32f1xx.c │ └── inc/ │ └── system_stm32f1xx.h ├── main.c └── Output/ Debug/第三步：编写最简main.c
#include "stm32f1xx.h" int main(void) { // 使能GPIOA时钟 RCC->APB2ENR |= RCC_APB2ENR_IOPAEN; // 配置PA5为推挽输出（LED） GPIOA->CRL &= ~GPIO_CRL_MODE5; GPIOA->CRL |= GPIO_CRL_MODE5_1; // 输出模式，最大速度10MHz GPIOA->CRL &= ~GPIO_CRL_CNF5; // 推挽输出 while (1) { GPIOA->BSRR = GPIO_BSRR_BR5; // PA5拉低 for(volatile int i = 0; i < 1000000; i++); GPIOA->BSRR = GPIO_BSRR_BS5; // PA5拉高 for(volatile int i = 0; i < 1000000; i++); } }📌 注意：这里直接操作寄存器，不依赖HAL或标准外设库。
第四步：配置项目选项（Options for Target）
点击魔术棒图标，进入配置界面：
Target 页
- Xtal(MHz): 8.0 （根据你的外部晶振设置）
- Memory Model: Small（适合小内存设备）
Output 页
- ✔ Create HEX File（方便后续烧录）
C/C++ 页
- Define:
STM32F103xB,USE_STDPERIPH_DRIVER（即使不用库也建议定义） - Include Paths: 添加包含路径，如
./Core/inc
Debug 页
- Use: ST-Link Debugger
- Settings → Flash Download → Update Target before Debugging
Linker 页
- Use Memory Layout from Target Dialog（勾选后自动应用IROM/IRAM设置）
- 或者自定义 Scatter File（推荐高级用户使用）
常见问题排查清单
| 现象 | 可能原因 | 解决方法 |
|---|---|---|
编译报错undefined symbol SystemInit | system_stm32f1xx.c未加入项目 | 添加该文件到Source Group |
| 程序不运行，停在HardFault | 启动文件缺失或名称不匹配 | 检查是否使用了正确的startup_xxx.s |
| LED不闪，但单步调试能走 | 时钟未正确配置 | 检查HSE_VALUE和SystemInit()是否被调用 |
| 下载失败：“No target connected” | ST-Link未识别 | 检查接线（SWDIO、SWCLK、GND、VCC）、驱动是否安装 |
| 变量值异常 | .data未从Flash复制 | 确保启动文件中有bl __main或等效机制 |
设计建议：打造可复用、易维护的工程模板
一旦成功运行，建议将当前工程保存为“通用基础模板”，用于后续所有STM32F1项目：
推荐目录结构
Template_STM32F1/ ├── CMSIS/ │ ├── core_cm3.h │ ├── startup_stm32f103xb.s │ ├── system_stm32f1xx.c │ └── inc/ │ └── system_stm32f1xx.h ├── main.c ├── stm32f1xx.h // ST官方头文件 ├── project.uvprojx └── linker.sct可选优化项
- 启用预编译头（Precompiled Headers）提升编译速度；
- 开启
-Wall警告级别，强制修复潜在隐患； - 发布版本关闭调试信息（Debug Information）减小体积；
- 使用批处理脚本自动备份HEX文件。
写在最后：掌握原理，才能超越模板
很多人觉得，“反正CubeMX一键生成工程”，何必费劲研究这些底层细节？
但请记住：当你遇到Bootloader跳转失败、中断无法响应、内存越界等问题时，那些“一键生成”的工程就成了黑盒。你不知道哪一步出了问题，更谈不上修复。
而当你亲手搭建过一次完整的启动链路，你会明白：
Reset_Handler不只是一个标签，它是整个系统的入口哨兵；.sct文件不只是配置，它决定了你的程序能否安全驻留；SystemInit()不是可有可无，它是连接硬件与C世界的桥梁。
这才是嵌入式开发的真正起点。
无论你是刚入门的学生，还是希望夯实基础的工程师，我都鼓励你关掉CubeMX，打开Keil，亲手走一遍这个过程。你会发现，原来那盏闪烁的LED，背后藏着如此精密的设计逻辑。
如果你在实践中遇到了其他挑战，欢迎在评论区交流讨论。让我们一起，把“能跑”变成“懂跑”。
