简介STM32F103ZET6空工程模板是一款面向嵌入式初学者与单片机开发者的Keil MDK工程骨架解决从零搭建STM32标准外设库项目时反复配置启动文件、芯片型号与编译选项的痛点。压缩包共178个文件包含29个C源码、30个H头文件以及编译生成的O目标文件、CRF交叉引用文件、D依赖文件等中间产物同时提供UVPROJX工程文件和HEX可执行文件可用于验证工程完整性或直接烧录。资源整体仅6.63MB适合快速解压后基于标准外设库开展GPIO、定时器、USART等外设练习或项目原型开发。已有1086人学习下载模板内部保留标准外设库常用外设驱动源文件时钟、定时器、ADC、USART、I2C、CAN等模块代码齐全注释与目录结构规整便于在此骨架上按模块添加功能免去重复搭建环境的时间。1. 这块空模板治的是嵌入式起步最磨人的那一步拿到一块新的STM32F103ZET6开发板多数人第一反应是找一个现成的例程点亮LED。但等你要做自己的项目时问题就来了例程里带的工程要么是某家开发板商自己定义的板级封装要么是别人用老库写的初始化和你现在用的HAL风格冲突。删删改改半天最后连编译都过不去。所谓空工程模板就是先把芯片的最小启动链路、时钟树、调试接口、编译参数全部配好不掺任何业务代码你拿到后只需要往里加自己的逻辑。它解决的痛点不是不知道怎么点灯而是每次新建项目都要从零折腾启动文件和链接脚本还容易在换IDE或换芯片型号时翻车。这个模板适合三类人刚学完寄存器操作、开始用标准库或HAL库做小系统的学生从其他单片机转过来、想快速上手F103ZET6的工程师以及在公司里维护过多个项目、想让团队代码风格和工程配置统一的开发者。它的价值不在于代码量而在于省掉了那套没人愿意每次重写、但写错一次就全体罢工的底层配置。本文会把这套空工程模板拆开从文件结构到编译配置再到常见坑一步步让你能照着搭出一个自己可复用的模板。2. 拆开看模板内部Flash、RAM、启动文件各管哪块2.1 先摸清F103ZET6的家底才知道模板为什么要这么排STM32F103ZET6属于高密度Flash的增强型产品线。它带512KB的Flash和64KB的SRAM工作主频最高72MHz。这个空工程模板的所有配置本质上都是围绕着512KB Flash里放代码、64KB SRAM里跑数据这一件事展开。模板里通常会有几个固定目录一个放启动文件一个放链接脚本一个放系统时钟和硬件初始化还有一个空出来的Application文件夹给你写业务逻辑。我习惯把模板根目录分成Core、Drivers、Output和Project。Core里放startup_stm32f103xe.s、system_stm32f103xe.c和main.cDrivers里放HAL库源码或者寄存器操作文件Output留给编译产生的中间文件Project里是IDE工程文件。这样划分的好处是将来做多个项目时只要把业务代码放进去然后改一下链接脚本里的输出文件名就行不用每次去翻库文件有没有被误删。2.2 启动文件不是玄学它决定芯片上电后第一脚踩在哪启动文件startup_stm32f103xe.s是模板里最不能动错的文件。它干的事包括设置初始栈顶指针也就是把SP寄存器指向SRAM的最高地址、初始化中断向量表、调用SystemInit做时钟配置、最后跳转到main函数。很多人直接复制别人工程里的启动文件过来用结果发现中断响应全乱——因为不同芯片型号的向量表位置和中断列表不一样F103ZET6和F103C8T6的向量表条目就差了好几个。选启动文件时一定要认准xe这个后缀它代表高密度产品Flash大于256KB的型号。模板里放的是MDK环境下的.s文件如果是用GCC工具链得用对应的.S文件两者语法不同但逻辑差不多。启动文件里有两个常量值得你打开看一眼Initial_Sp的值是0x2001000064KB RAM顶部Heap_Size和Stack_Size默认是0x200和0x400。如果你的项目用到了大数组或递归这两个值就得在启动文件或链接脚本里改后面避坑章会细说。2.3 链接脚本把代码和数据安排得明明白白链接脚本MDK工程里是stm32f103xe.sctGCC工程里是.ld负责告诉链接器哪些段放在哪个地址区间。F103ZET6的Flash起始地址是0x08000000大小0x80000512KBRAM起始地址是0x20000000大小0x1000064KB。模板里必须把这两个值写对否则代码烧进去要么跑飞要么根本下载不了。以MDK的分散加载文件为例你至少会看到这样的定义; 分散加载文件 stm32f103xe.sct LR_IROM1 0x08000000 0x00080000 { ; 加载区Flash起始0x08000000大小512KB ER_IROM1 0x08000000 0x00080000 { ; 执行区代码 *.o (RESET, First) *(InRoot$$Sections) .ANY (RO) } RW_IRAM1 0x20000000 0x00010000 { ; 可读写区RAM起始0x20000000大小64KB .ANY (RW ZI) } }这段脚本的逻辑是所有只读代码RO放进Flash可读写RW和零初始化ZI数据放进RAM。First确保了中断向量表放在Flash的最起始位置——这是芯片硬件读向量表时固件固定的地址。如果你改了0x08000000这个开头就意味着你打算做Bootloader偏移普通空模板不需要动。2.4 时钟初始化模板里最容易被忽略的隐性坑SystemInit这个函数在system_stm32f103xe.c里模板默认用的是外部8MHz晶振经过PLL倍频到72MHz。但很多F103ZET6开发板上的晶振其实是8MHz没错也有的板子用的是12MHz或者没有焊外部晶振。如果外部晶振不是8MHzSystemInit里的RCC_CONFIG宏又没改系统时钟就会跑得莫名其妙——串口波特率不对、延时不准、甚至启动失败。所以我做模板时会在system_stm32f103xe.c里把时钟源选择单独抽出来用一个宏USE_HSE和USE_HSI控制。默认先用内部8MHz RC振荡器让系统跑起来保证任何板子都能烧进去亮灯等确认外部晶振没问题再切换到HSEPLL。这个习惯帮我排掉了不少使用不同开发板时看似代码一样但就是不工作的玄学问题。空工程模板的Core目录文件清单文件名作用关键参数startup_stm32f103xe.s中断向量表、栈初始化、复位跳转Stack Size0x400Heap Size0x200system_stm32f103xe.c系统时钟初始化SystemInitHSE与PLL倍频默认8MHz→72MHzmain.c空主函数只放初始化和空循环无业务逻辑便于测试stm32f1xx_hal_conf.hHAL库功能开关和参数配置根据实际外设裁剪减少编译时间3. 用MDK从零搭一个能跑通点灯的空模板3.1 新建项目后把文件按模板位置放好用MDK创建工程时随意指定一个工程名可能让后面维护越来越乱。我建议先建好目录骨架工程文件就放在Project/MDK-ARM下芯片型号选择STM32F103ZE注意不是STM32F103ZET6——MDK的device列表里通常用ZE结尾表示高密度。选错型号会导致编译器用错启动文件和内存配置哪怕你手动指定了启动文件也会报一堆警告。创建完工程后把刚才第2章提到的四个核心文件加进去。有两条路径一是直接从我们备份好的模板目录中复制过来二是从HAL库的示例工程里抓取。我更推荐前者因为模板里的启动文件和链接脚本已经针对ZET6调过。复制时注意把main.c里原本的示例业务逻辑全部清空只保留int main(void)和一个空的while(1)这时候编译应该能通过但烧进去没有任何现象——这正是空模板应有的状态。3.2 配置目标选项这几个参数错一点都不行在MDK的Options for Target对话框里最少要检查三处。第一处是Device选型前面已经说过。第二处是Target标签下的Read/Write Memory Areas必须和链接脚本里的地址一致即ROM起始0x08000000、大小0x80000RAM起始0x20000000、大小0x10000。如果你只改了链接脚本却忘了改这里编译器会提示内存溢出。第三处是C/C标签下的Define模板里至少要有USE_HAL_DRIVER和STM32F103xE这两个宏前者让HAL代码生效后者让HAL库的头文件选择正确的芯片系列定义。常见错误是只勾选了USE_HAL_DRIVER忘记STM32F103xE结果编译报unknown type name GPIO_TypeDef之类莫名其妙的问题其实只是宏没配对。另外C标准建议选C99因为后续用for(int i0;...)这样的写法更自然。GNU扩展可以不开除非你要用某些编译器专有的语法。3.3 写一个最小的点灯程序验证模板的可运行性空模板本身不发光不发声但必须有一个能验证链路通畅的最小程序。最简单的就是点灯GPIO的初始化代码虽然写在业务层但HAL库的时钟使能和引脚配置部分完全可以固化成模板风格。我一般会在模板里保留一个bsp_led.c里面写好LED初始化函数但用宏TEMPLATE_LED_ENABLE控制是否编译。这样拿到模板的人可以立刻看到效果不想用就直接把宏关掉。看这个最小初始化代码/* main.c — 空模板的最小验证 */ #include main.h void SystemClock_Config(void); // 前向声明实际实现可以在模板里提供 static void LED_Init(void); int main(void) { HAL_Init(); // 初始化HAL库优先级分组、滴答定时器等 SystemClock_Config(); // 配置系统时钟默认72MHz LED_Init(); // 配置LED引脚 while (1) { HAL_GPIO_TogglePin(LED_GPIO_Port, LED_Pin); // 翻转电平 HAL_Delay(500); // 利用SysTick做延时 } } static void LED_Init(void) { __HAL_RCC_GPIOB_CLK_ENABLE(); // 使能GPIOB时钟 GPIO_InitTypeDef GPIO_InitStruct {0}; GPIO_InitStruct.Pin GPIO_PIN_0; // 假设LED接在PB0 GPIO_InitStruct.Mode GPIO_MODE_OUTPUT_PP; GPIO_InitStruct.Speed GPIO_SPEED_FREQ_LOW; HAL_GPIO_Init(GPIOB, GPIO_InitStruct); }这段代码的逻辑是HAL_Init先设置嵌套向量中断控制器的优先级分组并启动SysTick作为HAL_Delay的时间基准SystemClock_Config把CPU时钟提到72MHzLED_Init把PB0配置为推挽输出。为什么选推挽输出而不是开漏因为推挽能直接灌拉电流点灯开漏需要外部上拉电阻模板里为了少一个依赖默认推挽。速度为什么用LOW对点灯这种低频信号低速度足够还能减少功耗和噪声。3.4 烧录与调试模板里预留的调试配置下载调试相关设置也属于空工程模板的一部分。在MDK的Utilities标签里选择你的调试器型号。最常用的是ST-Link界面里选择ST-Link Debugger然后在Settings里把下载速度设为1MHz——很多10MHz或更高速度的设置在杜邦线连接或供电不稳时会导致下载失败调低速度往往就能解决。如果用的是J-Link需要指定接口类型SWD或JTAG和速度档位。模板里建议把Reset and Run选项勾上这样程序下载后直接运行不需要手动按复位按钮对批量烧录尤其方便。还有一个容易被忽视的点在Debug标签下如果选择了Run to main()那么程序会停在main函数入口方便你设断点验证启动文件是否成功跳转。如果你发现全速运行没问题但进入调试就死机多半是调试器复位时序和你的电源设计冲突。4. 模板工程的关键配置编译优化、堆栈大小与printf重定向4.1 编译优化级别怎么选直接影响你后续排查问题空模板在发布时编译优化级别应该默认开在-O0或-O1。很多工程师拿到模板第一件事就是改-O2结果代码跑飞了找不到原因。对于模板这种只提供基础设施的角色我强烈建议默认-O0也就是不优化。这样调试时变量可以实时观察单步执行不会乱跳。等项目稳定后再手动提升到-O1甚至-O2但那时就该重新测试一遍所有时序敏感的逻辑。在MDK的C/C标签下-O0对应One Function at a Time等等效选项。另外还有一条关于优化等级影响volatile变量的老经验如果你的代码里有依赖寄存器翻转的延时循环比如for(i0;i100000;i);在-O2下可能被编译器直接删掉因为循环体是空的。模板里不会写这类延时但你要清楚优化等级不是越高越好。4.2 堆栈大小设多少才不浪费RAM又不爆栈F103ZET6有64KB RAM听起来不少但嵌套中断、递归函数、大型缓冲数组都会迅速吞噬栈空间。模板默认栈大小是1KB0x400堆是512B0x200。点灯这种空程序完全够用但你一旦往工程里加进printf的浮点格式化、JSON解析库、FatFS文件系统栈很可能不够。怎么判断当前栈够不够一种办法是在调试界面查看SP寄存器的值然后对比它是否触碰到了0x20000000 RAM大小以下的最低地址。但更直接的是在链接脚本里把栈区后面放一个固定图案比如在启动文件里初始化栈区填充0xCC程序跑完看栈区有没有被改写。我见过最隐蔽的栈爆是在一个中断里使用大数组平时不触发一旦某个事件触发中断立即hard fault。所以模板里我通常把栈设为0x10004KBRAM还剩60KB对大多数裸机项目够用。如果你要做USB或网络协议栈可能得加到8KB。4.3 printf重定向模板里最常用的串口调试辅助空模板里值得预留一个串口调用的函数重定向fputc到USART1。这样你的业务代码里直接用printf就能往串口助手里打印日志。重定向的本质是把标准输出函数改写为你的串口发送函数。在MDK环境下用MicroLIB时只需要实现一个fputc函数即可。/* bsp_uart.c — 串口1初始化与printf重定向 */ #include stdio.h void UART1_Init(void) { __HAL_RCC_GPIOA_CLK_ENABLE(); __HAL_RCC_USART1_CLK_ENABLE(); GPIO_InitTypeDef GPIO_InitStruct {0}; GPIO_InitStruct.Pin GPIO_PIN_9 | GPIO_PIN_10; // TXPA9, RXPA10 GPIO_InitStruct.Mode GPIO_MODE_AF_PP; GPIO_InitStruct.Speed GPIO_SPEED_FREQ_HIGH; HAL_GPIO_Init(GPIOA, GPIO_InitStruct); UART_HandleTypeDef huart1 {0}; 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; HAL_UART_Init(huart1); } int fputc(int ch, FILE *f) { HAL_UART_Transmit(huart1, (uint8_t *)ch, 1, 0xFFFF); return ch; }逻辑不复杂初始化PA9和PA10为复用推挽功能然后配置USART1为115200-8-N-1。fputc里调用阻塞发送超时时间设成0xFFFF只表示等待足够长并不是真的会等65秒。要注意的是如果你用标准库而不是MicroLIB往往还需要处理fgetc或者额外支持半主机模式的问题。模板里可以直接在MDK选项里勾选Use MicroLIB它体积小且重定向简单代价是某些C标准库功能不完整比如scanf浮点支持差但平时调试足够。4.4 外部晶振和串口波特率的关联一组实测参数参考很多人在模板里改完串口波特率却发现输出乱码先怀疑代码最后发现是时钟不对。空模板里我习惯把系统时钟、AHB分频、APB分频写在一个配置表里方便大家对照。F103ZET6最大时钟树是这样的外部8MHz经过PLL倍频得到72MHzAHB分频1得72MHzAPB1分频2得36MHzAPB2分频1得72MHz。USART1挂APB2所以它的外设时钟是72MHzUSART2/3挂APB1时钟36MHz。如果你用同一个波特率寄存器值实际波特率会因外设时钟不同而有偏差。外设所在总线外设时钟115200波特率误差理论USART1APB272MHz1%USART2/3APB136MHz1%I2C1APB136MHz需计算时序模板里如果把SystemClock_Config的参数写死成72MHz那么串口初始化部分你只需要改波特率不需要碰时钟。反过来如果你为了省电把主频降到36MHz那USART的初始化代码里所有关于过采样和分频的计算最好重新用CubeMX生成一遍别手改。5. 空模板的避坑指南五条能让你少熬三个夜的踩坑记录5.1 现象程序下载后没有运行要手动复位才跑起来原因这几乎100%是MDK烧录设置里没勾选Reset and Run而你的模板里恰好又用了低电平复位延时的设计。或者某些调试器在连接时自动拉低了复位引脚程序下载完停在复位状态。解决打开Options for Target - Utilities - Settings - Flash Download勾上Reset and Run。如果是ST-Link还要检查Mode选的是Normal而不是Connect under Reset。后者仅用于变砖恢复平时开着会导致每次下载都多花十秒。5.2 现象编译通过但运行时函数指针跳转死机原因启动文件选错了。有人把F103C8T6中密度的启动文件放进来虽然向量表前几条一样但两者中断向量总数不同。当外设中断发生时会跳到错误的中断服务函数或者直接跑飞。解决确认启动文件里的文件头注释写的芯片范围。startup_stm32f103xe.s里的xe就是高密度。你可以打开该文件搜索Vector Table附近的DCD指令数一数中断向量个数F103系列中密度有60个左右高密度有80多个。更省事的方式是直接从官方固件库发布包里复制不要从网上下载不知名来源的启动文件。5.3 现象串口打印乱码改波特率也没用原因典型的系统时钟频率和配置的振荡器不一致。比如模板默认8MHz HSE你的板子实际是12MHz晶振那么PLL倍频后主频不是72MHz串口波特率寄存器算出的实际波特率也是错的。解决先用HSI内部时钟验证串口。将SystemClock_Config里改为HSI作为系统时钟源此时主频固定8MHz不分频串口用9600波特率看打印是否正常。如果正常再排查外部晶振。用示波器测量MCO引脚PA8可以输出系统时钟对比实际频率和预期。没有示波器时可以用两个串口一个发一个收对比时间戳。5.4 现象程序运行一段时间后进入HardFault调试器看死在未知地址原因大概率是栈溢出。模板默认栈1KB你的中断回调里用了递归或大数组瞬间把栈顶压过界限写坏相邻的全局变量或堆区。解决在启动文件里把Stack_Size从0x400改成0x10004KB再试。如果还死就建一个内存监视任务在栈区固定位置放一个magic number定时检查是否被覆盖。比较省心的是在链接脚本中把栈放到RAM最顶部因为栈向下生长底部最低地址最先被用如果栈底被穿说明问题比较严重。5.5 现象编译时提示很多undefined symbol的错误集中在SystemInit或中断回调原因MDK的工程里没有把HAL库的全部源文件加进去或者模板裁剪过头了。比如你用HAL_UART但工程里只有stm32f1xx_hal_uart.c漏了stm32f1xx_hal_rcc.c和stm32f1xx_hal_gpio.c——因为HAL库内部有依赖关系。解决不要在模板里搞最小依赖。直接把整个Drivers/STM32F1xx_HAL_Driver/Src目录下所有.c文件都加入编译虽然编译时间会长几秒但绝对不会有“用了才没有”的尴尬。等你的工程稳定了再慢慢通过stm32f1xx_hal_conf.h把不需要的模块注释掉。注意stm32f1xx_hal.c必须保留它是核心。6. 把空模板升级成你的个人脚手架预置调试宏与自动生成脚本空模板用顺了以后你会发现它真正值钱的部分不是那几个文件而是一套“拿来就能跑”的约定。我自己的习惯是给模板加两个进阶功能。第一个是DEBUG_LEVEL宏控制日志输出在main.h里定义/* main.h — 日志开关示例 */ #define DEBUG_LEVEL_DEBUG 2 #define DEBUG_LEVEL_INFO 1 #define DEBUG_LEVEL_ERROR 0 #define CURRENT_DEBUG_LEVEL DEBUG_LEVEL_DEBUG #define LOG_INFO(fmt, ...) \ do { if (CURRENT_DEBUG_LEVEL DEBUG_LEVEL_INFO) printf([INFO] fmt\r\n, ##__VA_ARGS__); } while(0)这样你在业务代码里写LOG_INFO(Sensor init done, val%d, val);正式发布时把CURRENT_DEBUG_LEVEL改成ERROR所有INFO日志自动消失同时编译器不会产生任何代码。比#ifdef包一大段到处贴人强多了。第二个进阶是写一个简单的批处理脚本把模板复制并重命名成新项目。核心逻辑是复制整个模板目录然后修改里面的MDK工程名和分散加载文件里的输出名。很多人不喜欢用脚本觉得手动复制也很快但当你一个月开五个新项目时你就知道脚本有多香。我用的是一段最小可用的批处理命令# 新建项目脚本片段复制模板并清理中间文件 cp -r STM32F103ZET6_Empty_Template My_New_Project cd My_New_Project find . -name *.o -delete find . -name *.axf -delete rm -rf Output/*这段代码逻辑简单先把模板完整复制一份再删掉编译中间产物和输出目录里的旧文件避免新工程带着老时间戳导致全量重新编译的问题。注意find命令在Windows下用不了得用del /s *.o而Linux和macOS下这条就是我心里的标准写法。复制完的工程会保留模板里所有的硬件初始化你只需要改main.c里的业务代码。模板最终的价值是你在一周后、一个月后打开它时不用回忆“这个文件为什么存在、那个配置是怎么设的”。所以我会在模板里的关键文件开头写注释比如链接脚本里标明0x08000000为什么不能乱动启动文件里标明Stack_Size和Heap_Size的修改位置。这些注释在最初搭模板时是一个负担但在后续每个项目里都会帮你省下几次翻数据手册的时间。这个习惯是我踩过好几回“看起来同样的工程但别人能跑我不能”的坑之后养成的。希望这篇拆解能让你少走我走过的弯路。祝你的空模板一次搭通后面项目不断。本文还有配套的精品资源点击获取