STM32CubeIDE从零搭建C8T6纯标准库工程

STM32F103C8T6 这颗芯片在圈子里火了快二十年，最小系统板便宜到一杯咖啡的价钱，资料堆得比芯片本身还厚。但这两年有个挺尴尬的现状：教程里九成还在讲 Keil 加标准库（SPL），而新一代开发者手里的工具链已经换成了 STM32CubeIDE。于是大量人卡在同一个问题上——想用 CubeIDE，又想沿用熟悉的标准库 API，结果新建工程一通操作，生成的全是 HAL 代码，把 HAL 目录删掉之后满屏红色报错。这篇就专门讲这件事：怎么在 STM32CubeIDE 里从零搭出一套纯标准库工程，配置项逐个抠清楚，顺带把我自己踩过的坑和排查思路摊开说。

1. 为什么我宁愿在CubeIDE里手工搭一套标准库工程

先说结论：这不是一条"更先进"的路，而是一条"更省心"的路，而且省心的对象很具体——那些不需要复杂外设栈、不需要 USB 协议栈、不需要 RTOS 全家桶的项目。这类项目占了实际开发的一大半，用 HAL 反而是拿高射炮打蚊子。标准库的 API 直白、寄存器映射清晰、编译产物小，对于要"看懂每一个 bit"的场合依然是最合适的。

1.1 SPL、HAL、LL三套库的定位差别，先摆清楚

很多人把这三者当成"新旧版本"，其实定位完全不同。SPL（Standard Peripheral Library）是寄存器级的外设封装，一个外设一个.c文件，函数命名规则是"外设_动作"，比如USART_SendData、GPIO_SetBits。它不抽象硬件差异，也不管理时钟树，RCC_APB2PeriphClockCmd这种开时钟的活儿要你自己显式调用。好处是所见即所得，坏处是可移植性差，换一颗 F4 基本要重写。

HAL 是另一套思路，它把外设抽象成"句柄 + 状态机 + 回调"，配合 CubeMX 做图形化配置，跨系列移植成本低。代价是代码层级深、编译产物大、出问题时调用栈能翻七八层。LL 则是 HAL 的补充，本质上是"带寄存器的薄封装"，介于两者之间。

对一个跑在 64KB Flash 上的 C8T6 来说，HAL 的很多抽象其实是负担。我做过对比：同样一个"点灯 + 串口打印"的空壳程序，HAL 版本编出来大概 10KB 出头，SPL 版本 3KB 左右。省下来的不是 Flash 容量本身，而是启动时间、调试时的可读性，以及你排查问题时不用在一堆HAL_StatusTypeDef里绕圈。

1.2 CubeIDE配标准库，真正省掉的是哪几件事

以前大家用 Keil 加标准库，图的是"模板一拷就能跑"。但 Keil 的问题也很实在：商业授权、Windows 独占、.uvprojx这种 XML 工程文件在多人协作时几乎没法做 diff、命令行构建能力弱。而 CubeIDE 底层是 Eclipse CDT 加 GNU 工具链，工程本质上就是一堆源文件加编译参数，make能直接跑，CI 里也能用。

所以这套组合的真实价值是：保留你熟悉的标准库 API，同时拿到一套免费、跨平台、可版本化、可自动化的构建系统。学习成本集中在一次性配置上，配完之后你得到的是一套干净、透明、随时能接管的老派工程，而不是被 CubeMX 的.ioc文件绑定住的生成物。

还有一点很实际：CubeIDE 自带 GCC 编译器和 GDB 调试器，反汇编、内存查看、SWV 打印这些能力都在，调试体验不输商业 IDE。对需要长期维护的老项目来说，工具链的可获取性比功能多寡更重要。

1.3 丑话说在前面：这条路不适合谁

得诚实一点。标准库最后一版停在 V3.5.0，官方早就不维护了，新系列（G0、G4、H5 这些）根本没有 SPL 版本。如果你的项目要用 USB、以太网、文件系统、低功耗框架，或者未来有换芯片的打算，HAL 加 CubeMX 才是正确选择，硬扛标准库只会把自己埋进坑里。

另外，C8T6 只有 64KB Flash 和 20KB RAM，一旦上 RTOS 加协议栈，标准库那点体积优势还不如你优化两行代码来得明显。所以我的判断标准很简单：纯裸机、外设不超过五六个、没有中间件需求、需要逐位控制时序，满足这几条就放心用标准库；只要有一条不满足，老老实实上 HAL。

2. 工程骨架怎么搭：从空工程到能编译的第一步

配置这件事，最怕的是一上来就在旧工程上打补丁。正确的做法是先建一个"什么都没有"的空壳，把编译器和链接器跑通，再往里一块一块加代码。这样每加一步你都知道是谁的问题，而不是最后面对一堆报错无从下手。

2.1 别从CubeMX工程里砍HAL，直接建裸工程

新手最常见的错误操作是：新建 STM32 工程，CubeMX 弹窗里随便点两下生成，然后把Drivers/STM32F1xx_HAL_Driver整个目录删掉，再把main.c里 HAL 的初始化全注释掉。这么干的结果是.cproject里还挂着 HAL 的头文件路径，链接脚本还是按 HAL 版本调整过的，.ioc文件还在后台偷偷参与生成，下次一构建又全回来了。

正确的入口是 CubeIDE 的另一个新建项：File → New → C/C++ Project，在模板列表里选STMicroelectronics STM32 MCU，点 Next，器件选STM32F103C8Tx，工具链选MCU ARM GCC，构建配置勾上 Debug 和 Release，然后 Finish。这样生成出来的工程不带任何 HAL 源码，只有一个空的main.c、一份 GCC 汇编启动文件startup_stm32f103c8tx.s、一份链接脚本STM32F103C8TX_FLASH.ld，以及syscalls.c、sysmem.c这两个 newlib 适配文件。

这套骨架就是我们要的地基。它已经解决了芯片型号匹配、向量表定义、内存布局这些问题，剩下的只是把标准库塞进去。

2.2 目录结构：SPL源码和CMSIS怎么摆

标准库压缩包解压后目录很碎，直接整个拖进工程会让 Include 路径变成一长串。我习惯整理成下面这样，跟 CubeIDE 的默认习惯对齐：

Project/ ├── Core/ │ ├── Inc/ (main.h, stm32f10x_conf.h, stm32f10x_it.h) │ └── Src/ (main.c, stm32f10x_it.c) ├── Drivers/ │ ├── CMSIS/ │ │ ├── core_cm3.h │ │ ├── core_cm3.c │ │ ├── stm32f10x.h │ │ └── system_stm32f10x.c / .h │ └── SPL/ │ ├── inc/ (stm32f10x_gpio.h 等全部头文件) │ └── src/ (stm32f10x_gpio.c 等全部源文件) ├── Startup/ │ └── startup_stm32f103c8tx.s └── STM32F103C8TX_FLASH.ld

这里有个容易被忽略的细节：system_stm32f10x.c里包含SystemInit()和SystemCoreClock的定义，而启动文件的Reset_Handler会在跳进main之前调用SystemInit。这个文件必须编进工程，否则链接时会报undefined reference to 'SystemInit'。同样，core_cm3.c提供__STREXB、__CLZ这类内核内联函数的实现，虽然在 GCC 下大部分会被头文件里的内联版本替代，但保守起见还是加上。

还有一个取舍：SPL 的src目录下十几个.c文件，我是建议先全部加进来，等工程稳定了再把没用到的从构建里排除（右键 → Resource Configurations → Exclude from Build）。前期图省事，后期再瘦身。

2.3 三个宏定义，缺一个就编译不过

这一步是整个配置里最容易卡住新人的地方。标准库的stm32f10x.h开头有一段条件编译，如果你没定义器件密度宏，它会直接抛出：

#error "Please select first the target STM32F10x device used in your application (in stm32f10x.h file)"

这三个必须定义的宏分别是：

C8T6 是 64KB Flash，属于 Medium Density，所以是STM32F10X_MD。这里有个很多人搞混的点：SPL 里还有_LD（小容量 16-32KB）、_HD（大容量 256-512KB）、_XL（超大容量）、_CL（互联型）。选错了不会立刻报错，但会导致中断向量表偏移、外设寄存器地址不对，运行起来行为诡异，极难排查。

宏加在哪里？右键工程 → Properties → C/C++ Build → Settings → MCU GCC Compiler → Preprocessor，在 "Defined symbols" 里逐行添加。注意不要带=号，STM32F10X_MD直接写名字就行；HSE_VALUE=8000000这种带值的才用等号。

3. 编译与链接参数：从一堆红字反推配置

骨架搭完点构建，大概率还是红的。别急，CubeIDE 的报错信息其实很有指向性，只要你能读懂它在抱怨什么，配置就是按图索骥的事。

3.1 Include路径与预处理宏的填法

Include 路径在C/C++ Build → Settings → MCU GCC Compiler → Include paths里加。我一般按这个顺序填：

"${workspace_loc:/${ProjName}/Core/Inc}" "${workspace_loc:/${ProjName}/Drivers/CMSIS}" "${workspace_loc:/${ProjName}/Drivers/SPL/inc}"

用${workspace_loc}变量而不是绝对路径，是为了让工程能被别人 clone 下来直接编译。绝对路径一旦换机器就全废，这是团队协作里最常见的"在我电脑上是好的"翻车现场。

这里有个小技巧：如果发现某些头文件死活找不到，可以在C/C++ General → Paths and Symbols → Includes → GNU C里也加一遍。CubeIDE 有两套路径配置，一套给编译器用，一套给索引器用，只配前者会导致编译通过但编辑器里全是红波浪线，看着糟心。

顺带提一句stm32f10x_conf.h。这个文件的作用是"选择性包含外设头文件"，里面默认把所有外设的#include都打开了，没用的可以注释掉。它不参与编译产物，只影响编译时间和头文件依赖，注释掉不需要的外设能让增量编译快不少。

3.2 启动文件到底用哪一份

标准库压缩包里的startup目录下有arm/、gcc_ride7/、iar/三个子目录。很多人下意识地把 Keil 那份startup_stm32f10x_md.s拷进 CubeIDE 工程，然后编译器甩出一堆bad instruction、unexpected token——因为那是 ARM 汇编器语法（AREA、EXPORT、DCD），GCC 的as根本不认。

两个选择：一是用标准库gcc_ride7目录下的 GCC 版本，二是直接沿用 CubeIDE 生成的startup_stm32f103c8tx.s。我更倾向后者，原因很实在：它由 CubeIDE 按具体型号生成，向量表项和芯片实际中断数量严格对应，省掉了"MD 版本的向量表到底有几个外部中断"这种核对工作；而且里面已经写好了Default_Handler的死循环和weak属性，符号命名（WWDG_IRQHandler、USART1_IRQHandler）跟 SPL 的stm32f10x_it.c完全对得上。

只有一个地方要留意：CubeIDE 生成的启动文件里，栈顶符号叫_estack，堆栈大小定义在链接脚本里（_Min_Stack_Size、_Min_Heap_Size）。如果你习惯在启动文件里手改栈大小，得改链接脚本而不是.s文件。

3.3 syscalls、newlib和那一串undefined reference

第一次点构建，如果链接阶段报出这一串：

undefined reference to `_write' undefined reference to `_sbrk' undefined reference to `_close' undefined reference to `_exit'

不用慌，这是 newlib 在跟你要系统调用。裸机上没有操作系统，这些函数原本是给 POSIX 环境准备的。两条路解决：一是加链接参数-specs=nosys.specs，用一套空实现顶上去；二是保留 CubeIDE 生成的syscalls.c（里面已经把_write、_read、_sbrk都写成了带__attribute__((weak))的桩函数）。

我推荐后者，因为syscalls.c里的_write会循环调用__io_putchar(int ch)，而__io_putchar是 weak 的——这意味着你可以在自己的代码里重写它，一行不改就完成 printf 重定向。用nosys.specs虽然省事，但后面想做 printf 输出还得自己补_write，绕回来了。

链接参数的完整配置我一般是这样：

-mcpu=cortex-m3 -mthumb -mfloat-abi=soft -T"${workspace_loc:/${ProjName}/STM32F103C8TX_FLASH.ld}" -specs=nano.specs -specs=nosys.specs -Wl,--gc-sections -Wl,-Map="${ProjName}.map" -Wl,--print-memory-usage

注意nano.specs和nosys.specs可以同时用，前者是精简版 C 库（体积小很多），后者是空实现系统调用。用了nano.specs之后要记住一个副作用：printf的浮点格式化默认被裁掉了，要打印%f必须额外加-u _printf_float。

3.4 裁剪与优化：让Hex瘦下来的组合拳

编译选项上，我建议 Debug 配置用-Og（GCC 专门为调试做的优化级别），Release 用-Os。别在调试阶段用-O0，它会让代码体积膨胀两三倍，对于 64KB Flash 的芯片来说很容易撞墙；也别用-O2做单步调试，变量会被优化得"凭空消失"，看寄存器比看变量还累。

体积优化真正有效的是这三件套：

• -ffunction-sections -fdata-sections：让每个函数、每个变量单独成段
• -Wl,--gc-sections：链接时把没被引用的段直接扔掉
• -fno-common：避免未初始化的全局变量被合并成公共符号

实测下来，SPL 的空工程加上这三条，能从 4KB 出头压到 2.8KB 左右。听起来不多，但当你后面要接一个 20KB 的协议栈时，这点余量就是能不能塞进去的区别。

还有一个细节：-Wl,--print-memory-usage会在每次构建结束时打印 Flash 和 RAM 的占用百分比。这个小功能看起来不起眼，但它是防止"某天加了个大数组，RAM 静默溢出，程序跑飞"的第一道防线。

4. 跑通验证：点灯、串口、中断三件套

配置对不对，光看编译通过不算数。我一般用"点灯、串口、中断"这三步做验证，因为它们分别覆盖了 GPIO 时钟、外设初始化和中断向量三个最容易配错的地方。三步都过，基本可以确定工程没问题。

4.1 main.c骨架与SystemInit背后做的事

一个标准库工程的main.c骨架长这样：

#include "stm32f10x.h" static void Delay(__IO uint32_t nCount) { for (; nCount != 0; nCount--); } int main(void) { SystemInit(); /* 配置系统时钟到 72MHz */ RCC_APB2PeriphClockCmd(RCC_APB2Periph_GPIOC, ENABLE); GPIO_InitTypeDef gpio; gpio.GPIO_Pin = GPIO_Pin_13; gpio.GPIO_Mode = GPIO_Mode_Out_PP; gpio.GPIO_Speed = GPIO_Speed_50MHz; GPIO_Init(GPIOC, &gpio); for (;;) { GPIO_ResetBits(GPIOC, GPIO_Pin_13); Delay(0xFFFFF); GPIO_SetBits(GPIOC, GPIO_Pin_13); Delay(0xFFFFF); } }

注意SystemInit()这一行。严格来说启动文件已经调用过它了，你在main里再调一次是冗余的，但很多人习惯保留，因为显式写出来心里有底。它做的主要工作是配置 HSE 起振、开 PLL、把 SYSCLK 拉到 72MHz、设置 AHB/APB 分频。这一切的前提是HSE_VALUE跟你板子上的晶振频率一致。

SystemCoreClock这个全局变量也会在这里被赋值成 72000000，后面做 SysTick 定时的计算都依赖它。如果实际时钟跑不到 72MHz，这个变量依然是 72MHz，结果就是延时函数慢了好几倍——这是后面第 5 章要展开讲的经典坑。

至于Delay这种空循环，只能用来点灯看效果，别拿去做通信时序。真要延时，用 SysTick 或者定时器。

4.2 GPIO点灯与PB3/PB4那个老坑

C8T6 的最小系统板上，板载 LED 一般挂在 PC13。这颗引脚没有复用，直接用没问题。但如果你要用的引脚正好是 PB3、PB4、PA15 中的一个，就会遇到那个让无数人抓狂的现象：代码写得完全正确，引脚就是没反应。

原因是这几个引脚上电后默认被 JTAG 占用（JTDO、NJTRST、JTDI），归属调试接口而不是普通 GPIO。要用它们做普通 IO，必须先关掉 JTAG。关键是"关掉 JTAG 但保留 SWD"，因为 PA13、PA14 是 SWD 的 SWDIO 和 SWCLK，全关了就没法下载和调试了：

RCC_APB2PeriphClockCmd(RCC_APB2Periph_AFIO, ENABLE); GPIO_PinRemapConfig(GPIO_Remap_SWJ_JTAGDisable, ENABLE);

这两行的顺序不能反，AFIO时钟不开，重映射寄存器写不进去。而且这个操作必须在配置 GPIO 之前做，否则引脚已经锁成调试功能了，再改配置会无效。我第一次踩这个坑的时候，对着万用表量了半个小时电平，最后发现是 remap 没开，那种感觉懂得都懂。

另外提醒一句：一旦关了 JTAG，PB3 就不能再拿来做 SWO 输出了。SWV 打印和 GPIO 复用只能二选一。

4.3 printf重定向在GCC下的正确写法

Keil 时代重定向printf是重写fputc，到了 GCC 加 newlib 环境，这套不灵了，得从_write或者__io_putchar下手。前面说过 CubeIDE 生成的syscalls.c里_write会循环调用__io_putchar，所以我们只要重写它：

#include "stm32f10x_usart.h" int __io_putchar(int ch) { while (USART_GetFlagStatus(USART1, USART_FLAG_TXE) == RESET); USART_SendData(USART1, (uint8_t)ch); return ch; }

这个写法有个坑：__io_putchar在syscalls.c里是 weak 定义，你在自己文件里再定义一次，链接器会用你的强符号。但如果两个都是弱符号，行为就不确定了。所以千万别手贱把自己写的也加上__attribute__((weak))。

串口初始化的代码就不展开了，标准库那套USART_InitTypeDef五六个字段填一遍。真正要注意的是波特率计算：USART_Init内部依赖RCC_GetClocksFreq()拿到 APB2 的实际频率，如果系统时钟没跑对，波特率就会偏，现象是串口助手收到一堆乱码。这时候别怀疑串口模块坏了，先去确认时钟。

还有printf换行的问题。newlib 的行缓冲策略在裸机上表现不稳定，有时候明明打了\n数据却没出去。稳妥做法是每次打印完手动fflush(stdout)，或者干脆在你的__io_putchar里不管缓冲，一个字节一个字节直接发——单片机这点数据量，效率损失可以忽略。

4.4 中断向量与stm32f10x_it.c的对应关系

标准库模板里有个stm32f10x_it.c，里面预置了HardFault_Handler、SysTick_Handler、PendSV_Handler这些内核异常的空实现。这个文件不是必须的，但强烈建议保留，把中断服务函数都集中放这里，别散落在各个业务文件里。

命名一定要和启动文件里的向量表一致。startup_stm32f103c8tx.s里弱定义的名字是USART1_IRQHandler，你写成USART1_IRQHandler(void)才能覆盖它；写成USART1_Handler或者Usart1_IRQHandler（大小写不同）都不会报错，但中断永远进不去，因为它连着的是你的函数而不是向量表项。这个坑隐蔽性极强，因为编译链接全程无警告。

配中断还有两步不能漏。第一是开 NVIC：

NVIC_InitTypeDef nvic; nvic.NVIC_IRQChannel = USART1_IRQn; nvic.NVIC_IRQChannelPreemptionPriority = 1; nvic.NVIC_IRQChannelSubPriority = 1; nvic.NVIC_IRQChannelCmd = ENABLE; NVIC_Init(&nvic);

第二是开外设侧的中断使能，比如USART_ITConfig(USART1, USART_IT_RXNE, ENABLE)。这两个是"与"关系，少一个都不响应。Strictly 来说NVIC_PriorityGroupConfig也要在main开头调一次，全局定好抢占和响应的位数分配，否则后面配的优先级数值含义会跟你想的不一样。

5. 踩坑记录：几类最费时间的报错与排查链路

前四章讲的是"应该怎么做"，这一章讲"做错了会怎样"。我把这几年在这套组合上遇到问题按阶段归了归类，每一类都附上我实际的排查顺序——重点不在于答案，而在于下次遇到新的报错时你知道从哪儿下手。

5.1 编译期：器件宏、启动文件语法、core_cm3兼容

编译期的问题最好排查，因为编译器会把位置指给你。但有三类报错特别有迷惑性。

第一类是#error "Please select first the target STM32F10x device..."。这个前面说过，是器件密度宏没定义。但还有一种情况：宏定义了，仍然报这个错。这时候要检查宏是不是定义在了正确的构建配置下——CubeIDE 的 Debug 和 Release 是两套独立配置，你在 Debug 里加了宏，切到 Release 一编译又红了。排查方法是看构建控制台输出的编译命令行，里面有没有-DSTM32F10X_MD。

第二类是启动文件的语法错误，典型报错是Error: bad instruction 'dcd Reset_Handler'或者unexpected characters at end of line。这百分之百是用了 ARM 汇编器版本的.s文件。判断方法很简单：打开文件看开头，如果是AREA RESET, DATA, READONLY就是 Keil 版，如果是.syntax unified加.thumb就是 GCC 版。

第三类比较少见但很折磨人：core_cm3.h相关的__ASM、__INLINE未定义。SPL V3.5.0 的core_cm3.h里对编译器做了分支判断（__CC_ARM、__ICCARM__、__GNUC__），理论上 GCC 分支是有的，但如果你的工程里混进了别的版本的头文件（比如从别的工程拷来的core_cm3.h），或者 Include 路径顺序导致先找到了旧版本，就会出问题。排查办法是在 Eclipse 里按住 Ctrl 点#include "core_cm3.h"，看它跳到了哪个文件，路径不对就调整 Include 顺序。

顺便说个我遇到过的诡异情况：某次工程里同时存在Drivers/CMSIS/core_cm3.h和Drivers/SPL/inc/core_cm3.h两份，编译时好时坏，最后发现是两份文件里的__NVIC_PRIO_BITS定义不一致导致的。所以拷库的时候一定要检查有没有重复文件，宁可多花十分钟核对目录。

5.2 运行期：时钟对不上导致串口乱码与延时失准

这一类问题最消耗时间，因为编译链接全过，下载也成功，就是行为不对。

最典型的现象是串口全乱码。第一反应通常是波特率配错了，但改了还是乱。这时候要按这个顺序查：先用调试器连上去，在main的第一行停下，读SystemCoreClock变量，看是不是 72000000；再读RCC->CFGR寄存器，看 SWS 位是不是0b10（PLL 作为系统时钟）；再读RCC->CR的 HSERDY 位，看外部晶振到底起没起振。

如果 HSERDY 是 0，说明 HSE 没起来。可能原因有：板子上根本没焊晶振（有些精简板确实省了）、晶振是 12MHz 而HSE_VALUE写的 8MHz、负载电容不匹配导致起振慢。system_stm32f10x.c里的SetSysClockTo72对 HSE 起振是有超时判断的，起不来它会跳过 PLL 配置，但函数结束时SystemCoreClock依然被赋值成 72000000——这就是最坑的地方，变量在撒谎，实际时钟还停在 HSI 的 8MHz。于是你的波特率计算全部按 72MHz 来，实际跑的却是 8MHz，偏差九倍，串口当然全是乱码。

延时失准是同一个根因的另一种表现。你用 SysTick 配 1ms 中断，结果实际是 9ms，按键消抖、传感器时序全乱套。所以我的习惯是在main开头加一段自检：

if (RCC_GetFlagStatus(RCC_FLAG_HSERDY) == RESET) { /* 时钟降级运行，用 GPIO 闪灯报警 */ while (1) { GPIO_SetBits(GPIOC, GPIO_Pin_13); for (volatile int i = 0; i < 500000; i++); GPIO_ResetBits(GPIOC, GPIO_Pin_13); for (volatile int i = 0; i < 500000; i++); } }

这段代码在正式产品里当然要去掉，但开发阶段能帮你省掉大量"为什么串口不通"的困惑。

还有一种时钟相关的坑跟重映射有关。SPL 里GPIO_PinRemapConfig(GPIO_FullRemap_USART1, ENABLE)会把 USART1 从 PA9/PA10 挪到 PB6/PB7。改完之后忘了改初始化代码里的端口，串口自然没数据。排查时先看引脚，再看时钟，最后才怀疑外设本身。

5.3 调试期：ST-LINK连不上、下载后不跑

调试阶段的坑分两类：连不上和跑不对。

连不上通常有两种提示。一种是No ST-LINK detected，检查 USB 线、驱动、CubeIDE 里的 ST-LINK 固件版本。另一种是Target not found或者Error in initializing ST-LINK device，这时候问题多半出在板子侧：SWD 的 SWDIO/SWCLK 没接、目标板没供电、或者芯片被设置成了低功耗模式。

有个很典型的情况是"下载过一次之后就再也连不上了"。原因通常是程序里把 SWD 引脚（PA13、PA14）配成了普通 GPIO，或者一上电就进了Standby模式。解决办法是把BOOT0拉高，用系统存储器启动模式上电，这样芯片不会执行你的程序，ST-LINK 就能连上，然后重新烧一个正常的固件。所以我的建议是：任何会操作重映射或者低功耗的代码，第一次烧写前先确认 BOOT0 跳线可操作，别把自己锁死。

跑不对的情况更隐蔽。现象是下载成功、调试器也能连，但程序就是不执行到main。排查第一步看 PC 指针停在哪：如果停在0x08000000附近的Default_Handler死循环里，说明触发了某个异常但没定义处理函数。这时候去看xPSR寄存器的 IPSR 字段，能读出当前是哪个异常号，再对照stm32f10x.h里的IRQn_Type枚举，就知道是哪个中断跑飞了。

我自己遇到过一次，程序反复进HardFault_Handler。最后查出来是栈溢出：链接脚本里_Min_Stack_Size默认给的是 0x400（1KB），我在中断里定义了一个 512 字节的局部数组，加上嵌套调用直接把栈顶顶穿了。把栈改成 0x800 之后问题消失。所以 RAM 只有 20KB 的芯片，一定要养成看.map文件的习惯，确认栈和堆的实际占用。

6. 把老库放进现代流程：版本管理、命令行构建与取舍

配置跑通只是开始，真正决定这套方案能不能长期用的是后面的工程管理。这一章说说我怎么处理版本控制、怎么做脱离 IDE 的构建，以及什么时候该承认"这套东西该换了"。

6.1 工程文件的版本管理边界

用 CubeIDE 做团队协作，.cproject和.project这两个文件一定要提交。它们记录了源文件列表、Include 路径、宏定义、链接参数，不提交的话别人 clone 下来根本编不了。.settings/目录同理，里面存的是代码风格和索引配置。

反过来，Debug/和Release/这两个构建输出目录必须加进.gitignore。里面全是自动生成的.o、.d、.mk文件和最终产物，一旦提交，每次构建都会产生海量 diff，还能把合并冲突搞得没法处理。

还有一类文件值得讨论：.ioc。如果你是从 CubeMX 工程改过来的，这个文件留着会让 IDE 认为工程受 CubeMX 管理，右键菜单里会出现"Generate Code"，手滑点一下就把你手工改的东西覆盖了。纯标准库工程一定要确保没有.ioc残留。

我自己的做法是在仓库根目录放一份README，写清楚工具链版本、库的版本（SPL V3.5.0）、以及"不要点 Generate Code"的警告。看起来啰嗦，但换过几次人之后你会发现这几行字能省掉很多沟通。

6.2 脱离IDE界面：命令行构建与自动化

CubeIDE 生成的工程自带 Makefile 体系，Debug/目录下就有一份makefile。这意味着你完全可以不开 IDE，直接在命令行跑：

# 生成构建目录（首次或改了工程配置后） arm-none-eabi-gcc --version make -C Debug all -j8 # 清理 make -C Debug clean

注意-C Debug这个参数，Makefile 是按构建配置分目录的，Release配置对应make -C Release all。-j8是并行编译，工程文件多的时候能快不少。

这套能力在自动化里价值很大。比如你想做一个"每次提交自动编译并检查体积"的流水线，只要在脚本里跑一遍make，然后读Debug/*.map文件或者用arm-none-eabi-size看.text段大小，超过阈值就报错。这比人工点构建可靠得多，也能防止某次提交不小心把 Flash 用爆。

我在几个小项目里还试过更激进的做法：完全抛开 CubeIDE 的工程文件，自己手写一份顶层Makefile和CMakeLists.txt，源文件用通配符扫描，Include 路径和宏定义集中在一处。好处是任何编辑器都能开发，坏处是调试配置（GDB 的launch.json或者.gdbinit）得自己维护。这套方案适合对构建流程有洁癖的人，团队协作的话还是老老实实用 IDE 工程更省事。

6.3 什么样的项目该继续用SPL，什么该换

用了这么久，我对这套组合的适用边界有了比较清晰的认识。

继续用 SPL 的场景：教学和入门（寄存器到外设的映射关系一目了然）、引脚和时序需要精确控制的场合、Flash 极度紧张的场合、维护已有的老代码库、以及那种"一个芯片一个功能，写完就投产"的小批量产品。这些场景下 HAL 带来的抽象收益几乎为零，反而增加理解成本。

该换的场景：需要 USB Device/Host、以太网、CAN 上加高层协议、文件系统、低功耗框架（HAL_PWR那套确实比裸写寄存器省心）、以及未来半年内可能换芯片的项目。还有一个隐藏指标：如果团队里新人多，HAL 加 CubeMX 的学习曲线明显更平缓，这时候为了"我习惯标准库"而坚持，其实是在给团队挖坑。

至于中间路线，LL 库值得提一句。它在 F1 系列上也有支持，API 风格介于寄存器和 HAL 之间，比如LL_GPIO_SetOutputPin、LL_USART_Enable。体积接近 SPL，但官方还在维护，而且能跟 CubeMX 共存。如果你的项目正在纠结"想用轻量库但又怕 SPL 太老"，LL 是一个被低估的选项。

我个人在这套工程上折腾了挺长时间，最大的体会是：配置阶段的每一分钟投入，都会在后面调试阶段十倍地还回来。那些看起来"多此一举"的显式SystemInit、自检代码、.map文件核对，恰恰是把"玄学问题"变成"确定问题"的关键。另外强烈建议把配好的这套工程打个包存起来当模板，下一个 C8T6 项目直接复制粘贴，改个工程名就能开工——这套目录结构和编译参数，我已经原封不动用了好几个项目，一次都没再重配过。