1. 从空文件夹到能编译:为什么 Keil5 建工程第一步不是点“New Project”
Keil5 是 STM32 开发里最常见的代码开发工具之一,但很多人装好后的第一个动作就是 File→New Project,选完芯片就开始往里塞文件。工程当下能编译,过两周换个芯片、换台电脑,头文件路径全断,启动文件也不知道当时选的是哪个容量。血泪经验是:Keil5 新建 STM32 工程真正的第一步不在 IDE 里,而是在文件系统里把 user、library、inc、src 这几个目录先摆好,IDE 最后只是来认这个骨架。这篇面向刚上手 STM32F103、或者每次建工程都要翻旧工程抄路径的人,从空文件夹开始,把芯片选型、CMSIS 文件落位、Define 与头文件路径、.c/.h 加入工程、ST-Link 下载这几步走完,并指出最容易翻车的几个参数。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 工程目录先定骨架:user、library、inc、src 各自装什么
2.1 为什么先建文件夹再开 IDE
Keil5 的工程文件不负责“打包”源码,它记录的是文件在磁盘上的位置和编译配置。先 New Project 再随手把 .c 从桌面拖进来,工程里就会出现一堆绝对路径;换一台机器,或者把工程发给别人,路径对不上,编译第一行就报找不到文件。先建目录骨架,等于先把“编译器去哪里找源文件、去哪里找头文件”这件事定下来,后面在 Keil5 里填的 Include Paths 只是把这个约定翻译给编译器。
材料里的做法很朴素:先新建一个工程文件夹,下面建 user 和 library 两个文件夹;user 下再建 inc 和 src,inc 放头文件,src 放源文件;library 整个复制进工程文件夹。这个顺序看起来多了一步,但它把“用户代码”和“库代码”分开了。用户代码会频繁改,库代码基本不动;分开后,Include Paths 只需要指向 user/inc 和 library 里的头文件目录,不会把 src 也加进搜索路径,避免同名头文件互相覆盖。
我一般还会在工程根目录留一个空的 library 目录,先把官方库整目录复制进去,再开始建工程。不要只挑几个 .c 复制,库文件之间有相对引用,拆散之后头文件找不到,编译报错会绕很大一圈。目录名也不要用中文或空格,Keil5 对路径里的空格有时能处理,有时会在链接阶段给你一个莫名其妙的报错,这种玄学问题排查起来很浪费时间。
2.2 user/library 与 inc/src 的落位规则
把四个目录的职责先定死,后面加文件就不容易乱。user 是用户文件的根,user/inc 只放 .h,user/src 只放 .c;library 放官方库文件和库自带的头文件。这样做的直接好处是:新建 .c/.h 时不用思考放哪,编译配置也只有一套固定写法。
| 目录 | 放什么 | 是否加入 Include Paths | 是否加入工程源文件组 |
|---|---|---|---|
| user/inc | 用户头文件 .h | 是 | 否 |
| user/src | 用户源文件 .c | 否 | 是 |
| library | 库文件及库头文件 | 库内头文件目录加入 | 库的 .c 加入 |
| 工程根目录 | 工程文件、说明文件 | 一般不加 | 否 |
这张表里最容易做错的是“是否加入工程源文件组”。user/inc 下的 .h 不需要出现在工程源文件组里,它由 #include 找到;user/src 下的 .c 必须加入工程,否则编译器根本不会编译它。library 里的 .c 也一样,复制进文件夹只是第一步,后面还要在 Keil5 的工程窗口里加到对应文件组。很多人以为“文件在工程文件夹里就等于在工程里”,链接时看到未定义符号才回头找原因,这是新建工程阶段最高频的翻车点之一。
还有一个细节:不要把 .c 和 .h 混在同一个目录。混放之后,Include Paths 一旦把 src 也加进去,编译器可能把某个 .c 当普通文本读,或者出现头文件重复包含。分开之后,路径配置有明确边界,换芯片、换库都只需要动一处。
2.3 一个可照抄的目录树与检查点
建目录不需要在文件管理器里一层层点,用一条命令把骨架拉出来,后面复制库文件也方便。下面这条命令在工程根目录执行,MyProject 换成自己的工程名:
bash复制# 在工程根目录下建立目录骨架
mkdir -p MyProject/user/inc
mkdir -p MyProject/user/src
mkdir -p MyProject/library
-p 的作用是递归创建,父目录不存在时一并建出来,重复执行也不会报错。执行完检查三点:user 下确实有 inc 和 src 两个子目录;library 与 user 平级,不要塞进 user 里面;工程根目录和 user、library 在同一层。确认之后,把官方库整个文件夹复制到 library 下,不要只复制几个 .c 文件。
这里有一个前置条件:复制库之前先确认库的版本和芯片系列对得上。STM32F103 有高容量、中容量、低容量之分,库里的启动文件也按容量分。目录骨架本身不区分容量,但后面选启动文件时必须回到这里核对芯片实际容量,不能凭感觉选。目录建错还能改,启动文件选错,编译可能过,运行却进不了 main,排查成本高得多。
3. 在 Keil5 里落芯片与启动文件:STM32F103、CMSIS 与 hd/md/ld 容量选择
3.1 新建工程与芯片选型
打开 Keil5 后先做一件事:关闭所有已经打开的工程。Keil5 会记住上次的工程配置,如果直接 New Project,有时候窗口标题还是旧工程,改 Define 改到旧工程里,编译结果当然对不上。材料里明确要求“关闭所有打开的工程”,这不是洁癖,是避免配置串台。
新建工程的顺序是:File→New Project,选择目标文件夹(选到工程根目录,不要选 user 或 src),输入工程名,然后在器件库里选 STM32F103。芯片选型不是走形式,它决定后面启动文件、寄存器定义、调试算法和 Flash 下载范围。选错型号,常见现象是编译提示设备不匹配,或者下载时找不到对应的 Flash 算法。选型时看清楚型号后缀,不要只看到 STM32F103 就点确定,容量和引脚数不同,启动文件也不同。
工程建好后,Keil5 会问要不要复制启动文件,这一步可以先跳过,后面按 CMSIS 的方式统一放。材料里的做法是在工程里新建 cmsis 文件组,把系统文件、启动文件、用户文件和驱动文件分类放进去。这个“文件组”只是工程窗口里的逻辑分类,不对应磁盘目录,但分类清楚后,后面找文件、加文件会快很多。
3.2 CMSIS 里到底放哪几类文件
CMSIS 是 Cortex-M 内核和芯片外设之间的一层软件接口。启动文件负责复位后初始化堆栈、设置中断向量表、调用系统初始化,最后跳到 main;内核文件提供内核寄存器的定义;系统文件负责时钟等系统级初始化。材料里把 CMSIS 相关文件分成系统文件、启动文件、用户文件和驱动文件,并在 cmsis 中添加内核文件、系统文件,同时提醒注意芯片容量:hd 高容量、md 中容量、ld 低容量。
| 文件类别 | 作用 | 放置位置 | 选择依据 |
|---|---|---|---|
| 启动文件 | 复位入口、中断向量表、跳 main | cmsis 文件组 | 按芯片容量选 hd/md/ld |
| 内核文件 | 内核外设寄存器定义 | cmsis 文件组 | 与 Cortex-M 内核对应 |
| 系统文件 | 系统时钟等初始化 | cmsis 文件组 | 与芯片系列对应 |
| 用户文件 | 业务代码 | user/src | 自己新建 |
| 驱动文件 | 外设驱动 | library 或 user/src | 按使用的外设选 |
容量后缀是这一节最容易出错的地方。hd 是高容量,md 是中容量,ld 是低容量,选哪个不看开发板丝印,看芯片实际容量。选小了,中断向量表和 Flash 范围对不上,编译可能能过,下载后不进 main 或者中断乱跳;选大了,链接器可能把代码放到实际不存在的区域,运行时直接跑飞。材料没有给具体容量数值,我的习惯是查芯片型号对应的数据手册,确认容量后再回来看启动文件后缀,不凭记忆选。
启动文件加入工程后,还要确认它出现在 cmsis 文件组里,而不是只躺在磁盘上。只复制文件不加工程,链接时会报启动符号未定义,现象和“没选启动文件”一样。加完之后编译一次,看有没有重复定义的中断处理函数,有的话说明启动文件和用户代码里各定义了一份,删掉用户代码里那份。
3.3 Define 与头文件路径怎么填
材料里的 Step 7 有两个关键动作:在 Define 中写入系统启动文件的名字,并且大写;在路径中写头文件地址,包括内核文件地址和运行支持文件地址。这两个动作都在 Options for Target 的 C/C++ 选项卡里完成。
Define 是预编译宏,编译器在编译每个 .c 之前会先把这些宏定义好。启动文件的名字大写写进去,是为了让库文件和用户代码走同一套配置。这里的大小写不是风格问题,宏名区分大小写,写错一个字母,编译时就报某个宏未定义,或者启动文件里的条件编译走到另一条分支。材料特意强调“大写”,照做即可,不要自作主张改成小写。
Include Paths 是编译器找 #include 的搜索路径。材料要求写内核文件地址和运行支持文件地址,意思是除了 user/inc 和库头文件目录,还要把内核文件所在目录、运行支持文件所在目录加进去。路径少了,典型现象是编译第一行就报找不到头文件;路径多了,一般不会报错,但可能让同名头文件发生覆盖。我的做法是每加一条路径就重新编译一次,确认报错行数在减少,而不是一次加十几条再猜哪条有用。
| 配置项 | 填什么 | 常见错误 |
|---|---|---|
| Define | 启动文件名,大写 | 大小写写错、多了空格 |
| Include Paths | 内核文件目录、运行支持文件目录、user/inc、库头文件目录 | 只加 user/inc,漏内核和运行支持 |
| 芯片型号 | STM32F103 对应型号 | 只选系列,没看容量后缀 |
路径填完后不要急着写业务代码,先 Build 一次。0 Error 只说明语法和链接过了,Warning 也要看:隐式声明、未使用变量、类型不匹配,这些在新建工程阶段出现,往往意味着头文件路径或宏配置还有问题。等业务代码堆上来再回头查,定位成本会高很多。
4. Keil5 工程里的源文件与头文件成对管理:.c 放 src、.h 放 inc 的命名与加入方式
4.1 .c/.h 的放置与命名约束
材料 Step 8 说得很清楚:新建 .c 和 .h 文件,.c 放 src,.h 放 inc;.h 文件开头和结尾要有特定格式,并且举例说 LED 是 .c 文件名,但 .h 这里名字必须大写。这句话拆开看是两件事:一是 .c 和 .h 要成对,二是头文件的保护宏要大写。
成对的意思是,一个 LED.c 配一个 LED.h,.c 里 #include "LED.h",.h 里放对外声明。不要出现 LED.c 配 gpio.h 这种交叉命名,后面文件一多,找声明要翻半天。保护宏用 #ifndef/#define/#endif 三件套,宏名与文件名对应并大写,防止同一个头文件被重复包含。
c复制/* LED.h:与 LED.c 成对,保护宏统一大写 */
#ifndef LED_H
#define LED_H
/* 声明写在这里 */
#endif
c复制/* LED.c:放在 user/src 下 */
#include "LED.h"
/* 实现写在这里 */
#ifndef LED_H 判断宏是否已经定义,没有定义就往下走;#define LED_H 立刻定义它;#endif 收尾。第二次包含同一个头文件时,LED_H 已经存在,整个文件内容被跳过。宏名大写是为了和变量名区分,也是材料里强调的写法。这里不需要在头文件里写函数实现,声明和实现分开,改实现时不会牵动所有包含它的源文件。
文件名和宏名要对应。LED.c 对应 LED.h,保护宏写 LED_H;如果文件名是 motor.c,保护宏就写 MOTOR_H。不要图省事所有头文件都用 __HEADER_H__,那样两个头文件互相包含时,第二个会被第一个的宏挡掉,编译报找不到声明,现象很隐蔽。
4.2 双击 user 把 .c 加进工程
文件放进 user/src 不等于加入工程。材料 Step 9 的动作是“双击 user 文件夹,加入 .c 文件到程序中”。在 Keil5 的 Project 窗口里,user 是一个文件组,双击它或者右键选择添加已有文件,定位到 user/src,选中 .c 文件,确认后文件会出现在 user 组下面。只有出现在工程文件组里的 .c 才会参与编译。
操作顺序可以固定成四步:
- 在 Project 窗口找到 user 文件组。
- 双击 user,或右键选择 Add Existing Files to Group。
- 定位到 user/src,选中要加入的 .c 文件。
- 确认文件出现在 user 组下,而不是只出现在磁盘目录里。
如果忘记这一步,典型现象是链接报未定义符号,但你去 user/src 看,文件明明存在,内容也没问题。原因就是编译器根本没编译它。这时候不要怀疑函数写错,先看 Project 窗口里有没有这个文件。另一个现象是编译通过了,但运行行为还是旧的,说明加进去的是另一个同名文件,或者旧文件没移除。加文件时看清楚路径,别从桌面选了一个同名副本。
4.3 编译前的自检清单
新建工程阶段的自检不需要很复杂,按下面这张表过一遍,能挡掉大部分低级错误。
| 检查项 | 正确状态 | 错误后果 |
|---|---|---|
| 芯片型号 | 与开发板一致 | 下载算法不对、外设寄存器错 |
| 启动文件容量 | hd/md/ld 与实际容量一致 | 不进 main、中断异常 |
| Define | 启动文件名大写 | 宏未定义、条件编译走错分支 |
| Include Paths | 含内核、运行支持、user/inc、库头文件 | 找不到头文件 |
| user/src 下的 .c | 都在 user 文件组里 | 链接报未定义符号 |
| .h 保护宏 | 大写且与文件名对应 | 重复包含、声明丢失 |
过完表再按 F7 编译。0 Error 之后不要马上下载,先看 Warning。新建工程阶段常见的 Warning 是“隐式声明函数”,通常意味着头文件没包含或者路径不对;还有“未使用变量”,可能是宏配置导致某段代码没编进去。把这些清掉再写业务代码,后面调试会轻松很多。
5. 编译下载前的避坑排查:路径、宏、调试器设置里最容易翻车的五处
5.1 Define 里启动文件名大小写不对
现象:编译报某个宏未定义,或者链接时提示启动文件相关符号重复定义。原因:材料要求 Define 中写系统启动文件的名字并且大写,实际填的时候写成了小写,或者多了空格、少了后缀对应的字符。宏名区分大小写,启动文件里的条件编译只认大写形式。解决:回到 Options for Target 的 C/C++ 选项卡,把 Define 清空重填,按实际启动文件名去掉扩展名后全大写,不要带空格,改完重新全量编译。
5.2 Include Paths 漏了内核文件和运行支持文件目录
现象:编译第一行就报找不到头文件,错误指向 #include 那一行。原因:材料明确要求路径中写头文件地址,包括内核文件地址和运行支持文件地址。只加了 user/inc,编译器能找到用户头文件,但找不到内核和运行支持的头文件。解决:逐条补路径,每加一条编译一次,确认报错在减少。路径不要带中文和空格,也不要用跳很多级的相对路径,换机器容易断。
5.3 容量后缀 hd/md/ld 选错
现象:编译能过,下载后不进 main,或者中断响应异常。原因:启动文件按容量分 hd 高容量、md 中容量、ld 低容量,选错后中断向量表和 Flash 范围与实际芯片不匹配。这种错误不会在编译阶段报出来,属于典型的“编译通过但运行翻车”。解决:核对芯片实际容量,换对应后缀的启动文件,删除旧启动文件,重新全量编译后再下载。
5.4 .c 只复制进 src,没加入工程 user 组
现象:链接报未定义符号,但 user/src 下文件确实存在。原因:Keil5 只编译工程文件组里列出的 .c,磁盘上有文件不代表在工程里。材料 Step 9 的动作是双击 user 加入 .c,漏掉这一步就会出现这种“文件明明在”的假象。解决:在 Project 窗口双击 user 组,把 src 下的 .c 加进去,确认文件出现在组下;如果之前加过同名文件,先移除旧的再加新的。
5.5 ST-Link 用 SW 下载但 Debug 里没设 SW
现象:点击下载报连接失败,或者找不到目标芯片。原因:材料 Step 10 提醒,用 ST-Link 的 SW 方式下载,要在 Debug 的 settings 里把端口设置成 SW。默认可能是 JTAG,引脚定义不同,连不上目标。解决:Options for Target→Debug,选中 ST-Link,点 Settings,把 Port 改成 SW,确认能读到芯片 ID 后再下载。下载前先编译,不要拿旧固件去烧。
5.6 没关旧工程,配置改到旧工程里
现象:改完 Define 和路径,编译报错还是旧的,或者窗口标题不是当前工程名。原因:Keil5 会保留上次打开的工程,直接 New Project 时容易在旧工程上操作。材料 Step 4 要求打开 Keil5 后关闭所有打开的工程。解决:先 Project→Close Project,再新建或打开目标工程,确认窗口标题是当前工程名,再改配置。这个坑不常见,但一旦踩中,会浪费很多时间在“为什么改了没生效”上。
6. 从能编译到能复用:把新建工程这套动作固化成模板
新建一次工程不算本事,下次换芯片、换项目还能在十分钟内搭出一个能编译、能下载的骨架,才说明这套流程真的走顺了。我的做法是把这次建好的目录结构、CMSIS 文件、Define、Include Paths 一起留成一个模板工程:user/inc、user/src、library 保持空目录,启动文件按 hd/md/ld 各留一份,Define 和路径按最常用的配置填好。下次新建时,复制整个模板文件夹,改名,先 Close Project 再打开,避免配置串到旧工程。
模板化之后,验证方法要固定成三步,不要凭感觉判断“应该没问题”:
| 验证步骤 | 做法 | 通过标准 |
|---|---|---|
| 编译验证 | 不改任何代码,直接 Build | 0 Error,Warning 逐条确认 |
| 下载验证 | ST-Link 选 SW,Debug 里确认端口 | 能读到芯片 ID,下载完成 |
| 运行验证 | 下载一个最小程序,比如点灯 | 程序进 main,现象符合预期 |
这三步里,下载验证最容易被跳过。很多人编译过了就直接写业务,等到要烧录时才发现 Debug 端口是 JTAG,又回头改设置。把 ST-Link 的 SW 设置放在模板里,下一次复制出来就是对的,省掉一次翻车。
还有一个习惯:每次新建工程后,先在 main 里写一个空循环,编译下载,确认能进 main,再往里加业务代码。不要一上来就把外设驱动全加进去,出了问题分不清是工程配置还是驱动逻辑。新建工程阶段的目标不是“功能跑起来”,而是“骨架可信”。骨架可信之后,加什么文件、改什么参数,心里都有底。
从那以后我每次新建 STM32 工程,都先把 user、library、inc、src 四个目录摆好,再开 Keil5;Define 和 Include Paths 填完先编译一次,ST-Link 的 SW 模式先确认能读到芯片,然后才写第一行业务代码。希望帮到你。
