文章目录
- [单片机 VSCode 开发环境搭建](#单片机 VSCode 开发环境搭建)
-
- [1. 工具链介绍](#1. 工具链介绍)
-
- [1.1 工作流程](#1.1 工作流程)
- [2. 工具安装](#2. 工具安装)
-
- [2.1 ARM GCC 编译器](#2.1 ARM GCC 编译器)
- [2.2 Make](#2.2 Make)
- [2.3 OpenOCD](#2.3 OpenOCD)
- [2.4 环境变量](#2.4 环境变量)
- [2.5 VSCode 插件](#2.5 VSCode 插件)
- [3. 项目结构说明](#3. 项目结构说明)
-
- [3.1 关键文件说明](#3.1 关键文件说明)
- [4. 编译和烧录](#4. 编译和烧录)
-
- [4.1 方法一：VSCode 快捷键](#4.1 方法一：VSCode 快捷键)
- [4.2 方法二：终端命令](#4.2 方法二：终端命令)
- [4.3 编译输出](#4.3 编译输出)
- [4.4 烧录成功标志](#4.4 烧录成功标志)
- [5. 添加新项目（Keil 工程移植）](#5. 添加新项目（Keil 工程移植）)
-
- [5.1 步骤](#5.1 步骤)
- [5.2 Makefile 模板](#5.2 Makefile 模板)
- [5.3 Keil 工程文件对应关系](#5.3 Keil 工程文件对应关系)
- [5.4 需要从 Keil 工程提取的信息](#5.4 需要从 Keil 工程提取的信息)
- [6. 常见问题](#6. 常见问题)
-
- [Q: 编译报错 "core_cm3.c: registers may not be the same"](#Q: 编译报错 "core_cm3.c: registers may not be the same")
- [Q: 烧录报错 "Error: open failed"](#Q: 烧录报错 "Error: open failed")
- [Q: 烧录成功但程序不运行](#Q: 烧录成功但程序不运行)
- [Q: 如何查看编译错误？](#Q: 如何查看编译错误？)
- [Q: 如何切换不同的项目？](#Q: 如何切换不同的项目？)
- [附录：openocd.cfg 说明](#附录：openocd.cfg 说明)
单片机 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 Flash2. 工具安装
假设所有工具安装在 C:\tools\ 目录下，也可以手动添加到环境变量。
2.1 ARM GCC 编译器
下载地址：
选择 Windows (mingw-w64-i686) 的 .zip 包，解压到 C:\tools\arm-gcc\。
验证：
bash
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 也解压进去。
验证：
bash
C:\tools\make\bin\make.exe --version
2.3 OpenOCD
下载地址：
选择 xpack-openocd-x.x.x-win32-x64.zip，解压到 C:\tools\openocd\。
验证：
bash
C:\tools\openocd\xpack-openocd-0.12.0-3\bin\openocd.exe --version
2.4 环境变量
每次新开终端需要运行一次环境设置脚本：
PowerShell（VSCode 默认终端）：
powershell
. .\env.ps1 # 注意前面有个点和空格cmd.exe：
cmd
.\env.bat也可以把以下路径永久加入系统 PATH（一劳永逸）：
C:\tools\arm-gcc\bin
C:\tools\make\bin
C:\tools\openocd\xpack-openocd-0.12.0-3\binVSCode 用户注意 ：
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 方法二：终端命令
powershell
# 先设置环境（每次新开终端需要运行一次）
. .\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 步骤
- 把 Keil 工程复制到工作区目录（如
02_LED/） - 告诉 AI 工程路径，AI 会自动：
- 分析工程结构
- 生成项目 Makefile
- 更新 VSCode 配置
- 编译烧录测试
5.2 Makefile 模板
每个项目需要一个自己的 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.mk5.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 未连接或驱动未安装。
解决：
- 检查 ST-Link 是否插好
- 安装 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 行即可。