STM32F103C8T6工程模板：从启动文件到BSP的嵌入式开发基石

简介：STM32F103C8T6工程模板是一份面向嵌入式开发者的开箱即用项目基础框架，主要解决从零搭建单片机开发环境、重复配置底层外设的痛点。它基于ARM Cortex-M3内核的经典芯片，覆盖启动文件、HAL驱动库、GPIO/定时器/串口等外设驱动及示例程序，可直接使用MDK Keil等工具链完成编译、烧录与调试。压缩包共233个文件，以59个h头文件与52个c源文件为主体，辅以uvprojx工程配置、hex固件及axf调试映像，整体仅6.66MB，轻量且目录完整。目前已有3777人学习采用，对初学者和进阶工程师都能提供明确的起步路径。借助模板中的设备驱动与调试配置，开发者可跳过繁琐的底层初始化和链接脚本设置，直接聚焦业务功能开发，从而大幅缩短项目验证周期。

1. STM32F103C8T6的工程模板：凭什么让一块 64KB Flash 的开发板撑起量产项目

很多开发者第一次接触 STM32F103C8T6 就是从“点灯”开始的，但真正让人上头的不是点灯本身，而是怎么把一份代码从一个项目搬到另一个项目、从一个外设扩到十几个外设，还能保持结构不乱。如果你也经历过“新开一个工程，花三天搭环境，点灯只用三分钟”的状况，那这个标题击中了一个很实际的需求：STM32F103C8T6 的工程模板。它本质上不是一份代码，而是一套工程骨架——启动文件、链接脚本、时钟配置、外设驱动框架、编译选项，全都提前定好，新项目拿来直接用。适合刚入门的学生、从 Arduino 或 51 转过来的开发者，也适合小公司里一个人维护多个小产品的硬件工程师。

2. 模板拆解：启动文件、链接脚本与时钟树，三块基石各管什么

2.1 启动文件 start_stm32f10x_md.s：向量表、堆栈初始化与 C 运行环境

F103C8T6 属于中等容量产品（Medium-density），所以 Keil 和 IAR 工程里用的启动文件是startup_stm32f10x_md.s。这个文件做三件事：第一，定义完整的中断向量表，从复位向量开始，依次排列到所有外设中断；第二，初始化堆栈指针 SP 和初始 PC，然后把.data段从 Flash 复制到 RAM，把.bss段清零；第三，调用SystemInit()再跳进main()。

; 启动文件关键流程（伪代码） Reset_Handler PROC EXPORT Reset_Handler IMPORT __main IMPORT SystemInit LDR R0, =SystemInit BLX R0 LDR R0, =__main BX R0 ENDP

这段汇编的意义在于：它决定了 C 代码运行前的环境是什么样。SystemInit()在标准外设库里负责把时钟从默认的 HSI 8MHz 切换到用户配置的 HSE + PLL，__main是 C 运行库的入口，负责数据段搬运和main()调用。调试时遇到“进不了 main、卡在启动文件里”，基本都是这一段的前期环境出了问题，而不是业务代码有问题。

启动文件还定义了堆栈大小，常见默认值是Stack_Size EQU 0x00000400，也就是 1KB。对 F103C8T6 这种只有 20KB RAM 的芯片，1KB 栈偏紧，我一般会改成 0x800（2KB）甚至 0x1000（4KB），具体看中断嵌套深度和局部变量大小。堆 Heap 则默认 0x200（512B），不用malloc的工程可以保持默认，甚至改到 0。

选择启动文件时有个最容易踩的点：md代表 Medium-density，对应的是 F103C8/CB；hd对应 F103RC 以上的高容量。把hd的启动文件烧进 C8T6，程序大概率直接跑飞，因为向量表长度和中断号都不匹配。

2.2 链接脚本与 Flash/RAM 分区：C8T6 的 64KB Flash 是怎么被分配的

C8T6 只有 64KB Flash 和 20KB RAM，这个容量决定了模板的设计思路：能省则省，但不该省的坚决不能省。链接脚本（Keil 里叫散列文件，IAR 里叫 .icf）把 Flash 分成几个区域：中断向量表、只读代码、只读常量、以及可能被 OTA 预留的 Boot 区。

; Keil MDK 中 F103C8T6 的典型分散加载描述（部分） LR_IROM1 0x08000000 0x00010000 { ER_IROM1 0x08000000 0x00010000 { *.o (RESET, +First) * (InRoot$$Sections) .ANY (+RO) } RW_IRAM1 0x20000000 0x00005000 { .ANY (+RW +ZI) } }

0x08000000是 Flash 起始地址，0x00010000是 64KB 大小；0x20000000是 RAM 起始地址，0x00005000是 20KB。如果做 Bootloader + App 的分区方案，就要把LR_IROM1的起始地址改成0x08004000之类的偏移值，同时把大小改成剩余容量。改完链接脚本之后，中断向量表的重映射也是一件事，App 里需要手动把向量表搬到新地址，否则中断全部跳回默认位置，外设一开就死。

2.3 时钟树配置：为什么新模板第一件事就是切到 72MHz 主频

模板里最容易被忽视但最影响稳定性的就是时钟配置。F103C8T6 上电默认用内部 HSI 8MHz 运行，所有外设时钟都挂在它下面，这时候去看SystemCoreClock，值就是 8000000。很多开发者点灯点不亮、串口乱码，一半原因出在没切时钟：外设波特率按 72MHz 算，实际却是 8MHz，自然对不上。

标准外设库的时钟配置集中在system_stm32f10x.c里，模板通常在SystemInit()里把时钟切到外部晶振 + PLL 倍频到 72MHz。如果板子上没有外部晶振，模板就得配置成 HSI 内部振荡器倍频，两种方案对应不同的RCC_CFGR寄存器组合。

void SystemInit (void) { RCC->CR |= (uint32_t)0x00000001; // 开启 HSI RCC->CFGR &= (uint32_t)0xF0FF0000; // 复位 CFGR 关键位 // 后续由 SetSysClock() 完成 PLL 配置 }

时钟配置遵循一个固定模板流程：开启外部晶振 HSE → 等待 HSE 就绪 → 配置 Flash 等待周期（72MHz 下必须设 2 个等待周期）→ 配置 PLL 倍频系数 → 开启 PLL → 等待 PLL 锁定 → 把 PLL 作为系统时钟源。参数就三个：PLL 输入源、倍频数、AHB 预分频。对 C8T6 来说，最常见组合是 HSE 8MHz、PLL 倍频 9 倍、SYSCLK 72MHz。

3. 用标准外设库从零搭最小模板：版本选型与工程文件组织

3.1 选标准外设库还是 HAL 库：C8T6 的 Flash 和 RAM 限定了选择

这是搭模板前必须想清楚的一件事。F103C8T6 运行 HAL 库能跑，但 HAL 的底层抽象层、多个回调函数、以及 CubeMX 生成代码里附带的中间件，让一个空工程轻松突破 30KB Flash，RAM 占用也高。而标准外设库（StdPeriph）是直接操作寄存器之上的薄封装，空工程大概 10KB 左右，留给业务代码的空间更充裕。对于 C8T6 这种容量，我的选择是：能用标准外设库就不用 HAL，除非项目强制要求用 CubeMX 做图形化初始化，或者团队成员只熟悉 HAL。

选型的另一个考虑是移植成本。标准外设库的 API 直接映射寄存器操作，底层细节透明，出了问题可以直接读寄存器排查；HAL 库则多了一层句柄和回调机制，出问题时得追多层调用栈。STM32F103C8T6 的项目大多是中小规模的逻辑控制、数据采集、电机驱动，标准外设库的“所见即所得”风格更合适。

需要注意的是，标准外设库官方早已停止维护，但社区和芯片厂商的生态仍然以它为基础，源码可以直接拿到器件支持包翻看。模板里我会把标准外设库的源码固定在一个子目录里，不随意改动，这样后续换芯片型号或换人维护时，依赖关系依旧成立。

3.2 从零建工程：完整目录结构与源文件分组

模板的核心不是代码本身，而是文件怎么组织。一个清晰、可复制的目录结构，决定了项目规模变大之后能不能继续维护。我一般会按“内核层、外设驱动层、板级封装层、应用层”四个层次建目录，编译器和 IDE 工程文件放在单独目录。

Template/ ├── Drivers/ │ ├── CMSIS/ │ │ ├── core_cm3.h │ │ ├── system_stm32f10x.c │ │ └── system_stm32f10x.h │ ├── StdPeriph_Driver/ │ │ ├── inc/ │ │ ├── src/ │ │ └── stm32f10x_conf.h │ └── Startup/ │ └── startup_stm32f10x_md.s ├── BSP/ │ ├── bsp_led.c │ ├── bsp_led.h │ ├── bsp_uart.c │ └── bsp_uart.h ├── App/ │ ├── main.c │ ├── app_task.c │ └── app_task.h ├── MDK-ARM/ └── User/ ├── stm32f10x_it.c └── stm32f10x_it.h

这个结构的好处是依赖方向从头到尾是单向的：App 只调用 BSP，BSP 只调用 StdPeriph，StdPeriph 只调用 CMSIS。任何一层有问题，替换起来都不影响其他层。启动startup_stm32f10x_md.s属于 CMSIS 层的一个组件，Keil 工程里单独分组，编译顺序不需要特别指定，Keil 会自动处理汇编文件的编译。

3.3 最小模板的代码骨架：系统时钟、延时、LED 与串口

模板里最基础的代码就三样：时钟配置、延时、LED 闪烁。串口作为调试输出也应该从一开始就放进去，否则后续排查问题时无从下手。代码量不大，但每段都有固定的写法。

/* main.c - 最小模板骨架 */ #include "stm32f10x.h" #include "bsp_led.h" #include "bsp_uart.h" void delay_ms(uint32_t ms) { uint32_t i; for (i = 0; i < (ms * 8000); i++) { __NOP(); } } int main(void) { /* SystemInit() 已在启动文件中调用，此处无需重复 */ BSP_LED_Init(); BSP_UART_Init(115200); printf("Template boot OK. SysClk=%u Hz\r\n", SystemCoreClock); while (1) { BSP_LED_Toggle(); delay_ms(500); } }

delay_ms用软延时实现，8MHz 主频下每次循环大约 4 个周期，所以用 8000 这个近似系数。这里有个陷阱：如果模板后来把主频从 8MHz 改到 72MHz，软延时的系数必须同步调大 9 倍，否则延时变成实际的 1/9。所以模板放进正式项目前，最好把延时函数替换成基于 SysTick 的版本，避免每个业务程序都带着一个可能出错的定时系数。

/* bsp_uart.c - 串口驱动的标准外设库初始化 */ void BSP_UART_Init(uint32_t baudrate) { GPIO_InitTypeDef GPIO_InitStructure; USART_InitTypeDef USART_InitStructure; RCC_APB2PeriphClockCmd(RCC_APB2Periph_GPIOA | RCC_APB2Periph_USART1, ENABLE); GPIO_InitStructure.GPIO_Pin = GPIO_Pin_9; GPIO_InitStructure.GPIO_Mode = GPIO_Mode_AF_PP; // TX 复用推挽 GPIO_InitStructure.GPIO_Speed = GPIO_Speed_2MHz; GPIO_Init(GPIOA, &GPIO_InitStructure); GPIO_InitStructure.GPIO_Pin = GPIO_Pin_10; GPIO_InitStructure.GPIO_Mode = GPIO_Mode_IN_FLOATING; // RX 浮空输入 GPIO_Init(GPIOA, &GPIO_InitStructure); USART_InitStructure.USART_BaudRate = baudrate; USART_InitStructure.USART_WordLength = USART_WordLength_8b; USART_InitStructure.USART_StopBits = USART_StopBits_1; USART_InitStructure.USART_Parity = USART_Parity_No; USART_InitStructure.USART_HardwareFlowControl = USART_HardwareFlowControl_None; USART_InitStructure.USART_Mode = USART_Mode_Rx | USART_Mode_Tx; USART_Init(USART1, &USART_InitStructure); USART_Cmd(USART1, ENABLE); }

两个要点：GPIO_Speed不能忽略，对串口这种低速外设设 2MHz 就够，设 50MHz 反而容易引入噪声；串口 TX 必须配置成AF_PP，RX 配IN_FLOATING，这两个模式配反是串口不通的头号原因。

3.4 工程配置里的 6 个必调参数：宏定义、Debug、Flash 算法与优化等级

Keil MDK 工程在编译前，有 6 个参数必须核对，错了要么编译不过，要么烧录后跑不起来。

STM32F10X_MD这个宏直接决定标准外设库中哪些外设定义被编译进去，漏定义会导致系统时钟和外设地址全部错乱。Debug 模式选 SW 而不是 JTAG，是出于实际考虑：SWD 只用 PA13/PA14 两根线，JTAG 五根线容易把其他引脚占掉。如果板子上的引脚不够用，甚至可以把 SWDIO/SWCLK 在初始化后释放成 GPIO，但前提是烧录口已经调试好，后续不再需要在线调试。

编译优化等级是个容易被忽略的玄学点。-O0下一切正常，切到-O2后定时器不准、延时变短，很多情况下是代码里存在依赖“编译器不做优化”的未定义行为。模板里建议默认-O0，但这个配置本身要在工程文档里标注出来，等验证完功能逻辑后再统一切优化，不要边开发边切。

4. 模板的移植与裁剪：把固定外设骨架变成可复用的业务框架

4.1 按外设分文件的 BSP 层组织方式

模板不能只有一个main.c堆到底。外设初始化代码有个特点：每个外设都有固定的“开时钟 → 配引脚 → 配参数 → 使能”四步，如果同一段代码被复制到三个项目的main.c里，维护成本会指数级上升。所以模板里我会把每个外设独立成一对.c/.h文件，编译进一个固定的 BSP 分组。

/* bsp_led.h - 只暴露接口和常量，不暴露寄存器操作 */ #ifndef __BSP_LED_H #define __BSP_LED_H #include "stm32f10x.h" #define LED_GPIO_PORT GPIOC #define LED_GPIO_PIN GPIO_Pin_13 #define LED_GPIO_CLK RCC_APB2Periph_GPIOC void BSP_LED_Init(void); void BSP_LED_On(void); void BSP_LED_Off(void); void BSP_LED_Toggle(void); #endif

接口只暴露功能，不暴露寄存器细节。这样做有一个直接好处：换一块板子、换一个 LED 引脚时，只需要改.h里的宏定义和.c里的实现，App 层的代码完全不需要动。很多项目后期翻车，就是改引脚时直接在业务代码里改 GPIO 操作，把外设逻辑和业务逻辑搅在一起。

4.2 板级封装与应用层划分：谁是“知道硬件的人”

模板在正式使用前，需要明确一条职责线：BSP 层是唯一知道“这颗 LED 在哪个引脚、这个按键在哪一个 GPIO”的人，App 层只调用BSP_LED_On()这种功能接口。这条线一旦打破，模板就失去了复用性。

我见过一个项目，为了省时间，在应用代码里直接写了GPIO_ResetBits(GPIOC, GPIO_Pin_13)来控制 LED。后来硬件改版把 LED 换到另一颗芯片上，应用层里所有同名操作全部要改，排查了两天才发现是引脚位置变了。如果在 BSP 层封装好接口，改一个文件就够了。

4.3 裁剪编译时间与体积：不用的外设从模板中排除

标准外设库默认把所有外设的源码都包含在工程里，编译一次 F103 的工程时间会明显变长，Flash 占用也会变大。裁剪方法有两种：一是只把需要的.c文件加入工程分组，二是用stm32f10x_conf.h的宏关闭不需要的外设头文件。

/* stm32f10x_conf.h 中只启用需要的模块 */ #define _GPIO #define _RCC #define _USART #define _TIM /* 注释掉不需要的外设： #define _ADC、#define _SPI 等 */

编译阶段的标准外设库源码里，每个模块都用#ifdef _XXX包住了函数定义，所以裁剪宏能真正去掉代码，而不是简单跳过编译。模板里我会根据目标业务“默认裁到最小集”，只保留 GPIO、RCC、USART、TIM、DMA 这几个高频外设。等真用到 ADC 或 I2C 时，再把对应宏打开、把.c文件加进工程，一分钟就能恢复。

5. 模板搭建的常见问题与排查：从启动异常到跑飞的五个真实场景

5.1 现象：烧录器连接不上，提示“No target connected”

这是搭模板时最让人挫败的问题。原因通常不是芯片坏了，而是硬件复位状态不对或 SWD 引脚被占用。排查路径有固定顺序：先量 VDD 和 GND 是否短路，再确认 NRST 引脚是否有 10k 上拉，最后确认 SWDIO/SWCLK 引脚对地电容是否过大。还有一种情况是第 3.4 节的 Flash 编程算法选错，烧录器虽然能连上，但擦除不成功，表现为“烧录到一半报错”。解决方法是把目标板的 Boot0 拉高、Boot1 拉低，强制从系统存储器启动，这时 SWD 通信会恢复，重新擦除即可。

5.2 现象：程序烧进去了，但 GPIO 输出高低电平异常

代码逻辑没问题，输出引脚却测不到电平变化，大概率是“外设时钟没开”。F103 的 GPIO 和外设挂在三条总线上：GPIOA/B/C 和 USART1 在 APB2，USART2/3 和大部分定时器在 APB1，DMA 在 AHB。RCC_APB2PeriphClockCmd(RCC_APB2Periph_GPIOC, ENABLE)漏掉一行，寄存器写入直接无效，而且不会报错。排查时先看 GPIO 配置代码里有没有“开启 GPIO 时钟 + 复用功能时钟”这两行，再看速度位GPIO_Speed是否设置成了GPIO_Speed_2MHz这种低速档，输出频率偏高时电平会变形。

5.3 现象：程序运行一段时间后进入 HardFault，或随机跑飞

这种问题在 F103C8T6 上非常常见，RAM 总量只有 20KB，大数组 + 深函数调用很容易把栈吃掉。模板里我固定会在启动文件里把栈设置成 0x1000（4KB），同时把编译器的--stack参数也同步调大，两个地方只改一个就会出问题。另一个典型原因是中断服务函数缺失：定时器开了中断，但stm32f10x_it.c里没有对应的XXX_IRQHandler，中断一来就跳到了默认的死循环或空函数。排查方法是先在HardFault_Handler里打断点，看调用栈和LR寄存器的值，能定位到是哪一行触发的异常。

/* stm32f10x_it.c - 定时器中断服务函数缺失时，会默认进入这个空循环 */ void TIM2_IRQHandler(void) { /* 检查中断标志位，再执行业务逻辑 */ if (TIM_GetITStatus(TIM2, TIM_IT_Update) != RESET) { TIM_ClearITPendingBit(TIM2, TIM_IT_Update); /* 你的业务代码 */ } }

5.4 现象：编译报错 “No space in execution regions”

这个报错说明 Flash 超出了 64KB 硬限制，常见原因是启动文件选错、宏定义漏掉、或者 HAL 库里把没用的组件也编译进去了。如果是启动文件或宏定义的问题，编译信息里会直接告诉你startup_stm32f10x_hd.s被编译成了目标文件，把它替换成md版本即可。如果确认是代码本身膨胀，就要进入裁剪流程：先检查stm32f10x_conf.h的模块宏，再检查是否把调试用的printf浮点打印带进来了。标准库里启用浮点printf会额外消耗十几 KB Flash，用整型格式化输出可以省出很大空间。

5.5 现象：Keil 中中文注释乱码、源码文件打开后直接报编码错误

这个问题不算功能 bug，但会浪费大量时间。新版本的 Keil 默认使用 UTF-8，而旧工程或老代码片段是 GB2312 编码，两者混用时，中文字符会变成一串乱码。模板里我会统一用 UTF-8 保存所有.c/.h文件，并且在 Keil 的Edit → Configuration → Editor → Encoding中选择 UTF-8。批量转换编码可以用脚本或者 IDE 自带的全文件转码功能，但要注意：转换完必须重新编译一次，防止注释里的非法字符干扰词法分析。

6. 让模板更顺手：串口命令框架、模板版本管理与跨项目复用

模板的价值在新项目启动的前半小时体现得最明显。平时我会在模板里预留一个极简串口命令解析框架：把uart_irq收到的一行字符串拆成“命令字 + 参数”，丢给注册好的函数去执行。这样新板子拿回来，不用专门写调试程序，直接用串口工具发指令就能测 GPIO、读 ADC、操作电机。解析代码不超过 50 行，放在 App 层的一个cmd_handler.c里，配合 BSP 层的外设接口，算是一个“微型调试协议”。

/* cmd_handler.c - 极简串口命令分发 */ typedef void (*cmd_func_t)(int argc, char *argv[]); typedef struct { const char *name; cmd_func_t func; } cmd_entry_t; static void cmd_led_on(int argc, char *argv[]) { BSP_LED_On(); printf("LED ON\r\n"); } const cmd_entry_t cmd_table[] = { {"led_on", cmd_led_on}, {"adc_read", cmd_adc_read}, }; void CMD_Handler(char *line) { for (int i = 0; i < sizeof(cmd_table)/sizeof(cmd_table[0]); i++) { if (strcmp(line, cmd_table[i].name) == 0) { cmd_table[i].func(0, NULL); return; } } printf("Unknown cmd\r\n"); }

串口命令框架加进模板之后，我习惯把整个模板作为一个 Git 仓库来管理，用分支区分“基础模板”和“具体项目”。基础模板分支只维护 BSP 层和 CMSIS 相关文件，App 层默认只保留 main 和命令解析；每个新项目基于基础模板切一个独立分支，业务代码全部写在 App 层。这样当基础模板修复了一个底层 bug（比如时钟配置里 Flash 等待周期问题），可以直接把基础分支合并到各项目分支，不用手动改每一份代码。

算下来，这套模板从第一次搭好到现在，已经帮我在十几个项目里省掉了重复搭框架的时间。最初踩的那些坑——启动文件选错导致跑飞、GPIO 时钟没开导致点不亮、栈溢出导致 HardFault——全部沉淀成了模板里的默认配置和注释提醒。如果你正在为“新工程从零开始”发愁，不妨照着这个结构搭一版自己的模板，哪怕只保留 BSP 分层和串口调试框架，后面做新项目的时候也会省下不少力气。希望帮到你。

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