说实话，看到后台留言“看了三篇了，一行都没让我写呢”，我忍不住笑了。这确实是嵌入式C++编程之旅前几篇最容易被吐槽的地方。回头想想，前几篇确实一直在铺路：搭环境、建工程、讲编译流程，一点代码都没上。但嵌入式这行有个很现实的门槛——它不像Web前端，打开浏览器F12就能改两行看看效果。你连工具链和芯片都还没打通，就急着写代码，大概率会卡在第一个报错上动弹不得。这一篇，我们终于要真正落笔了，目标很明确：用C++写出第一行能跑在STM32上的代码，点亮一颗LED。这篇文章会从为什么前三篇不让你写代码讲起，然后带你从硬件连接、工程配置，到三条核心语句、整个while循环，再到常见的排错实录，把整个“编译-下载-运行”闭环完整走一遍。

1. 为什么折腾了三篇才让你动手

1.1 嵌入式入门和Web开发完全是两回事

先说个类比：在Web开发里，你new一个项目，脚手架自动帮你拉好依赖，浏览器就是你的运行环境，改一行代码，刷新就能看到结果。嵌入式完全不是这套逻辑。你面对的是一个裸芯片，没有操作系统帮你管理内存，也没有控制台帮你打印报错，甚至你写的代码能不能跑起来，取决于启动文件、链接脚本、芯片型号选择、调试器连接这些“工程外围”的东西。这些环节任何一个断了，你的代码再对也进不了芯片。所以前几篇花篇幅讲环境搭建、芯片支持包安装、工程模板，都是在给你“磨菜刀”。

很多人会觉得“我就是想写个点灯，看那么细干嘛”。但实际情况是，你跳过了这些直接抄代码，一旦遇到问题，你根本不知道是代码问题还是环境问题。比如编译通过了但烧录失败，你会怀疑ST-Link坏了还是接线错了；烧录成功了但灯不亮，你会怀疑代码逻辑不好还是时钟没配好。我在带人的时候见过太多这种“抄代码半小时、排错一整天”的例子。前三篇不做别的，就是让你把工具链和工程结构摸清楚，把网上教程常常默认你“已经会了”的部分补齐。

也顺便回应一下热词里那些实际需求，比如“keil5兼容c51和stm32安装”“stm32芯片包安装”“vscode配置stm32开发环境”。这些确实都是嵌入式入门的高频场景。前几篇已经分别讲过Keil MDK的安装思路和VSCode作为编辑器搭配编译链的方案，所以这一篇我会默认你的环境已经能编译一个空的STM32工程。如果还没准备好，建议回头补补。不然这篇的代码你就算照着敲，也会编译出一堆“找不到头文件”的错误，那体验就很糟糕了。

1.2 语言选型：为什么是C++而不是纯C

另外还有个必须回答的问题：嵌入式开发里C语言已经够通用了，为什么这一系列还要用C++？这不是为了噱头。STM32的官方固件库和HAL库都是C写的，但这不代表C++没有用武之地。C++的类、封装、作用域隔离、模板这些东西，在工程规模变大之后非常值钱。比如说你后面要驱动多个传感器、多个外设，纯C要靠命名空间前缀和一堆结构体函数指针来模拟“对象”的感觉，C++直接一个类就封装完了，代码复用性和可读性好非常多。

当然，嵌入式C++和桌面C++不是一回事。没有STL容器可以随便用，异常机制在裸机环境里默认也是关掉的，new和delete要慎用。但它保留的类、继承、模板、constexpr这些特性，对写驱动、写状态机、写算法来说已经非常好用了。后面几篇我会展示怎么用C++封装外设驱动，那个优势会比这一篇点灯更明显。点灯这个级别，C和C++看起来差别不大，但我们要从一开始就用C++的思维去组织代码，而不是把C语言换个.cpp后缀就叫嵌入式C++。

2. 动手前坐稳：硬件与软件清单

2.1 硬件怎么选：最便宜的板子也能学到八成东西

新手入门我一般推荐STM32F103C8T6最小系统板，就是俗称的“蓝药丸”或者“Blue Pill”。这板子非常便宜，淘宝上一块大概十几块钱，但该有的东西都有：72MHz主频的Cortex-M3核心、64KB Flash、20KB RAM、一系列GPIO、USART、SPI、I2C、定时器。最重要的是，它的资料量极其惊人，你搜“STM32F103C8T6教程”能搜出几万条结果。哪怕你后面要做的项目根本不是这个型号，学会它的套路之后，换到F4、F7、H7系列也就是改改配置的事。

除了板子，你还需要一个ST-Link V2下载调试器，几块钱到几十块钱都有。另外准备一块面包板、几根杜邦线、一颗LED灯珠（颜色随意，红色或蓝色比较常见）、一颗330欧姆左右的电阻。接线非常简单：用杜邦线把ST-Link的SWDIO接到板子的PA13，SWCLK接到PA14，GND接GND，3.3V接3.3V。然后用另一组杜邦线从板子的PA5引脚引出，串联一个330欧姆电阻，再接LED的正极，LED负极接板子的GND。这里电阻是为了限制电流，防止LED烧坏，330欧姆到1K欧姆问题都不大，但别用10K以上，不然你会看到LED只是微微泛光，亮度非常暗。

为什么选PA5？因为PA5是STM32F103C8T6上最常见的板载LED引脚之一。很多最小系统板上直接焊了一个LED在PC13或者PA1上，但用我们自己外接的LED更自由，可以直观看到引脚定义、接线和电阻的作用。如果你手上的板子有板载LED连接在PC13，那本篇代码改成配置GPIOC的引脚就行，原理一模一样。

2.2 软件怎么配：两种流派我都用过

软件方面，我实测下来比较顺手的就两条路。

一条路是Keil MDK搭配STM32F1系列芯片支持包。Keil的优点是编译速度快，调试界面集成度高，很多老工程师都在用，遇到问题容易找到人问。缺点是Windows下偏多，License管理有点烦人。另一条路是STM32CubeIDE加VSCode的组合。CubeIDE基于Eclipse，免费跨平台，STM32CubeMX图形化配置外设非常方便，生成初始化代码之后，你可以用VSCode打开工程目录来编辑代码。很多人在热词里搜“vscode配置stm32开发环境”“vscode stm32调试powerlink如何设置launch.json”，其实都是在折腾这种方式。CubeIDE本身自带调试功能，不一定要折腾VSCode的launch.json，但如果你喜欢VSCode的编辑体验，把编译和调试命令配进去也是可行的，这个过程以后可以单独写一篇。

不管是哪条路，最后的效果都一样：能新建一个STM32F103C8T6的工程，能编译出一个hex文件，能用ST-Link下载到板子上。这一篇的代码你可以直接用上面任一种工程模板来编译。如果你用的是CubeMX，生成工程时不需要勾选任何中间件，也不需要配置额外的时钟树，直接用默认的HSI内部时钟也可以跑通。但更建议花10秒钟把时钟树切成HSE外部晶振，因为后面做串口波特率、定时器定时的时候，外部晶振的时间基准更准。

3. 第一行代码：让LED亮起来

3.1 从GPIO开始：先把“电”这个事想明白

GPIO的全称是General Purpose Input Output，通用输入输出口。你可以把它想成一排可以手动拨动的小开关，每个引脚都可以配置成输出模式或输入模式。点灯用的就是输出模式。但要真正让这个开关工作，你先得给这一排开关所在的电路送上电，这个“送电”的动作在STM32里就是开启对应GPIO外设的时钟。很多人第一次写STM32代码会忘记这一步，然后灯死活不亮，急得团团转。其实芯片设计者是故意的——为了降低功耗，默认情况下大部分外设的时钟都是关闭的，你用到哪个外设就得先把哪个外设的时钟打开。这个心智模型一旦建立，后面的串口、SPI、I2C都是同一个套路，只是换了个寄存器名称而已。

STM32F103的GPIO配置有两组关键寄存器：CRL和CRH。CRL负责配置端口0到7号引脚的模式，CRH负责配置8到15号引脚。每组寄存器里每个引脚占4位，这4位里又分成MODE位和CNF位。MODE位决定输入还是输出以及输出速度，CNF位决定推挽还是开漏或者复用功能。点灯最简单的方式就是设置成通用推挽输出，输出速度50MHz。这里“50MHz”不是说你真的会输出那么高的频率，而是表示引脚翻转能力的上限，你用低速模式也照样能点亮LED，只是到了后面做PWM或通信时你才会体会到速度档位的影响。

3.2 三行代码点亮LED的核心逻辑

先直接给出核心代码，然后再逐行解释：

#include "stm32f10x.h" int main(void) { RCC->APB2ENR |= RCC_APB2ENR_IOPAEN; GPIOA->CRL &= ~(0xF << 20); GPIOA->CRL |= (0x2 << 20); GPIOA->BRR = GPIO_BRR_BR5; while(1) { } }

这段代码的逻辑其实非常简单。第一行RCC->APB2ENR |= RCC_APB2ENR_IOPAEN;就是打开GPIOA的时钟。RCC是Reset and Clock Control的缩写，负责整个芯片的时钟管理。APB2ENR是挂在APB2总线上的外设时钟使能寄存器，GPIOA恰好挂在这条总线上。IOPAEN这个宏展开之后是((uint32_t)0x00000004)，对应第2位。往这一位置1，GPIOA的时钟就通了。在C++里这段代码和C没什么区别，操作的都是同一个寄存器的地址，但我建议你从一开始就养成习惯，尽量用寄存器库提供的宏名而不是裸数字，这样别人看代码时才不会被一串十六进制搞晕。

第二段是配置PA5的模式。CRL寄存器的第20到23位正好对应第5号引脚（因为每个引脚占4位，5乘以4等于20）。先把这4位清零，然后写入0x2。0x2是通用推挽输出、速度50MHz的编码。如果你写0x3也可以，那是输出速度100MHz的一种配置，但在F103上推挽输出只有2MHz/10MHz/50MHz三档，0x3被映射到50MHz，所以很多老工程里也能看到0x3。这里最需要注意的是别把整个寄存器都赋成一个值，而要用“先清零、再赋值”的套路，这样不影响其他引脚的配置。

第三行是点亮LED的关键：让PA5输出低电平。GPIOA->BRR = GPIO_BRR_BR5;中的BRR是位复位寄存器，往对应位置1就能让该引脚输出低电平。为什么低电平会点亮LED？因为我们把LED接在PA5和GND之间，PA5输出低电平时，电流从LED正端流向负端，正好形成回路。如果你的LED接法是反过来的，那就要用BSRR寄存器置位，让引脚输出高电平才能点亮。我这里先选了低电平点亮，接线图也按这个来，等你自己接线时务必分清正负极。

3.3 让LED呼吸起来：延时与循环

如果代码止步于上面那段，LED只会一直亮着，虽然也算成功，但看起来太静态了。更直观的成就感来自闪烁。要让LED闪烁，核心就一句话：在循环里不停地翻转引脚状态，中间夹一个等待时间。

先看完整代码：

#include "stm32f10x.h" void delay_soft(volatile uint32_t count) { while(count--) { } } int main(void) { RCC->APB2ENR |= RCC_APB2ENR_IOPAEN; GPIOA->CRL &= ~(0xF << 20); GPIOA->CRL |= (0x2 << 20); while(1) { GPIOA->BSRR = GPIO_BSRR_BR5; delay_soft(7200000); GPIOA->BSRR = GPIO_BSRR_BS5; delay_soft(7200000); } }

这里面有意思的地方在于BSRR这个寄存器。BSRR是一个32位寄存器，低16位用于置位（Set），高16位用于复位（Reset）。往低16位的对应位置1，引脚输出高电平；往高16位的对应位置1，引脚输出低电平。也就是说，往同一个寄存器里写不同的位，就能同时控制若干个引脚的输出状态，而且写的过程是原子性的。相比之下，直接操作ODR寄存器会产生“读-改-写”三步操作，如果在中断里对同一个引脚操作，可能产生竞争条件。我一开始学的时候没这个概念，后来做PWM和通信协议时才明白，BSRR这种设计就是为了避免多任务下的竞争问题，STM32每个GPIO都标配这个寄存器，比单纯一个ODR灵活得多。

延时函数里我用了一个volatile uint32_t count。volatile告诉编译器：这个变量可能会被外部修改，不要把它优化掉。否则，像while(count--)这种空循环，在开优化的情况下很可能被编译器整个删掉，代码烧进去灯就会一直亮着不闪，又或者闪烁极快到肉眼无法分辨。这个坑我在O2优化下踩过不止一次，后来学乖了，凡是被刻意用作延时的循环变量都加上volatile。当然真正的工程里不会用这种靠猜的软延时，而是用SysTick或定时器来计时，后面讲定时器时会专门展开。但作为第一次点灯，软延时最直观，也最容易理解“CPU在空转”这个概念。

编译下载过程很简单。Keil里按F7编译，如果0 error 0 warning，按F8下载。CubeIDE里先锤子图标编译，再点绿色虫子或下载按钮。下载完成后按下板子上的复位键，正常情况下你会看到LED以大约1Hz的频率闪烁。这里的延时参数7200000，在72MHz主频下大约是0.1秒级的一个循环时间，因为每条指令要耗费几个时钟周期，空循环还有个跳转开销，所以真实延时大概在0.1秒到0.2秒之间。看着会有点闪烁感，但完全能识别出来。嫌太快就把计数值加到10000000以上，嫌太慢就往下减，通过这个调参过程，你会对手里的芯片主频有一个体感认知。

4. 从单文件到小工程：用C++组织代码

4.1 为什么要把代码拆开

上一篇我们那些代码全塞在main.cpp里，足够写“Hello World”了，但如果一直这么干，代码很快就会膨胀成一个大杂烩。点灯只是一个GPIO外设的初始化+翻转，要是你后面同时操作按键、OLED屏、超声波传感器，谁都能想象main.cpp会变成什么惨状。所以从这一篇开始，我们要养成“外设驱动模块化”的习惯，这也是C++真正发挥优势的地方。

我们可以把LED相关的操作封装成一个简单的类。头文件led.h这样写：

#ifndef LED_H #define LED_H #include "stm32f10x.h" class Led { public: Led(GPIO_TypeDef* port, uint16_t pin); void on(); void off(); void toggle(); private: GPIO_TypeDef* _port; uint16_t _pin; }; #endif

然后led.cpp实现这些方法：

#include "led.h" Led::Led(GPIO_TypeDef* port, uint16_t pin) : _port(port), _pin(pin) { } void Led::on() { _port->BSRR = _pin; } void Led::off() { _port->BSRR = static_cast<uint16_t>(_pin << 16); } void Led::toggle() { if (_port->ODR & _pin) { _port->BRR = _pin; } else { _port->BSRR = _pin; } }

这里有个小细节：off()里用了_pin << 16，把低16位的引脚编号移到高16位，这样正好落在BSRR寄存器的复位区内。但注意要把这个结果转换成uint16_t或者直接用uint32_t运算，因为_pin本身是16位的，左移16位可能溢出。实际在C++里移位操作发生在int提升之后，所以_pin << 16在32位环境下是OK的，但养成显式处理位宽的习惯更稳妥。你还可以在构造函数里顺带完成GPIO时钟使能和模式配置，不过那样Led类就要知道RCC和CRL这些细节，耦合度稍高。我倾向于让外部先把引脚初始化做好，Led类只负责“高电平、低电平、翻转”这些控制操作，职责单一。

main.cpp就用这个类来点灯：

#include "led.h" void delay_soft(volatile uint32_t count) { while(count--) { } } int main(void) { RCC->APB2ENR |= RCC_APB2ENR_IOPAEN; GPIOA->CRL &= ~(0xF << 20); GPIOA->CRL |= (0x2 << 20); Led led(GPIOA, GPIO_Pin_5); while(1) { led.toggle(); delay_soft(7200000); } }

对比一下第一篇的所有代码，你会发现main.cpp清爽很多。后面如果要加一个按键控制，你就再写个Button类；要加一个蜂鸣器，就再写个Buzzer类。每个文件只关心自己的外设，出了问题直接打开对应文件排查，不用在几千行的main.cpp里大海捞针。这就是封装的意义，C++的class在这里不是花架子，而是实打实的工程组织工具。

4.2 编译优化、链接脚本与资源约束

很多新手写完代码后发现一个诡异现象：同样的代码，Debug模式下闪烁正常，Release模式下灯常亮。这通常是编译器优化造成的。前面说过，软延时循环里的计数变量如果没有volatile，-O2下可能被直接优化掉，整个循环消失。另外你向GPIO->BSRR连续写同一个引脚，编译器也可能认为“这是重复的语句”，把中间的操作合并掉，导致引脚只翻转了一次。解决办法除了加volatile，还可以用内嵌汇编或者直接改用SysTick硬件定时器。这也是我强烈建议你尽早告别软延时、转到硬件定时器的原因。

说到编译优化，就绕不开链接脚本和资源约束。STM32F103C8T6的Flash是64KB，RAM是20KB。一个空工程大概占多少？编译器生成的map文件里写得很清楚。在Keil里编译后点“Browse Information”或者在工程目录下找.map文件，能看到各段的大小：text段（代码）、data段（初始化数据）、bss段（未初始化数据）。我试过，一个LED类加上main函数，Flash占用还不到2KB，RAM占用几乎可以忽略。这看似很宽裕，但如果你后面用STL容器、异常处理、模板元编程，Flash占用会急剧膨胀。嵌入式C++有一条不成文的规矩：能用值传递就别用动态分配，能在上电时静态分配就别运行时new，能不用异常就不用异常。不是因为“嵌入式就该这样”，而是资源真的有限，而且很多MCU的异常处理实现会直接拖慢中断响应。

在编译优化级别上，我的个人经验是：调试阶段用-O0，发布阶段用-O2。但-O2之后要重点检查延时、打印、协议栈这类对时序敏感的代码。有些bug在-O0下完全不存在，一开-O2就出现，这种问题大部分是未定义行为或寄存器操作被编译器重排，排查起来非常头疼。所以从一开始写寄存器操作时，遇到那种“不应该被随便改动顺序”的代码，可以考虑把指针或寄存器地址声明为volatile指针，比如volatile GPIO_TypeDef*，这样编译器就不会对相关语句做激进重排。

5. 排错实录：LED不亮？我建议你按这个顺序查

5.1 常见问题速查表

点灯这个实验看起来简单，但实际带人时发现，卡住的环节五花八门。我把最常见的问题整理成一个表，你如果照做完没亮，按这个顺序排查基本能找到病根。

这个表没法覆盖所有情况，但90%的新手问题落在里面。我特别想强调一点：如果你的LED接法错误，比如正极直接接GND、负极接PA5，那高电平逻辑就反了。别人点灯是输出高电平亮，你是输出低电平亮，代码完全相反。这时候不要硬背“大灯接高电平还是低电平”，而是顺着电流回路理一遍：LED两端只要有电压差，电流就能流过，它就亮。理解这个比记住接线图重要得多。

5.2 我踩过的三个坑

第一是ST-Link接线。第一次用杜邦线连接ST-Link和板子，我把SWDIO和SWCLK插反了，结果Keil一直提示“No target connected”。我当时还以为是驱动问题，重装了驱动、重启了电脑，折腾了一个多小时才发现只是两根线插反了。从那以后我每次接线都先拍一张照片，对照原理图确认一遍再上电。SWD只需要GND、SWDIO、SWCLK三根线就能下载调试，3.3V可以不接，因为很多开发板会自己供电，但如果你用外部供电，电源共地是必须的。

第二是电阻选太大。第一次点灯我手边没有330欧姆的电阻，随手拿了颗10K的用，LED确实亮了，但亮度非常弱，在稍微亮一点的房间里根本看不出来。我一度怀疑是代码有问题，反复检查寄存器配置，后来换了颗1K的电阻，亮度立刻正常。这里也提醒一下：LED限流电阻不是随便选的。普通LED正向压降大约2V，工作电流5mA到20mA，电阻的选择就是要让电流落在合适范围。3.3V出去，减去2V压降，剩1.3V加在电阻上，如果电流想控制在5mA左右，电阻就是1.3V除以5mA约260欧姆，所以330欧姆很合适。有人会说“那我用10K省电不是更好”，但亮度太低会直接影响调试观察，没必要为了省那么点电流给自己添堵。

第三是-O2优化把延时优化掉了。这个前面提过，是我在切换到Release模式时踩的坑。灯不闪了，我还怀疑是芯片坏了，后来在代码里加了volatile之后恢复正常。这件事给我一个很深的教训：在嵌入式里写代码，编译器优化不是“顺便开一下就行”，它是程序行为的一部分。你写每一条语句，都要清楚它在不同优化级别下可能会被怎么处理。很多C语言教程从没说过volatile，但它恰恰是嵌入式C/C++最频繁用到的关键字之一，不是面试八股，是保命用的。

5.3 万用表和示波器要不要买

排错的时候有个趁手工具会事半功倍。万用表是嵌入式入门最值得投资的工具之一，二三十块钱的就能用。量一下PA5对GND的电压，代码里输出高电平时应该是3.3V左右，输出低电平时接近0V。这个测量能立刻告诉你到底是硬件问题还是软件问题。如果是0V恒定不变，可能是引脚配置错了；如果是3.3V恒定不变，可能是BSRR写反了或者程序没跑起来。示波器更直观，但在点灯这个阶段不是必须的，等你后面调UART波特率、I2C时序时再考虑。

6. 点亮之后，你手里有什么

每次帮别人点亮第一颗LED，我都会问一句：你刚才到底做了哪些事？很多人说“写了几行代码，点了个灯”。其实远远不止。你把STM32的时钟树打开了一个分支，你配置了一个GPIO引脚的电气模式，你往一个特定地址写入了特定数值，你经历了编译、链接、下载、复位的完整流程，你在一个没有操作系统的裸芯片上让代码真正“跑”了起来。这一整套流程，比“LED亮了”这个结果重要得多。后面做串口、定时器、中断，甚至跑RTOS，底层都是这些你已经验证过的东西。

从这一步往后，学习路线就比较清晰了。先是把串口打通，用printf往PC上打印调试信息，这会让你的排错能力提升一大截；然后试一下SysTick定时器做精准延时，再尝试定时器PWM输出控制LED亮度，感受呼吸灯效果；接着可以接一个按键，用外部中断检测输入，体会中断响应的时序概念。等你把这些基础外设都过了一遍，你就会发现网上那些项目，比如超声波测距、OLED显示屏菜单、报站器，其实都是这些外设的组合应用，代码量未必有多大，但每一条你都能看懂为什么这么写。

最后分享一个我自己的体会：点灯这个实验，我第一次做的时候卡了整整三天，不是代码难，而是那时候没人告诉我ST-Link还要接GND共地。三天里我把寄存器改来改去，始终以为是软件问题。后来无意中接上地线，灯亮了的一瞬间，我感觉不是LED亮了，而是整个嵌入式世界的大门向我打开了。希望这篇能帮你少走一点我当年走过的弯路，顺利把第一行代码真正写进芯片里。