【底层架构-06】Linux 下 STM32 编译环境搭建（GCC+OpenOCD+VSCode，附完整避坑指南）

前言

很多嵌入式开发者习惯 Windows 下 Keil MDK 开发 STM32，但在 Linux 系统下，借助开源的ARM GCC 交叉编译工具链+OpenOCD 调试烧录工具，同样能搭建高效、免费的 STM32 开发环境，还能适配服务器开发、自动化编译等场景。

本篇教程基于 Ubuntu/Debian 系列 Linux 发行版，从零开始搭建 STM32 编译、烧录、调试一体化环境，全程命令行 + VSCode 配置，步骤详细、命令可直接复制，新手也能轻松上手，告别 Keil 付费限制！

适用系统：Ubuntu 18.04/20.04/22.04/24.04、Debian 系列适用芯片：STM32F1/F4/F7/L4/G4/H7 等全系列核心工具：arm-none-eabi-gcc（交叉编译）、OpenOCD（烧录调试）、make（构建）、STM32CubeMX（代码生成）、VSCode（代码编辑）

一、环境搭建前准备

1.1 更新系统软件源

首先打开终端，更新系统软件包列表，避免安装工具时出现依赖问题：

sudo apt update
sudo apt upgrade -y

1.2 安装基础依赖工具

安装编译、下载所需的基础工具包：

二、安装 ARM GCC 交叉编译工具链

STM32 是 ARM Cortex-M 内核，需要专用的arm-none-eabi-gcc交叉编译器，将 C 代码编译成 STM32 可执行的二进制固件。

2.1 一键安装工具链

Ubuntu/Debian 官方源直接提供该工具，执行以下命令即可安装：

sudo apt install -y gcc-arm-none-eabi binutils-arm-none-eabi gdb-multiarch

2.2 验证安装是否成功

安装完成后，查看编译器版本，验证安装：

arm-none-eabi-gcc -v

若输出版本信息（如 10.3/12.2/13.2 版本），说明安装成功！

三、安装烧录调试工具 OpenOCD

OpenOCD 是开源的片上调试工具，支持 ST-Link、DAPLink 等调试器，实现 STM32 固件烧录、在线调试功能。

3.1 安装 OpenOCD

终端执行命令安装：

sudo apt install -y openocd

3.2 验证 OpenOCD 安装

openocd -v

输出版本号即安装成功。

3.3 配置调试器 USB 权限（关键！）

Linux 下普通用户默认无法访问 USB 调试器，必须配置 udev 规则，否则会出现无法找到设备、烧录权限不足问题。

sudo nano /etc/udev/rules.d/99-stm32-debugger.rules

# ST-Link V2
SUBSYSTEM=="usb", ATTRS{idVendor}=="0483", ATTRS{idProduct}=="3748", MODE="0666", GROUP="plugdev"
# ST-Link V2-1
SUBSYSTEM=="usb", ATTRS{idVendor}=="0483", ATTRS{idProduct}=="374b", MODE="0666", GROUP="plugdev"
# ST-Link V3
SUBSYSTEM=="usb", ATTRS{idVendor}=="0483", ATTRS{idProduct}=="374f", MODE="0666", GROUP="plugdev"
# DAPLink
SUBSYSTEM=="usb", ATTRS{idVendor}=="c251", ATTRS{idProduct}=="f001", MODE="0666", GROUP="plugdev"
SUBSYSTEM=="usb", ATTRS{idVendor}=="0d28", ATTRS{idProduct}=="0204", MODE="0666", GROUP="plugdev"

sudo udevadm control –reload-rules
sudo udevadm trigger

sudo usermod -aG plugdev,dialout $USER

四、安装 STM32CubeMX（代码生成工具）

借助 STM32CubeMX 可快速生成 STM32 初始化代码，直接导出 Makefile 工程，适配 Linux 编译环境。

chmod +x SetupSTM32CubeMX-*.linux

./SetupSTM32CubeMX-*.linux

五、STM32 工程创建、编译与烧录（实战演示）

5.1 用 STM32CubeMX 生成 Makefile 工程

5.2 Linux 下编译 STM32 工程

cd 你的工程路径

5.3 OpenOCD 命令行烧录固件

编译完成后，通过 OpenOCD 将固件烧录到 STM32 开发板：

# STM32F1系列示例
openocd -f interface/stlink.cfg -f target/stm32f1x.cfg -c "program build/你的工程名.elf verify reset exit"

常用芯片系列配置替换：

• STM32F4：target/stm32f4x.cfg
• STM32L4：target/stm32l4x.cfg
• STM32H7：target/stm32h7x.cfg

烧录成功后，开发板会自动复位，程序开始运行！

六、VSCode 集成开发配置（可选，提升效率）

如果需要可视化代码编辑、调试，可配置 VSCode 配合环境使用：

"includePath": [
"${workspaceFolder}/**",
"${workspaceFolder}/Drivers/STM32F1xx_HAL_Driver/Inc",
"${workspaceFolder}/Drivers/CMSIS/Device/ST/STM32F1xx/Include",
"${workspaceFolder}/Drivers/CMSIS/Include"
]

七、常见问题排查（高分必备避坑）

问题 1：arm-none-eabi-gcc: command not found

解决方法：重新安装工具链，或配置环境变量

export PATH=$PATH:/usr/bin/arm-none-eabi-gcc

问题 2：OpenOCD 无法找到 ST-Link

问题 3：make 编译报错

问题 4：烧录提示权限被拒绝

重新配置 udev 规则，重启电脑，确认用户加入 plugdev 组

八、总结

至此，Linux 下 STM32 完整的编译、烧录、调试环境就搭建完成了！全程开源免费，无需依赖 Keil，命令行操作简洁高效，也能配合 VSCode 实现可视化开发，完美适配嵌入式 Linux 开发、自动化编译等场景。

附录：常用命令汇总

# 编译工程
make
# 清理编译文件
make clean
# STM32F1烧录命令
openocd -f interface/stlink.cfg -f target/stm32f1x.cfg -c "program xxx.elf verify reset exit"
# 查看编译器版本
arm-none-eabi-gcc -v

下篇预告： 【底层架构-07】ESP-IDF 版本怎么选？最全版本选择、兼容性与避坑指南

原创不易，如果本文对你有帮助，欢迎点赞、收藏、关注三连！有任何问题都可以在评论区留言，我会及时回复。