Keil 5 新建 STM32 标准库工程：Pack、启动文件与宏定义-平芜编程栈

1. 点"New Project"之前，先想清楚工程目录怎么摆

很多人对 Keil 5 新建工程的第一印象是"三步搞定"：Project → New uVision Project → 选芯片 → 完事。真到自己动手，往往卡在第一步就动不了——器件列表是空的、编译一堆红、下载又报找不到调试器。问题不在手速，在于你在点那个按钮之前，脑子里的目录结构和工具链关系没理顺。

Keil MDK-ARM 5（现在归 Arm 维护）本质上是个"壳"：它负责编辑、编译、链接、下载，但芯片的具体描述、启动代码、外设寄存器定义，全都来自外部安装的器件支持包（Device Family Pack，简称 DFP）。所以一个能跑起来的新工程，至少要凑齐三样东西：正确的器件包、匹配芯片容量的启动文件、以及指向库文件目录的头文件路径。缺一样，工程就是半成品。

我建议在动手建工程前，先把目录规划好。标准库时代流传下来的一套目录结构到现在都很好用：

MyProject/ ├── Doc/ # 数据手册、笔记 ├── Libraries/ │ ├── CMSIS/ # 内核相关：core_cm3.h、stm32f10x.h、system_xxx.c │ └── STM32F10x_StdPeriph_Driver/ │ ├── inc/ # 外设驱动头文件 │ └── src/ # 外设驱动源文件 ├── Project/ # Keil 工程文件本体（.uvprojx） ├── User/ # 你自己的 main.c、stm32f10x_conf.h、中断服务函数 └── Output/ # 编译产物 .hex/.axf/.map，单独隔离

这个布局的核心动机是把"别人的代码"和"自己的代码"物理隔开。库文件几乎不会改，放在 Libraries 下；工程配置和编译输出是临时产物，塞进 Project 和 Output。这样你换一台电脑、或者把工程打包发给同事，只要 Libraries 和 User 两个目录跟着走，工程就能原样重建，不会因为 Output 里堆了一堆中间文件而体积暴涨。

我的经验是：Output 目录一定要单独建，并且在 Options for Target 里手动把 Listing、Objects 路径指过去。默认情况下 Keil 会把 .o、.axf、.hex 全部丢在工程文件同级目录，几十个文件混在一起，找 .hex 烧录的时候能翻半天。分开之后，烧录器只认 Output 里的 .hex，逻辑清晰。

注意：目录名和路径尽量用英文，不要出现空格、中文和特殊符号。Keil 的编译器和某些调试脚本对中文路径的处理一直不太稳，路径里带空格会导致链接器找不到库文件，这类问题报错信息很隐晦，排查起来特别费时间。

2. 器件列表空白：Pack 没装全，后面全是无用功

装完 Keil 5，兴冲冲点 New Project，弹出的器件选择框里只有 ARM 自家的几个 Cortex-M 通用型号，ST、NXP、TI 一个都找不到——这是新手遇到的第一个大坑。原因很简单：MDK 5 不再内置厂商的器件库，全部改成按需安装的 Pack。

解决办法是打开 Pack Installer（工具栏那个小盒子图标，或者菜单 Project → Manage → Pack Installer）。里面分三栏：左边是厂商，中间是 Pack 列表，右边是描述。找到你要用的厂商，比如 STM32F1 系列对应的是Keil::STM32F1xx_DFP，点 Install 就行。

这里有个现实问题：Pack Installer 默认从国外服务器拉取，公司网络或者家里网络不稳定的时候，下载进度条能卡到你怀疑人生。我的做法是提前下载离线 .pack 文件。很多厂商和第三方镜像站都会提供打包好的 .pack，下载下来之后直接在 Pack Installer 里用 File → Import 导入，秒装。离线包的好处还在于版本可控——团队协作时大家用同一个 .pack 版本，避免出现"我这能编译你那报错"的诡异现象。

装完 Pack 后还有一层容易忽略的东西：CMSIS 版本。Keil 5 的 RTE（Run-Time Environment）机制依赖 CMSIS Core，如果 Pack 里带的 CMSIS 版本和你工程里手动拷贝的 CMSIS 文件版本不一致，编译时会报重复定义或者找不到__NVIC_PRIO_BITS之类的符号。所以用标准库手动建工程时，我一般不勾选 RTE 里的任何组件，纯手工添加文件，把版本冲突的口子直接堵死。

再补充一点：STM32 的 Pack 命名有讲究，STM32F1xx_DFP覆盖 F101/F102/F103/F105/F107，STM32F4xx_DFP覆盖 F4 系列，选包的时候看清楚自己的芯片属于哪一档。选错了包，虽然器件能选上，但生成的启动文件寄存器地址可能对不上，这类问题表现为"程序能下载但跑飞"，非常难查。

芯片系列	对应 Pack 名称	常见容量档
STM32F1	Keil::STM32F1xx_DFP	LD/MD/HD/CL/XL
STM32F4	Keil::STM32F4xx_DFP	按具体型号
STM32H7	Keil::STM32H7xx_DFP	按具体型号

3. 标准库工程从零到能编译：文件、分组、路径三步走

标准库（Standard Peripheral Library）虽然官方已经不再主推，但大量存量项目、教学板、老产品还在用，所以"标准库新建工程"依然是搜索量很高的话题。下面这套流程我走过几十遍，闭着眼睛都能敲出来，关键是每一步的意图要说清楚。

3.1 从库包里挑出真正需要的文件

拿到STM32F10x_StdPeriph_Lib_V3.5.0这个库包，不要整个复制进去，那样文件太多，编译慢还容易乱。按需挑：

CMSIS 部分（放在Libraries/CMSIS/下）：

stm32f10x.h：寄存器定义总头文件，必须有
system_stm32f10x.c/.h：系统时钟初始化，必须有
core_cm3.c/.h：Cortex-M3 内核访问，必须有
startup_stm32f10x_md.s：启动文件，容量档要和芯片匹配

StdPeriph_Driver 部分（inc和src两个目录整体复制）：

这些是 GPIO、USART、TIM 等外设的驱动，用到哪个编译哪个，全加进去也不影响，Keil 会按需链接。

User 部分（自己建）：

main.c：主程序
stm32f10x_conf.h：外设驱动的开关配置文件，这个文件极其关键，它决定了stm32f10x.h会包含哪些外设头文件。

我踩过的一个坑是：stm32f10x_conf.h里默认把很多外设注释掉了，如果你在 main.c 里调用了USART_Init()却忘了在 conf 文件里取消#include "stm32f10x_usart.h"的注释，编译会直接报"未定义标识符"。报错指向的是 main.c，实际病根在 conf 文件，新手往往在大海捞针。

3.2 新建工程并添加分组

Project → New uVision Project，选好 Project 目录下的保存路径，起个名字。弹出器件选择框，选你的具体型号（比如 STM32F103C8）。紧接着会弹 RTE 配置窗口，直接关掉或者什么都不勾，我们手工加文件。

然后点工具栏的"Manage Project Items"（那个三层方块图标），建分组。我的分组习惯是：

STARTUP：放启动文件
CMSIS：放 core_cm3.c、system_stm32f10x.c
FWLIB：放 StdPeriph_Driver/src 下的所有 .c
USER：放 main.c

分组的本质只是"文件在 IDE 里的逻辑归类"，和物理目录没有强制关系。但清晰的分组能让你在调试时一眼定位到是哪一层出了问题。

3.3 头文件路径与宏定义

这一步是整个工程能否编译成功的分水岭。打开 Options for Target → C/C++ 选项卡：

在Include Paths里添加：

.\Libraries\CMSIS .\Libraries\STM32F10x_StdPeriph_Driver\inc .\User

在Define里填：

USE_STDPERIPH_DRIVER, STM32F10X_MD

这两个宏各有分工，缺一不可，下一节详细拆。

4. 那两行宏定义和启动文件选错，链接报错能查一下午

USE_STDPERIPH_DRIVER和STM32F10X_MD这两行看着不起眼，但它们是标准库工程的中枢开关，理解它们能帮你省下大量排查时间。

USE_STDPERIPH_DRIVER的作用在stm32f10x.h里有明确逻辑：只有定义了这个宏，头文件才会去包含stm32f10x_conf.h。换句话说，不定义它，你就算把 conf 文件改出花来也不会生效，外设驱动统统链接不上，报一堆 undefined symbol。

STM32F10X_MD决定的是启动文件选择、中断向量表大小、以及外设寄存器的地址映射。F1 系列按 Flash 容量分档：

容量档	宏定义	Flash 容量	对应启动文件
小容量	STM32F10X_LD	16–32 KB	startup_stm32f10x_ld.s
中容量	STM32F10X_MD	64–128 KB	startup_stm32f10x_md.s
大容量	STM32F10X_HD	256–512 KB	startup_stm32f10x_hd.s
互联型	STM32F10X_CL	—	startup_stm32f10x_cl.s
超大容量	STM32F10X_XL	512 KB–1 MB	startup_stm32f10x_xl.s

最常见的错误是宏定义选 MD，启动文件却加了 hd，或者反过来。症状是编译能过，但下载后进不了 main，或者进了 main 跑几步就 HardFault。原因是启动文件里的中断向量表长度和芯片实际的中断数量对不上，一旦有中断触发，PC 就跳到无效地址。

还有一种情况：只加启动文件、忘记加宏。这时 Keil 会用默认配置，某些外设寄存器地址会偏，表现为 GPIO 输出没反应。我的习惯是建好工程后立刻确认三件事：Define 里两行宏在不在、启动文件名字对不对、Include Paths 三个路径齐不齐。这三件事确认完，90% 的编译问题就避免了。

5. CubeMX 生成工程导入 Keil 5 的坑

现在更多人用 STM32CubeMX 生成初始化代码，再选 MDK-ARM 工具链导出工程。这条路省事，但导入 Keil 5 时有几个固定的坑。

第一个是Pack 版本不匹配。CubeMX 生成 .uvprojx 时会记录它期望的 DFP 版本，如果你本地装的版本低，Keil 打开时会提示 "Pack missing"，器件信息读不出来，编译按钮直接灰掉。解决办法是去 Pack Installer 里把版本升到 CubeMX 要求的那一档，或者反过来调低 CubeMX 的固件库版本。

第二个是HAL 库路径。CubeMX 会把Drivers/STM32F1xx_HAL_Driver这些目录一起生成出来，工程里的头文件路径也是自动配好的。千万不要手动去动这些路径，一动准出问题。它的相对路径是相对 .uvprojx 文件位置算的，你把工程文件挪个地方，路径全断。所以 CubeMX 工程从生成那一刻起，目录就别再搬。

第三个是RTE 和 HAL 的冲突。CubeMX 生成的工程默认不走 RTE，用的是它自己拷贝的 HAL 源码。如果你又手贱在 RTE 里勾了 CMSIS Core，就会出现两套内核头文件互相打架。我的原则是：CubeMX 工程，RTE 一律不碰。

第四个是启动文件和链接脚本。CubeMX 会根据芯片型号自动选对启动文件，这点比手工建工程省心。但如果你的芯片是"非标准容量"（比如某些 F103 的克隆型号），CubeMX 可能选错档位，需要手动核对.s文件名。

提示：CubeMX 生成的代码是"再生成友好"的，用户代码要写在/* USER CODE BEGIN */和/* USER CODE END */之间。写在区间外的代码，下次重新生成会被覆盖掉，这个坑每年都有人踩。

6. 下载报 no ulink device found：从接线到驱动的排查链路

工程编译通过，点下载，弹窗no ulink device found——这是搜索热度极高的问题，值得单独捋一遍。这条报错的字面意思是"没找到 ULINK 调试器"，但根本原因可能分布在硬件、驱动、配置三层，得顺着链路捋。

第一层，先确认你用的到底是什么调试器。ULINK 是 Keil 自家的调试器，价格不便宜。大部分教学板和开发板配的是 ST-Link 或者 J-Link，如果你手里是 ST-Link 却在 Debug 选项里选了 ULINK，那当然找不到。打开 Options for Target → Debug，下拉框里选对硬件：ST-Link 就选 ST-Link Debugger，J-Link 就选 J-LINK/J-TRACE Cortex。选完点旁边的 Settings，看能不能识别到设备 ID。

第二层，接线。SWD 模式最少要接四根线：SWDIO、SWCLK、GND、VCC（VCC 一般接 3.3V 参考）。很多人只接了 SWDIO 和 SWCLK 两根信号线，忘记接 GND，结果就是时好时坏或者干脆识别不到。另外注意目标板要独立供电，不要指望调试器的供电针脚能带动整块板子。

第三层，驱动的安装。ST-Link 需要装 ST-Link 驱动，装完之后设备管理器里应该能看到 STMicroelectronics STLink dongle。如果显示黄色感叹号，说明驱动没装好，重新装。J-Link 同理，需要装 SEGGER 的驱动包。

第四层，复位方式。Debug → Settings → Reset 方式，默认可能是 SYSRESETREQ。如果芯片跑飞了或者被锁了，这个方式会失效。切换到 Hardware Reset 或者 VECTRESET，往往能救回来。

第五层，芯片被读保护。有些板子出厂或者误操作开了读保护（Code Read Protection），调试器连不上。用 ST-Link Utility 或者 STM32CubeProgrammer 连一下，解除读保护再回来。

排查顺序我建议是：先看配置选对没 → 再看 Settings 能不能识别 → 再看接线和供电 → 最后看驱动和芯片保护。从软件往硬件推，能少拆很多次板子。

报错现象	最可能原因	快速验证
no ulink device found	调试器型号选错	Debug 里换成 ST-Link
No target connected	接线或供电问题	检查 GND、量 3.3V
Cannot access target	芯片被读保护	CubeProgrammer 解锁
时连时不连	SWD 速度太高	降到 1 MHz 以下

7. 新工程建好之后顺手做的几项配置

工程能编译、能下载，只能算及格。真正的老手在建好工程后会顺手调几个配置，让后面开发少受罪。

首先是Output 里的 Create HEX File。它的学名是 Intel HEX 文件，很多离线烧录器、量产工具只认这个格式。养成勾选它的习惯，需要交给产线的时候直接拷 Output 目录里的 .hex 就行。

然后是编码格式。Edit → Configuration → Encoding，中文注释导致的乱码问题十有八九出在这里。团队协作建议统一用 UTF-8，个人电脑上只有你自己用的话，Chinese GB2312 也行，但一定要所有人统一，混用必然乱码，一乱码编译器可能把注释当代码解析，报出莫名其妙的语法错误。

再就是Debug 里的 Browse Information。勾上它之后，右键跳转定义、查看引用会顺畅很多。代价是编译变慢、中间文件变大，但开发阶段这点代价完全值。等要出正式固件了，再关掉它做一次干净的全编译。

Optimization 等级也值得说一句。调试阶段我一般用-O0或者-O1，代码和逻辑一一对应，打断点、看变量都准。-O3下编译器会做大量内联和指令重排，单步调试时你会看到程序"乱跳"，变量值也对不上，以为是 bug，其实是优化在作怪。量产固件再上-O2或-O3压体积、提速度。

还有个小细节：Options for Target → Debug → Settings → Flash Download 里的 Programming Algorithm。这里要勾上你芯片对应的 Flash 算法（比如 STM32F10x 128K 或者对应的具体型号）。算法选错，下载会报 "Flash Download failed" 或者 "Cannot Load Flash Programming Algorithm"。很多人以为这是器件包的事，其实是这里没勾。

最后提一个跨工具链的小心得。如果哪天你要从 Keil 换到 IAR，或者从 IAR 换到 Keil，会发现新建工程的逻辑完全不一样——IAR 是 Workspace 加 Project 两层结构，源文件可以"引用"而不是复制。理解了 Keil 这套"分组只是逻辑归类、宏定义是编译开关、Pack 提供器件描述"的底层逻辑，换工具只是换个壳，核心那几个概念是通用的。我在实际使用中发现，把工程目录、宏定义、调试器配置这三件事在新建阶段一次性理清楚，后面至少能省下几十次"为什么跑不起来"的排查。真正让新手痛苦的从来不是 Keil 的界面，而是这些看不见的配置关系，而它们恰恰是新建工程阶段最容易定下来的东西。