手把手教你用Keil新建一个STM32工程：从零开始不踩坑

你是不是也曾经打开Keil uVision，点了“新建工程”后一脸懵？弹出来的芯片列表密密麻麻，不知道选哪个；添加文件时又怕加错；编译一下全是红字报错……别急，这几乎是每个嵌入式新手都会经历的阶段。

今天我们就抛开术语堆砌和AI腔调，像朋友聊天一样，一步一步带你用Keil MDK从零搭建一个能跑起来的STM32工程。不需要你懂多深的理论，只要跟着做，就能点亮第一颗LED。

一、为什么是Keil？它到底是个啥？

在讲“怎么建工程”之前，先搞清楚我们手里的工具是干什么的。

你可以把Keil uVision想象成写C语言程序的“超级记事本+翻译官+调试台”三合一软件：

• 它让你编辑代码（就像VS Code）
• 把C代码“翻译”成单片机看得懂的机器码（编译链接）
• 还能通过ST-Link之类的下载器，把程序烧进芯片里
• 更厉害的是，还能单步执行、看变量值、查寄存器状态

尤其是对STM32这类基于ARM Cortex-M内核的单片机，Keil几乎是入门标配。虽然现在也有STM32CubeIDE、VSCode+PlatformIO等选择，但很多公司老项目还是用Keil，所以掌握它是有必要的。

✅ 小贴士：建议使用 Keil MDK 5.x 版本（支持AC6编译器），并安装对应芯片的Pack包（比如STM32F1系列的支持包）。不会装？搜“Keil Pack Installer STM32”就行。

二、第一步：创建工程前的心理准备

别急着点“New Project”，先想清楚三个问题：

1. 我要用哪款单片机？
   - 常见的是STM32F103C8T6（蓝 pill开发板）、STM32F407ZGT6等等
   - 芯片型号决定了Flash大小、RAM容量、外设资源

2. 工程放在哪里？
   - 千万别放桌面或者带中文/空格的路径！比如：
   ❌C:\Users\张三\Desktop\我的新工程
   ✅D:\Projects\STM32_Blink_LED

否则可能出现莫名其妙的编译错误。

3. 要不要用库函数？
   - 初学者推荐用HAL库或标准外设库（StdPeriph Library）
   - 后面我们会手动添加.c和.h文件进去

想好了就开工！

三、真正开始：Keil新建工程八步走

第一步：启动Keil → 新建工程

打开Keil uVision，菜单栏点击：

Project → New μVision Project

弹出对话框，输入你的工程名，比如Blink_LED，然后保存到刚才说的那个干净路径下。

📌 注意：此时生成的是.uvprojx文件——这是Keil的工程配置文件，不是代码！

第二步：选择目标芯片

接下来会跳出来一个巨大的设备数据库窗口（Device Database）。

在这里你要找你实际使用的MCU型号。比如：

Search 输入：STM32F103C8

找到结果中的：

STMicroelectronics → STM32F103C8

点击确定。

⚠️ 关键来了！Keil马上会问你一句：

“Copy STM32F10x startup code to project folder and add file to project?”

意思是：“要不要自动帮你复制启动文件？”

✅ 给我复制！给我加入工程！

一定要点“Yes”，不然后面编译会报错找不到_main。

这个启动文件就是让程序能正常启动的关键——它负责设置堆栈、初始化.data段、清.bss段，最后才跳转到main()函数。

第三步：理解那个神秘的“Target”

你现在看到的工程结构左边有个“Project”面板，里面有一个叫Target 1的东西。

这玩意儿代表一个可构建的目标平台。你可以把它想象成“我们要为哪块板子生成程序”。

右键 Target 1 →Manage Components…

这时候可以重命名它为更有意义的名字，比如MyBoard，也可以添加分组（Group）来管理文件。

第四步：建立清晰的文件分组（强烈建议）

为了让工程整洁好维护，建议创建这几个分组：

操作方法：

1. 右键 Target → Add Group
2. 输入名字，比如Core
3. 重复几次建好上面几个组

这样以后一看就知道每个文件属于哪个模块。

第五步：添加关键源文件

现在开始往分组里加文件。

① 添加 main.c

• 先在电脑上新建一个文本文件，改名为main.c
• 拖进工程目录下（比如和.uvprojx同级）
• 回到Keil，右键User分组 → Add Existing Files…
• 找到main.c加进去

写个最简单的测试程序：

#include "stm32f1xx_hal.h" void SystemClock_Config(void); int main(void) { HAL_Init(); SystemClock_Config(); __HAL_RCC_GPIOC_CLK_ENABLE(); // 使能GPIOC时钟 GPIO_InitTypeDef gpio; gpio.Pin = GPIO_PIN_13; gpio.Mode = GPIO_MODE_OUTPUT_PP; // 推挽输出 gpio.Pull = GPIO_NOPULL; gpio.Speed = GPIO_SPEED_FREQ_LOW; HAL_GPIO_Init(GPIOC, &gpio); while (1) { HAL_GPIO_WritePin(GPIOC, GPIO_PIN_13, GPIO_PIN_RESET); // 点亮PC13（低电平点亮） HAL_Delay(500); HAL_GPIO_WritePin(GPIOC, GPIO_PIN_13, GPIO_PIN_SET); // 熄灭 HAL_Delay(500); } }

暂时不用管SystemClock_Config()怎么实现，后面可以用CubeMX生成，或者先空着让它默认运行。

② 添加HAL库文件（简化版做法）

如果你不想导入整个HAL库，至少要确保以下文件在工程中：

• system_stm32f1xx.c
• stm32f1xx_hal.c
• stm32f1xx_hal_gpio.c
• stm32f1xx_hal_rcc.c

这些.c文件都要加入Drivers分组，并参与编译。

第六步：配置编译选项（最重要的一步）

按快捷键Alt + F7或右键 Target → Options for Target。

进入设置页面，这里有五个关键标签页需要关注：

🔹 Output 标签页

• 勾选Create HEX File
  → 生成.hex文件，方便烧录器直接编程
• Name of Executable: 可改为blink_led

🔹 C/C++ 标签页

这是最容易出错的地方！

• Define: 添加两个宏定义
  DEBUG,STM32F103xB
• DEBUG用于条件编译调试信息

• STM32F103xB告诉编译器具体芯片类型（注意后缀xB对应64KB Flash版本）

• Include Paths: 添加所有头文件搜索路径，例如：
  .\Inc .\Drivers\STM32F1xx_HAL_Driver\Inc .\Middlewares\Third_Party\FreeRTOS\Source\include
  每行一个路径，Keil会逐个查找头文件

🔹 Assembler 标签页

• 确保汇编器能找到启动文件路径（一般自动处理了）

🔹 Linker 标签页

• 使用默认分散加载脚本即可（scatter loading）
• 如果提示内存不足，检查是否选错了芯片型号（Flash/RAM不够）

🔹 Debug 标签页

• 选择你的调试器，比如：
• ST-Link Debugger
• J-Link/J-Trace Cortex
• 点击 Settings → Connect 下能看到芯片ID才算成功

第七步：编译试试看！

点击顶部工具栏的Rebuild按钮（锤子+向下箭头图标）

如果一切顺利，底部Build Output会出现：

"blink_led.axf" - 0 Error(s), 0 Warning(s).

🎉 成功了！说明代码语法没问题，也能链接生成可执行文件。

如果报错，常见原因如下：

第八步：下载程序到板子

确保：

• 板子供电正常（USB or 外部电源）
• ST-Link连接正确（SWCLK、SWDIO、GND、VCC）
• 板子复位电路正常（NRST引脚悬空容易接触不良）

点击Load按钮（向下的绿色圆箭头），程序就会被烧录进Flash。

烧完后可以选择：

• Run：立即运行
• Stop at main()：停在main函数开头，便于调试

四、那些没人告诉你却总踩的坑

💣 坑1：启动文件选错了

STM32F103有不同Flash容量：

• 小容量：startup_stm32f103xb.s （64KB）
• 中容量：startup_stm32f103xc.s （128KB）
• 大容量：startup_stm32f103xd.s （256KB以上）

如果你用了C8T6（64KB Flash），就必须用xb结尾的启动文件。否则可能启动失败或中断响应异常。

💣 坑2：忘记开启对应GPIO时钟

HAL库操作GPIO前必须先使能时钟：

__HAL_RCC_GPIOC_CLK_ENABLE();

否则写再多HAL_GPIO_WritePin都没反应——因为硬件模块没通电！

💣 坑3：优化等级太高导致调试困难

默认优化可能是-O1或更高，会导致：

• 单步调试时“跳来跳去”
• 局部变量看不到值
• while(1)循环被优化掉

👉 初学者建议在 C/C++ → Optimization 设置为-O0（无优化）

五、进阶建议：让工程更专业

当你能稳定跑通一个工程后，可以尝试以下提升效率的做法：

✅ 做一个通用模板工程

完成一次标准配置后：

1. 关闭Keil
2. 复制整个工程文件夹，改名为Template_STM32F103
3. 删除中间生成的.axf,.hex,Listings,Objects等临时文件
4. 下次新建项目直接复制这个模板，改改main就行

省去每次重新配路径、宏定义的时间。

✅ 使用STM32CubeMX生成初始化代码

虽然我们现在手动配置，但工业级开发通常用STM32CubeMX工具图形化配置时钟、引脚、外设，然后导出为Keil工程。

既能避免配置错误，又能自动生成SystemClock_Config()函数。

写在最后：每一步都有它的意义

很多人学Keil只记步骤：“点这里→选那里→勾这个”，但从不明白“为什么要这么做”。结果一旦换块芯片或换个库，立马抓瞎。

而今天我们不只是教你“怎么做”，更要你知道：

• 为什么需要启动文件？
• 为什么要有包含路径？
• 宏定义怎么影响编译过程？
• HEX文件和AXF文件有什么区别？

当你理解了这些底层逻辑，你就不再是“照着教程点鼠标”的人，而是真正掌握了嵌入式开发的主动权。

🔧动手练习建议：

现在就去做一件事：

1. 按本文步骤新建一个工程
2. 实现PC13 LED闪烁
3. 改成PB0控制另一个LED（记得开RCC时钟！）
4. 加一个按键检测（PA0），按下时加快闪烁频率

只要你完成了这四步，恭喜你，已经跨过了嵌入式开发的第一道门槛。

如果你在过程中遇到任何问题，欢迎留言讨论。我们一起把“难懂”的Keil变成得心应手的工具。