STM32 命令行工具链手册：编译烧录调试自动化指南

这篇文章整理了 STM32F103C8T6 项目的命令行编译、烧录、调试工具链。有了命令行工具链，AI 可以自主完成"编译→读报错→修复→重试"的闭环，也是实现 Harness Engineering 的基础设施。

---

快速开始

如果你已经搭建好环境，以下是最小验证路径：

# 1. 编译
unify_builder.exe -p build/STM32F103C8/builder.params

# 2. 烧录（需连接 J-Link）
JLink.exe -device STM32F103C8 -if SWD -speed 4000 -autoconnect 1 -CommandFile build/STM32F103C8/commands.jlink

# 3. 查看串口输出
python tools/serial_monitor.py COM8 115200

详细配置和参数说明见下文。

前置条件

条件	说明
硬件	STM32F103 开发板 + J-Link 调试器（SWD 接口）
软件	VS Code + EIDE 扩展（会自动安装编译工具链）
操作系统	Windows（工具链依赖 Windows 路径格式）
Python	Python 3.x（串口监视器依赖 pyserial）

---

一、工具链概述

1.1 组成

组件	工具	来源	功能
编译器	ARM Compiler 5.06 (armcc)	EIDE 扩展	编译 C 代码
构建工具	unify_builder.exe	EIDE 扩展	项目构建系统
烧录工具	JLink.exe	EIDE 工具包	J-Link 命令行烧录
调试服务器	JLinkGDBServerCL.exe	EIDE 工具包	GDB 调试服务
调试客户端	arm-none-eabi-gdb.exe	EIDE 工具包	GDB 调试器

1.2 工具路径

EIDE 扩展目录（用环境变量表示）：
%USERPROFILE%\.vscode\extensions\cl.eide-<版本号>\res\tools\win32\unify_builder\

Bash 环境：
$USERPROFILE/.vscode/extensions/cl.eide-*/res/tools/win32/unify_builder/

EIDE 工具包目录：
~/.eide/tools/
├── gcc_arm/bin/           # ARM GCC 工具链
├── jlink/                 # J-Link 工具
│   ├── JLink.exe
│   └── JLinkGDBServerCL.exe
└── openocd/               # OpenOCD (备选)

1.3 项目配置文件

文件	位置	说明
builder.params	build/STM32F103C8/	编译参数配置
commands.jlink	build/STM32F103C8/	J-Link 烧录命令
eide.yml	.eide/	项目配置

---

二、编译系统

2.1 命令格式

unify_builder.exe -p <builder.params路径> [选项]

2.2 常用选项

选项	说明
-p <path>	指定 builder.params 文件路径
--rebuild	强制重新编译所有文件
--dry-run	模拟运行，不实际编译

2.3 完整命令示例

# Windows CMD / PowerShell
"C:\Users\<用户名>\.vscode\extensions\cl.eide-<版本>\res\tools\win32\unify_builder\unify_builder.exe" -p "D:\EIDE-Project\build\STM32F103C8\builder.params"

# Git Bash (推荐使用脚本)
./.claude/skills/eide-stm32-dev/scripts/build-flash.sh

2.4 编译输出解读

Program Size: Code=3000 RO-data=336 RW-data=52 ZI-data=1836

Total RO  Size (Code + RO Data)    3336 (   3.26kB)  ← 只读段
Total RW  Size (RW Data + ZI Data) 1888 (   1.84kB)  ← RAM 使用
Total ROM Size (Code + RO + RW)    3388 (   3.31kB)  ← Flash 使用

RAM: [##                  ] 9.2%      1.8KB/20.0KB
ROM: [#                   ] 5.2%      3.3KB/64.0KB

字段	含义
Code	代码段大小
RO-data	只读数据（常量、字符串）
RW-data	已初始化全局变量
ZI-data	未初始化全局变量（BSS 段）

2.5 常见编译错误

错误类型	示例	解决方法
语法错误	Error: #65: expected a ";"	检查行末分号
未定义标识符	Error: #20: identifier "XXX" is undefined	检查头文件包含或宏定义
类型不匹配	Warning: #188-D: enumerated type mixed	添加显式类型转换

---

三、烧录系统

3.1 J-Link 命令格式

JLink.exe -device STM32F103C8 -if SWD -speed 4000 -autoconnect 1 -CommandFile <命令文件>

3.2 参数说明

参数	值	说明
-device	STM32F103C8	目标芯片型号
-if	SWD	调试接口
-speed	4000	通信速度 (kHz)
-autoconnect	1	自动连接
-CommandFile	xxx.jlink	命令脚本文件

3.3 命令文件格式

r              # 复位目标
halt           # 停止 CPU
loadfile xxx.hex  # 加载 HEX 文件
r              # 复位
go             # 运行
exit           # 退出

3.4 烧录输出解读

J-Link>loadfile "D:\EIDE-Project\build\STM32F103C8\EIDE-Project.hex"
Downloading file...
J-Link: Flash download: Bank 0 @ 0x08000000: 1 range affected (1024 bytes)
J-Link: Flash download: Total: 0.506s
O.K.

信息	含义
Bank 0 @ 0x08000000	Flash 起始地址
1 range affected	影响的地址范围数
1024 bytes	烧录数据大小
O.K.	烧录成功

---

四、调试系统

4.1 架构

┌─────────────────┐     TCP/IP      ┌─────────────────┐     SWD      ┌─────────────┐
│  GDB Client     │ ◄─────────────► │  J-Link GDB     │ ◄──────────► │  STM32F103  │
│  arm-none-eabi  │     :3333       │  Server         │              │  目标板     │
│  -gdb           │                 │                 │              │             │
└─────────────────┘                 └─────────────────┘              └─────────────┘

4.2 启动 GDB Server

JLinkGDBServerCL.exe -if SWD -device STM32F103C8 -speed 4000 -port 3333

4.3 GDB 常用命令

命令	缩写	说明
target remote localhost:3333	-	连接 GDB Server
monitor reset	-	复位目标
monitor halt	-	停止目标
load	-	加载程序
break main	b main	在 main 设置断点
break file.c:123	b file.c:123	在指定行设置断点
continue	c	继续运行
step	s	单步进入
next	n	单步跳过
finish	-	运行到函数返回
info registers	i r	查看寄存器
info breakpoints	i b	查看断点
backtrace	bt	查看调用栈
print var	p var	打印变量值
x/10x 0x20000000	-	查看内存
quit	q	退出

4.4 GDB 调试脚本示例

target remote localhost:3333
monitor reset
monitor halt
file build/STM32F103C8/EIDE-Project.axf
load
break main
continue
info registers
backtrace

---

五、辅助工具

5.1 串口监视器

串口监视器用于实时查看 MCU 的调试输出。这里使用的是自定义 Python 脚本（基于 pyserial），支持自动重连和日志保存。

# 列出可用串口
python tools/serial_monitor.py

# 连接串口
python tools/serial_monitor.py COM8 115200

# 连接并自动复位（-r 参数会在连接后发送复位命令）
python tools/serial_monitor.py COM8 115200 -r

依赖安装：

pip install pyserial

用途：AI 可以通过串口监视器读取 MCU 的调试打印，验证程序运行状态，定位运行时问题。

5.2 清理脚本

# 清理编译中间文件
./.claude/skills/eide-stm32-dev/scripts/clean.sh

---

六、为什么用命令行

VS Code EIDE 扩展提供了图形界面（Ctrl+F9 编译、F7 烧录），为什么还要折腾命令行？

场景	图形界面	命令行
AI 自主迭代	无法调用	AI 可直接执行脚本
CI/CD 集成	不支持	天然支持
批量操作	手动逐个	脚本循环
远程开发	依赖 IDE	SSH 即可

核心价值：命令行是 AI 与工具链之间的接口。没有命令行接口，AI 就无法自主完成编译→修复→验证的闭环。

---

七、快速参考

7.1 命令速查表

功能	命令
编译	unify_builder.exe -p builder.params
重新编译	unify_builder.exe -p builder.params --rebuild
烧录	JLink.exe -device STM32F103C8 -if SWD -CommandFile xxx.jlink
启动调试服务	JLinkGDBServerCL.exe -if SWD -device STM32F103C8 -port 3333
GDB 连接	target remote localhost:3333

7.2 端口速查

端口	用途
3333	GDB 连接端口
3334	SWO 输出端口
3335	Telnet 端口

7.3 常见问题

问题	解决方法
builder.params 不存在	在 VS Code 中按 Ctrl+F9 编译一次
J-Link 连接失败	检查 SWD 接线、目标板供电
编译错误定位	查看输出中的 文件名:行号: Error

---

八、环境兼容性

8.1 路径格式

环境	路径格式	说明
Windows CMD	D:\path\to\file	反斜杠
Git Bash	/d/path/to/file	Unix 风格
J-Link	D:\path\to\file	只认 Windows 格式

8.2 路径转换（Bash）

# Unix 路径转 Windows 路径
# /d/path/to/file → D:\path\to\file
WIN_PATH=$(echo "$UNIX_PATH" | sed 's|^/\([a-z]\)/|\U\1:/|' | sed 's|/|\\|g')

8.3 脚本类型选择

环境	推荐脚本类型
Windows CMD	.bat / .ps1
Git Bash	.sh
跨平台	Python

---

文档版本：2026-05-04

---

相关文章

• [[00-Inbox/博客_从WS2812驱动到消消乐游戏-嵌入式开发实战复盘]] — 完整开发故事和问题排查过程
• [[00-Inbox/博客_AI驱动嵌入式开发-Harness-Engineering实践指南]] — 给 AI 配工具的方法论总结