STM32 开发板到手之后真正让人卡住的往往不是写代码而是从拆快递到点亮第一颗 LED 之间的那段空白。我见过太多人兴冲冲买回一块 STM32F103 板子结果在装软件、找驱动、配环境这几步上耗掉一整个周末最后板子吃灰。这篇内容就是写给刚拿到板子、或者正准备下单的朋友把 STM32F103 入门这条路上该踩的、不该踩的坑一次讲清楚。不管你是电子专业的学生、想转嵌入式的程序员还是纯粹想折腾硬件的爱好者只要跟着走一遍至少能少走两三个晚上的弯路。1. 拿到 STM32F103 开发板先别急着上电1.1 开箱之后第一件事是核对板子版本和核心芯片很多人拆开包装就直接插 USB 线这个习惯不太好。STM32F103 这个系列本身有很多细分型号最常见的几种是 C8T6、RCT6、ZET6区别主要在 Flash 容量、RAM 大小和引脚数量上。C8T6 是 64KB Flash、20KB RAM、48 引脚RCT6 是 256KB Flash、48KB RAM、64 引脚ZET6 则是 512KB Flash、64KB RAM、144 引脚。你买到的板子上焊的是哪一颗直接决定了后面能跑多复杂的程序。我一般拿到板子会先做三件事第一用放大镜或者手机微距拍一下芯片表面的丝印确认型号第二翻一下板子背面看看有没有标注版本号比如 V3.0、V3.1 这种不同版本的外设布局可能不一样第三对照卖家给的资料包确认板载的晶振频率是 8MHz 还是 12MHz这个直接影响后面时钟树的配置。注意有些低价板子会用 STM32F103C8T6 打磨后冒充 RCT6 卖丝印模糊或者字体不对就要警惕。正规渠道买的板子一般不会有这个问题但二手或者来路不明的要留个心眼。1.2 上电前必须确认的供电和跳线状态STM32F103 的供电范围是 2.0V 到 3.6V大部分开发板通过 USB 的 5V 经过板载 LDO 降压到 3.3V 给芯片供电。上电之前要检查几个地方BOOT0 和 BOOT1 跳线帽的位置这决定了芯片从哪里启动。正常跑程序的时候 BOOT0 接 GND、BOOT1 随便也就是从主 Flash 启动。如果要通过串口下载程序需要把 BOOT0 接到 VCC下载完再拨回去。还有一个容易被忽略的点是 USB 接口的类型。有些板子用的是 Micro USB有些是 Type-C还有些老板子是 Mini USB。线材不对的话插上去没反应新手很容易以为是板子坏了。我建议拿到板子先用手电筒照一下接口确认类型再找线。另外如果你买的板子带 ST-Link 或者 DAP-Link 调试器要确认调试器的排线有没有插反。排线上一般有防呆凸起但有些廉价排线没有插反了轻则识别不到芯片重则烧调试器。我自己的习惯是插之前先看板子上的丝印SWDIO、SWCLK、GND、3V3 这四个脚的位置记清楚。1.3 板载外设的初步检查清单一块典型的 STM32F103 开发板通常会带这些外设LED 指示灯至少一个、按键复位键加用户键、USB 转串口芯片CH340 或者 CP2102、SWD 调试接口、以及一些扩展排针。上电之后如果板子出厂烧了测试程序LED 应该会闪烁或者呼吸。如果没有反应先别慌可能只是出厂没烧程序。我习惯用万用表蜂鸣档快速测一下几个关键点3.3V 和 GND 之间有没有短路USB 的 5V 有没有到 LDO 输入端LDO 输出是不是 3.3V。这几个点正常板子基本就没大问题。这一步花不了两分钟但能避免很多板子是不是坏了的焦虑。2. 开发环境搭建Keil、CubeMX 和 VSCode 怎么选2.1 Keil MDK 依然是 STM32F103 最稳的选择网上关于 STM32 开发环境的讨论很多有人推 Keil有人推 IAR还有人用 VSCode 加插件。我的建议是如果你是零基础入门 STM32F103先用 Keil MDK。原因很简单资料最多、教程最全、遇到问题最容易搜到答案。Keil 的安装包不大装完之后需要单独装 STM32F1 的器件支持包也就是常说的 Pack。安装顺序是这样的先装 Keil MDK 主程序然后去 Keil 官网下载 STM32F1 系列的 Device Family Pack双击安装。装完之后打开 Keil在 Project 菜单里新建工程选择芯片型号的时候能看到 STM32F103 系列就说明装好了。这里有个细节Keil 5 和 Keil 4 的 Pack 不通用现在新装的都是 Keil 5别下错版本。提示Keil 的编译速度在 STM32F103 这种小芯片上完全够用没必要为了追求编译速度去折腾其他工具链。等你把 F103 玩熟了再考虑换 VSCode 加 GCC 的方案。2.2 STM32CubeMX 要不要学什么时候学CubeMX 是 ST 官方出的图形化配置工具可以自动生成初始化代码。对于 STM32F103 来说CubeMX 支持得非常好基本上点几下鼠标就能把时钟、GPIO、串口、定时器都配好。但我不建议一上来就用 CubeMX原因是你会对底层寄存器没有概念后面遇到问题不知道怎么排查。我的建议是分两步走第一周先用标准库手写代码把 GPIO 输出、GPIO 输入、串口收发这几个基础实验做一遍理解一下寄存器是怎么操作的。第二周开始用 CubeMX 生成代码对比一下它生成的初始化和你自己写的有什么区别。这样既懂了原理又享受了工具的效率。CubeMX 生成代码的时候要注意它默认用的是 HAL 库代码量比标准库大不少。STM32F103C8T6 只有 64KB Flash用 HAL 库写复杂一点的项目可能会不够用。如果 Flash 吃紧可以在 CubeMX 里选择用 LL 库代码会精简很多。2.3 VSCode 方案适合什么人VSCode 加 STM32 的方案这两年越来越流行核心是装 Cortex-Debug 插件配合 OpenOCD 或者 ST-Link GDB Server 来调试。这套方案的好处是编辑器体验好、免费、跨平台缺点是配置起来比 Keil 麻烦不少尤其是 launch.json 和 tasks.json 这两个文件新手很容易配错。如果你已经有一定编程基础平时就用 VSCode 写代码那可以试试这套方案。配置的关键是这几个文件c_cpp_properties.json 里要指定 ARM 的头文件路径tasks.json 里要写编译命令launch.json 里要配调试器路径和芯片型号。网上有现成的模板可以抄但芯片型号和路径要改成你自己的。我自己的主力环境是 Keil 加 VSCode 双开Keil 用来编译和下载VSCode 用来看代码和写代码。Keil 的编辑器确实不太好用但它的编译器和调试器对 STM32F103 的支持是最成熟的没必要为了编辑器体验去折腾整个工具链。3. 第一个工程从新建到点亮 LED 的完整链路3.1 用标准库新建工程的目录结构标准库新建工程是 STM32F103 入门最经典的方式虽然现在 ST 主推 HAL 库但标准库的代码结构清晰适合理解底层。新建工程的步骤大致是在 Keil 里新建 Project选好芯片型号然后把 ST 官方标准库里的启动文件、内核文件、外设驱动文件复制到工程目录里。目录结构我一般这样组织根目录下建四个文件夹分别是 Start、Library、User、Output。Start 放启动文件和内核文件Library 放标准库的外设驱动User 放 main.c 和用户自己写的代码Output 放编译生成的 hex 和 axf 文件。这样分的好处是结构清晰后面加外设的时候不会乱。启动文件的选择要注意STM32F103C8T6 用的是 startup_stm32f10x_md.smd 代表 Medium Density。如果是 RCT6 或者 ZET6要用 hd 版本。选错了启动文件编译能过但程序跑不起来这个坑我踩过。3.2 时钟配置为什么是 72MHzSTM32F103 的最高主频是 72MHz这个频率不是随便定的而是通过外部 8MHz 晶振经过 PLL 倍频得到的。具体路径是8MHz 晶振输入经过 PLL 预分频器除以 1然后 PLL 倍频 9 倍得到 72MHz再经过 AHB 预分频器除以 1作为系统时钟。这个配置在标准库的 system_stm32f10x.c 文件里已经写好了默认就是 72MHz。但如果你用的是 12MHz 晶振的板子这个默认配置就不对了需要手动改 PLL 的倍频系数。12MHz 的话倍频 6 倍得到 72MHz。改的地方在 SystemInit 函数里找到 RCC_PLLConfig 那一行把参数改成对应的值。这个细节很多教程不讲但买板子的时候如果没注意晶振频率后面串口波特率会全乱。3.3 GPIO 输出实验点亮第一颗 LED点亮 LED 是嵌入式界的 Hello World但这里面也有讲究。STM32F103 的 GPIO 有八种模式输出模式下常用的是推挽输出和开漏输出。推挽输出可以输出高电平和低电平驱动能力强开漏输出只能输出低电平高电平需要外部上拉。驱动 LED 一般用推挽输出。配置 GPIO 的步骤是先开 GPIO 时钟然后设置引脚的模式、速度最后用 GPIO_SetBits 或者 GPIO_ResetBits 控制电平。这里有个容易搞混的地方STM32 的 GPIO 时钟是挂在 APB2 总线上的开时钟要用 RCC_APB2PeriphClockCmd别用成 APB1 的。LED 的接法有两种共阳极和共阴极。共阳极是 LED 正极接 3.3V负极接 GPIOGPIO 输出低电平点亮共阴极是负极接 GND正极接 GPIO输出高电平点亮。大部分开发板用的是共阳极接法所以 GPIO_ResetBits 是点亮GPIO_SetBits 是熄灭。写代码之前先看一眼原理图确认接法。3.4 下载程序SWD 和串口两种方式下载程序有两种常用方式SWD 和串口。SWD 需要 ST-Link 或者 DAP-Link 调试器接线是 SWDIO、SWCLK、GND、3V3 四根线。串口下载需要 USB 转串口模块接线是 TX、RX、GND 三根线还要把 BOOT0 拨到 VCC。SWD 的好处是可以在线调试打断点、看变量都方便推荐作为主要下载方式。串口下载的好处是不需要额外买调试器板载的 USB 转串口芯片就能用但只能下载不能调试。我一般两个都留着SWD 用来日常开发串口用来救急比如不小心把 SWD 引脚复用了导致连不上芯片的时候。注意如果 SWD 连不上芯片先检查 BOOT0 是不是被拨到了 VCC再检查调试器驱动有没有装好。还不行的话把板子断电按住复位键点下载再松开复位键这叫复位下载法能解决大部分连不上的问题。4. 入门阶段最容易卡住的几个问题4.1 串口乱码波特率、时钟、线序三查串口乱码是新手遇到最多的问题没有之一。排查思路按这个顺序来第一确认波特率是不是两边一致常用的有 9600、115200板子和串口助手要设成一样的第二确认系统时钟是不是 72MHz如果晶振频率不对导致时钟错了波特率也会跟着错第三确认 TX 和 RX 有没有接反板子的 TX 要接串口模块的 RX板子的 RX 要接串口模块的 TX。还有一个隐蔽的坑是串口助手的编码格式。有些串口助手默认用 GBK有些用 UTF-8如果程序里发的是中文编码不对就会乱码。发英文和数字一般不会有这个问题。我习惯先用英文测试确认通路正常再折腾中文。4.2 程序下载后不运行BOOT 引脚和复位电路程序下载成功但板子没反应先检查 BOOT0 是不是还在 VCC。下载完之后要把 BOOT0 拨回 GND否则芯片会一直停在 Bootloader 里不执行你烧的程序。这个坑几乎每个新手都会踩一次。如果 BOOT0 没问题检查复位电路。有些板子的复位按键质量不好按下去弹不起来芯片一直处于复位状态。用万用表测一下复位引脚的电平正常应该是 3.3V按下按键变成 0V。如果一直是 0V那就是复位电路有问题。还有一种情况是程序里把 SWD 引脚复用了导致下载一次之后就连不上了。解决办法是用串口下载一个空程序或者用复位下载法。预防措施是在程序开头加一段延时给调试器留出连接时间。4.3 Keil 编译报错常见错误代码对照Keil 编译报错信息有时候不太直观我整理了几个常见的错误和解决办法错误提示可能原因解决办法cannot open source input file头文件路径没加在 Options for Target 的 C/C 里添加 Include Pathsundefined symbol源文件没加到工程把对应的 .c 文件添加到工程目录树flash download failed调试器配置不对检查 Debug 选项卡里的调试器型号和 Flash 算法no target connected调试器没识别到芯片检查接线、驱动、BOOT 引脚section .text overflowFlash 空间不够优化代码或者换 Flash 更大的芯片这些错误看着吓人其实原因都很简单。我建议每次报错先看第一行Keil 的报错信息第一行通常是最关键的后面的都是连锁反应。4.4 延时函数 delay 卡死的原因delay 函数卡死是 STM32F103 新手常见问题尤其是用 SysTick 做延时时。卡死的原因通常是中断优先级配置不对或者 SysTick 的时钟源没选对。STM32F103 的 SysTick 可以选择 HCLK 的 1/8 或者 HCLK如果选错了延时时间会差 8 倍但一般不会卡死。真正会卡死的情况是在中断服务函数里调用了 delay而 delay 又依赖中断形成了死锁。解决办法是不要在中断里用延时或者用不依赖中断的延时方式比如简单的 for 循环空转。虽然 for 循环延时不准但在中断里用足够了。还有一种情况是 delay 函数里用了 while 等待标志位但标志位一直不置位。这通常是初始化没做对比如 SysTick 没使能或者重装载值设成了 0。检查一下 SysTick_Config 的返回值如果是 1 说明重装载值太大了超出范围。5. 从点亮 LED 到做出一个小项目5.1 按键输入消抖和中断两种方式按键是继 LED 之后第二个要掌握的外设。STM32F103 的按键处理有两种方式轮询和中断。轮询是在主循环里不断检测引脚电平中断是配置外部中断按键按下时触发中断服务函数。轮询方式简单但占用 CPU 时间而且需要消抖。消抖有硬件消抖和软件消抖两种硬件消抖是在按键两端并一个电容软件消抖是检测到按下后延时 10ms 再检测一次。我一般用软件消抖加个 10ms 的延时简单有效。中断方式响应快但配置麻烦一点要开 AFIO 时钟、配置 EXTI、配置 NVIC。这里有个坑STM32F103 的 EXTI 线是复用的PA0 和 PB0 共用 EXTI0不能同时用。配置的时候要注意引脚编号别冲突了。5.2 串口通信收发数据和 printf 重定向串口是 STM32F103 最常用的通信接口调试、通信、下载都靠它。配置串口的步骤是开 GPIO 时钟和 USART 时钟配置 GPIO 为复用推挽输出和浮空输入配置 USART 的波特率、数据位、停止位、校验位最后使能 USART。printf 重定向是串口调试的利器可以把 printf 的输出重定向到串口。具体做法是重写 fputc 函数在里面调用 USART_SendData。这样就能用 printf 打印变量值比用串口助手手动发数据方便多了。注意要在 Keil 的 Target 选项里勾选 Use MicroLIB否则 printf 可能不工作。串口接收数据一般用中断方式每收到一个字节触发一次中断把数据存到缓冲区里。如果数据量大可以用 DMA 加空闲中断的方式效率更高。STM32F103 的 USART1 支持 DMA配置好之后 CPU 几乎不占用。5.3 定时器PWM 输出和定时中断定时器是 STM32F103 最强大的外设之一通用定时器 TIM2 到 TIM5 都是 16 位的支持向上、向下、中央对齐三种计数模式。定时器最常用的两个功能是定时中断和 PWM 输出。定时中断的配置步骤是开定时器时钟设置预分频器和自动重装载值使能更新中断配置 NVIC。定时时间的计算公式是定时时间 (预分频器 1) × (自动重装载值 1) / 时钟频率。比如 72MHz 时钟预分频 7199重装载 9999定时时间就是 1 秒。PWM 输出的配置稍微复杂一点要设置 PWM 模式、输出比较极性、使能输出。PWM 频率的计算公式是频率 时钟频率 / ((预分频器 1) × (自动重装载值 1))。占空比 比较值 / (自动重装载值 1)。用 PWM 控制 LED 亮度或者电机速度都很方便。5.4 做一个超声波测距的小项目把前面几个外设串起来可以做一个超声波测距的小项目。超声波模块常用的是 HC-SR04工作原理是发一个 10us 的高电平触发信号模块发出 8 个 40kHz 的脉冲然后等待回波。通过测量回波高电平的时间乘以声速再除以 2就是距离。实现思路是用定时器输出一个 10us 的高电平触发信号然后用定时器输入捕获功能测量回波的高电平时间。输入捕获的配置比 PWM 输出复杂要设置捕获边沿、捕获通道、中断。测到时间后用公式 距离 时间 × 340 / 2 / 10000 计算单位是厘米。这个项目涉及 GPIO 输出、定时器输出、定时器输入捕获、串口打印是一个很好的综合练习。做完这个STM32F103 的基础外设基本就摸清楚了。6. 入门之后往哪个方向走6.1 标准库转 HAL 库的过渡标准库玩熟之后建议花点时间了解一下 HAL 库。现在 ST 的新芯片基本只支持 HAL 库标准库已经停止更新了。HAL 库的代码风格和标准库差别挺大但核心概念是一样的都是配置寄存器只是封装方式不同。过渡的时候重点看这几个文件stm32f1xx_hal_gpio.c、stm32f1xx_hal_uart.c、stm32f1xx_hal_tim.c。HAL 库的函数名比较长但命名有规律比如 HAL_GPIO_WritePin、HAL_UART_Transmit。用 CubeMX 生成一个工程对照着看很快就能上手。6.2 从 F103 到其他 STM32 系列的迁移STM32F103 是入门的好选择但实际项目中可能会用到其他系列比如 F4 系列性能更强G0 系列性价比更高H7 系列适合高性能场景。从 F103 迁移到其他系列核心概念是通的主要差异在时钟树、外设数量和寄存器地址上。迁移的时候建议先看芯片的参考手册和数据手册重点看时钟树和外设框图。然后用 CubeMX 生成一个工程对比一下和 F103 的差异。有 F103 的基础迁移到其他系列一般一两周就能上手。6.3 进阶方向RTOS、通信协议、电机控制STM32F103 的资源有限跑 RTOS 有点吃力但可以跑 FreeRTOS 的裁剪版。学 RTOS 的好处是理解任务调度、信号量、消息队列这些概念对后面做复杂项目有帮助。通信协议方面CAN、485、Modbus 都是工业上常用的STM32F103 自带 CAN 控制器做 CAN 通信很方便。电机控制方面F103 可以驱动步进电机和伺服电机用 PWM 加定时器就能实现。我自己的路径是先做几个传感器的小项目把 GPIO、串口、定时器、ADC 都摸一遍然后学 FreeRTOS再做 CAN 通信的项目。每一步都不用急把当前的东西吃透再往下走。6.4 一些实用的学习资源和习惯最后分享几个我自己的学习习惯。第一每学一个外设先看参考手册对应的章节再看例程最后自己写一遍。第二遇到问题先搜错误信息大部分问题别人都遇到过。第三准备一个笔记本记录踩过的坑和解决办法下次遇到直接翻。资源方面ST 官方的参考手册和数据手册是最权威的虽然厚但值得翻。正点原子和野火的教程适合入门讲得比较细。B 站上也有很多免费的 STM32 教程选一个播放量高的跟着做就行。提示不要贪多STM32F103 的外设很多但常用的就那几个。把 GPIO、串口、定时器、中断、ADC 这五个玩熟就能做大部分入门项目了。剩下的用到再学不用一次全啃完。板子买回来只是开始真正有价值的是动手做。哪怕只是点亮一颗 LED也比看十篇教程强。我见过太多人收藏了一堆资料板子却一直在盒子里躺着。STM32F103 这块板子不贵但能学到的东西很多从寄存器操作到 RTOS从裸机到通信协议足够玩上大半年。别想着一口吃成胖子先把第一个 LED 点亮后面的路自然就清晰了。