单片机 VSCode 开发环境搭建

从零开始搭建 STM32F103C8T6 的 VSCode 开发环境。
使用 GCC + Makefile + OpenOCD 完成编译和烧录。

---

1. 工具链介绍

工具	作用	类比 Keil
arm-none-eabi-gcc	ARM 交叉编译器，把 C 代码编译成单片机能执行的机器码	Keil 自带的 ARMCC 编译器
make	构建工具，根据 Makefile 自动编译、链接	Keil 的构建按钮
Makefile	构建脚本，告诉 make 怎么编译项目	Keil 的 .uvprojx 工程文件
OpenOCD	烧录/调试工具，通过 ST-Link 把程序写入单片机	Keil 的下载/调试功能
链接脚本 (.ld)	告诉链接器程序在 Flash/SRAM 中怎么布局	Keil 的 Target 配置
启动文件 (.s)	芯片上电后最先执行的代码，初始化堆栈、中断向量表	Keil 自带的启动文件

1.1 工作流程

源代码 (.c/.h)
    ↓  arm-none-eabi-gcc 编译
目标文件 (.o)
    ↓  arm-none-eabi-gcc 链接 + 链接脚本 (.ld)
可执行文件 (.elf)
    ↓  objcopy 转换
二进制文件 (.bin / .hex)
    ↓  OpenOCD + ST-Link
烧录到 STM32 Flash

---

2. 工具安装

假设所有工具安装在 C:\tools\ 目录下，也可以手动添加到环境变量。

2.1 ARM GCC 编译器

下载地址：

• https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads

选择 Windows (mingw-w64-i686) 的 .zip 包，解压到 C:\tools\arm-gcc\。

验证：

C:\tools\arm-gcc\bin\arm-none-eabi-gcc.exe --version

2.2 Make

下载 GnuWin32 Make：

• make: https://gnuwin32.sourceforge.net/packages/make.htm （Binaries zip）
• 依赖: https://gnuwin32.sourceforge.net/downlinks/make-dep-zip.php

解压 make.zip 到 C:\tools\make\，再把依赖的 dll 也解压进去。

验证：

C:\tools\make\bin\make.exe --version

2.3 OpenOCD

下载地址：

• https://github.com/xpack-dev-tools/openocd-xpack/releases

选择 xpack-openocd-x.x.x-win32-x64.zip，解压到 C:\tools\openocd\。

验证：

C:\tools\openocd\xpack-openocd-0.12.0-3\bin\openocd.exe --version

2.4 环境变量

每次新开终端需要运行一次环境设置脚本：

PowerShell（VSCode 默认终端）：

. .\env.ps1    # 注意前面有个点和空格

cmd.exe：

.\env.bat

也可以把以下路径永久加入系统 PATH（一劳永逸）：

C:\tools\arm-gcc\bin
C:\tools\make\bin
C:\tools\openocd\xpack-openocd-0.12.0-3\bin

VSCode 用户注意：Ctrl+Shift+B 编译不需要手动设置 PATH，
因为 tasks.json 已经配置好了环境变量。只有在终端手动运行 make 时才需要。

2.5 VSCode 插件

必装：

• C/C++ (ms-vscode.cpptools) — 代码补全、跳转
• Cortex-Debug — 调试支持

推荐：

• C/C++ Extension Pack

---

3. 项目结构说明

test/                           ← 工作区根目录
├── .vscode/
│   ├── c_cpp_properties.json   ← IntelliSense 配置（代码补全）
│   ├── launch.json             ← 调试配置
│   └── tasks.json              ← 编译任务配置
├── 01_OLED/                    ← Keil 工程目录（用户代码）
│   ├── User/
│   │   ├── main.c              ← 主程序
│   │   └── stm32f10x_it.c      ← 中断处理
│   ├── Start/
│   │   ├── stm32f10x.h         ← 芯片寄存器定义（CMSIS）
│   │   ├── system_stm32f10x.c  ← 时钟初始化（72MHz）
│   │   └── system_stm32f10x.h
│   ├── Library/                ← STM32 标准外设库
│   │   ├── stm32f10x_gpio.c/h
│   │   ├── stm32f10x_rcc.c/h
│   │   └── ...
│   ├── Hardware/               ← 硬件驱动
│   │   ├── OLED.c/h
│   │   ├── LED.c/h
│   │   └── Key.c/h
│   └── System/                 ← 系统工具
│       └── Delay.c/h
├── common.mk                   ← 通用构建规则（共享）
├── Makefile                    ← 当前项目的构建配置
├── STM32F103C8Tx_FLASH.ld      ← 链接脚本
├── startup/startup_stm32f103c8t6.s  ← GCC 启动文件
├── openocd.cfg                 ← OpenOCD 配置
└── env.bat                     ← 环境变量设置

3.1 关键文件说明

文件	作用
Makefile	定义源文件列表、编译参数、目标名称
common.mk	共享的编译规则，所有项目共用
STM32F103C8Tx_FLASH.ld	链接脚本，定义 Flash/SRAM 布局
startup_stm32f103c8t6.s	GCC 格式的启动文件
openocd.cfg	OpenOCD 烧录配置（ST-Link + SWD）

---

4. 编译和烧录

4.1 方法一：VSCode 快捷键

操作	快捷键	说明
编译	Ctrl+Shift+B	编译当前项目
烧录	Ctrl+Shift+P → Tasks: Run Task → Flash	编译并烧录
调试	F5	启动调试（需 Cortex-Debug 插件）

4.2 方法二：终端命令

# 先设置环境（每次新开终端需要运行一次）
. .\env.ps1          # PowerShell
# 或 .\env.bat       # cmd.exe

# 编译
make

# 烧录（需连接 ST-Link V2）
make flash

# 清理编译产物
make clean

# 查看代码大小
make size

4.3 编译输出

   text    data     bss     dec     hex filename
   3304       0    1536    4840    12e8 build/oled.elf

段	含义
text	代码 + 常量（存 Flash）
data	已初始化全局变量（存 Flash，运行时复制到 SRAM）
bss	未初始化全局变量（运行时清零）

4.4 烧录成功标志

** Programming Finished **    ← 烧录完成
** Verified OK **             ← 校验通过
** Resetting Target **        ← 复位运行

---

5. 添加新项目（Keil 工程移植）

5.1 步骤

1. 把 Keil 工程复制到工作区目录（如 02_LED/）
2. 告诉 AI 工程路径，AI 会自动：
   • 分析工程结构
   • 生成项目 Makefile
   • 更新 VSCode 配置
3. 编译烧录测试

5.2 Makefile 模板

每个项目需要一个自己的 Makefile，格式如下：

# === 项目配置 ===
PROJECT_DIR = 02_LED        ← Keil 工程目录名
TARGET      = led           ← 输出文件名

# === 源文件列表 ===
C_SRCS  = $(PROJECT_DIR)/User/main.c
C_SRCS += $(PROJECT_DIR)/User/stm32f10x_it.c
C_SRCS += $(PROJECT_DIR)/Start/system_stm32f10x.c
C_SRCS += $(PROJECT_DIR)/System/Delay.c
C_SRCS += $(PROJECT_DIR)/Hardware/LED.c
C_SRCS += $(PROJECT_DIR)/Library/stm32f10x_gpio.c
C_SRCS += $(PROJECT_DIR)/Library/stm32f10x_rcc.c
# ... 根据实际用到的库文件添加

# === 包含通用规则 ===
include common.mk

5.3 Keil 工程文件对应关系

Keil 中	GCC 中	说明
.uvprojx	Makefile	工程配置
ARM Compiler	arm-none-eabi-gcc	编译器
.sct	.ld	链接脚本
startup_stm32f10x_md.s	startup_stm32f103c8t6.s	启动文件
Target Options → C Defines	Makefile 的 -D 参数	宏定义
Target Options → Include Paths	Makefile 的 -I 参数	头文件路径

5.4 需要从 Keil 工程提取的信息

• 源文件列表：所有 .c 文件路径
• 头文件路径：Include Paths 中列出的目录
• 宏定义：C Defines 中的内容（如 STM32F10X_MD, USE_STDPERIPH_DRIVER）

---

6. 常见问题

Q: 编译报错 “core_cm3.c: registers may not be the same”

原因：老版本 CMSIS 的 core_cm3.c 和新版 GCC 不兼容。

解决：在 Makefile 中删除 core_cm3.c，不需要它。

Q: 烧录报错 “Error: open failed”

原因：ST-Link 未连接或驱动未安装。

解决：

1. 检查 ST-Link 是否插好
2. 安装 ST-Link 驱动：https://www.st.com/en/development-tools/stsw-link009.html

Q: 烧录成功但程序不运行

原因：可能是时钟配置问题。

解决：确认 system_stm32f10x.c 中的时钟配置和硬件匹配（有无外部晶振）。

Q: 如何查看编译错误？

解决：编译时终端会显示错误信息，格式如下：

文件名:行号: error: 错误描述

VSCode 会自动解析并在"问题"面板显示。

Q: 如何切换不同的项目？

解决：替换 Makefile 内容即可。

---

附录：openocd.cfg 说明

source [find interface/stlink.cfg]   ← 使用 ST-Link 调试器
source [find target/stm32f1x.cfg]    ← 目标芯片 STM32F1 系列
adapter speed 4000                   ← SWD 时钟速度 4MHz
transport select hla_swd             ← 使用 SWD 协议（不是 JTAG）

如使用其他调试器（如 J-Link、DAP-Link），修改 interface 行即可。