CubeMX + CLion 从零配置教程

适用平台:macOS 和 Windows 适用对象:已用 STM32CubeMX 生成 CMake 工程,想用 CLion 编译、烧录、调试 STM32F103（Blue Pill）的人 支持调试器:ST-Link / J-Link / DAPLink 工具链:ARM GNU Toolchain（arm-none-eabi-gcc）+ Ninja + OpenOCD + CLion 自带 CMake

本教程从「CubeMX 已经把工程导出成 CMake 之后」讲起。CubeMX 那边记得在 Project Manager → Toolchain/IDE 选 CMake,这样才能用 CLion 打开

本篇教程为了确保逻辑严谨与 Claude opus 4.8 联合编写

目录

1. 整体流程概览
2. 安装电脑端必备工具
   • macOS
   • Windows
   • 验证安装
3. 在 CLion 里配置工程
4. 配置 OpenOCD 烧录与调试
5. 硬件接线与点灯
6. 常见问题排查
7. 附录:上传 GitHub 时提交什么、忽略什么

一、整体流程概览

整条链路是这样的:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

CubeMX 生成 CMake 工程
        │
        ▼
安装工具链 (arm-none-eabi-gcc + ninja + openocd)  ← 电脑环境(如果你觉得安装过了就[验证安装](#23-验证安装)一下, 如果验证通过就可以将这一步忽略)
        │
        ▼
CLion 打开工程
        │
        ├─ 配置「工具链 (Toolchain)」: 指定编译器、构建工具
        ├─ 配置「CMake 配置文件 (Profile)」: 关键是加 -DCMAKE_TOOLCHAIN_FILE
        │
        ▼
编译 (Build) → 生成 .elf 固件
        │
        ▼
配置「OpenOCD 下载并运行」: 选 .elf + 写 .cfg 面板配置文件
        │
        ▼
接好 SWD 线 → 点运行 → 烧录点灯

你需要分别配置 三样东西,初学时最容易混淆它们:

二、安装电脑端必备工具

需要装的东西总览:

2.1 macOS

① 安装 ARM GNU Toolchain

两种方式任选其一:

方式 A(推荐,和本教程路径一致): 去 ARM 官网下载 macOS 版安装包 developer.arm.com → Downloads → GNU Toolchain (arm-none-eabi) 解压后放到 /Applications/,例如: > 注:下面所有命令里的 15.2.rel1 是版本号,换成你实际装的版本

1

/Applications/ArmGNUToolchain/15.2.rel1/arm-none-eabi/bin/

方式 B(更省事): 用 Homebrew(但是你要记住自己的路径….)

1

brew install --cask gcc-arm-embedded

如果用了这个请使用自己的路径, 不要一股脑的照抄我下面的东西

② 配置 PATH

把工具链的 bin 目录加进 PATH,这样命令行和 OpenOCD/GDB 都能找到它。macOS 默认是 zsh,编辑 ~/.zshrc:

1
2

# 打开配置文件(没有就会新建)
open -e ~/.zshrc

在文件末尾加一行(路径换成你自己的):

1

export PATH="/Applications/ArmGNUToolchain/15.2.rel1/arm-none-eabi/bin:$PATH"

保存后让它生效:

1

source ~/.zshrc

③ 安装 Ninja

1

brew install ninja

装好后一般在 /opt/homebrew/bin/ninja(Apple Silicon)或 /usr/local/bin/ninja(Intel)

④ 安装 OpenOCD

CLion 自带 OpenOCD,通常不用单独装。如果遇到版本太旧、认不出 DAPLink/克隆片的问题,再装个新的:

1

brew install open-ocd

⑤ 安装 CLion

去 JetBrains 官网 下载安装。CLion 自带 CMake,不用单独装。

⑥ 调试器驱动

macOS 上 ST-Link、DAPLink 一般免驱(走 HID/libusb)。J-Link 需要去 Segger 官网装 J-Link 软件包

2.2 Windows

① 安装 ARM GNU Toolchain

去 ARM 官网 下载 Windows 版 .exe 安装包,双击安装。默认路径类似:

1

C:\Program Files (x86)\Arm GNU Toolchain arm-none-eabi\15.2 rel1\bin

安装最后一步,务必勾选 “Add path to environment variable”(添加到环境变量)。勾了这一步就省去手动配 PATH。

② 配置 PATH(如果上一步没勾)

此电脑 右键 → 属性 → 高级系统设置 → 环境变量 → 在「系统变量」里找到 Path → 编辑 → 新建,粘进去:

1

C:\Program Files (x86)\Arm GNU Toolchain arm-none-eabi\15.2 rel1\bin

确定后重启所有终端/CLion让其生效。

③ 安装 Ninja

任选一种:

1

winget install Ninja-build.Ninja

或用 scoop:

1

scoop install ninja

④ 安装 OpenOCD

CLion 自带 OpenOCD,通常直接用。需要新版时可以装 xPack OpenOCD 并加进 PATH。

⑤ 安装 CLion

去 JetBrains 官网 下载安装,自带 CMake。

⑥ 调试器驱动(Windows 上比 mac 重要)

2.3 验证安装

打开终端(Windows 用 PowerShell / CMD),逐条运行,能打印出版本号就说明装好了:

1
2
3

arm-none-eabi-gcc --version      # 编译器
ninja --version                  # 构建工具
openocd --version                # 烧录工具(若用 CLion 自带可跳过)

arm-none-eabi-gcc --version 如果提示「找不到命令」,说明 PATH 没配好,回到 ② 检查。

三、在 CLion 里配置工程

方法 1: 直接用CubeMX生成好的预设

使用 CubeMX 生成的代码自己本身就已经有预设了, 我们可以直接用, 只需要把这个启用配置文件勾上就行, 但是你需要选择 Debug - Debug 预设和 Release - Release 预设, 这两个是buildPresets(构建预设), 而前两个是configurePresets(配置预设) - 名字是单个词「Release 预设」的,来自 configurePresets - 名字是「Release - Release 预设」(中间带个横杠、两个词)的,来自 buildPresets——前面那个 Release 是 build preset 名,后面那个 Release 是它绑定的 configure preset 名,CLion 用 构建-配置 的格式把它俩拼成一个名字显示 如果之后你出现了, 这个图片所示的冲突问题, 这是因为CLion 检测到「Debug」这个预设名字重复了——你的 CMakePresets.json 里有一个 Debug 预设,同时 CLion 自己之前还保留着一个也叫 Debug 的 CMake profile(就是你自己手动建的不带「预设」的纯 Debug)。两个同名,CLion 没法导入 presets 里的 Debug,就报了这个错 解决办法是把你之前的自建的 Debug 预设删除, 或者重命名

然后点一下清除缓存重建目录, 这个错误就被解决了

方法 2: 不用 CMakePresets 配置,而是用自己构建的 CLion CMake Profile 配置(适合吃了没事的人)

第 1 步:打开工程

CLion → File → Open,选中 CubeMX 生成的工程根目录(里面有 CMakeLists.txt、CMakePresets.json、.ioc 的那个文件夹)。CLion 会自动识别为 CMake 工程。

第 2 步:配置工具链(Toolchain)

进入 设置 → 构建、执行、部署 → 工具链,点 + 新建一个,命名为 STM32,按下表填:

⚠️ 关于那个黄色警告 “测试 CMake 运行完成,但有错误”:这是正常的,可以无视。 因为 CLion 在测试工具链时会尝试编译一个能在你电脑(mac/win)上运行的小程序,而 ARM 交叉编译器编出来的是给 STM32 跑的,在电脑上当然「跑不起来」,于是报个警告。它不影响编译你的固件

调试器这里用「捆绑的」即可。真正烧录调试用的 GDB 会在第四部分的运行配置里单独指定为 「捆绑的 GDB multiarch」(嵌入式调试要用 GDB,不是 LLDB)

第 3 步:配置 CMake 配置文件(Profile)—— 最关键的一步

进入 设置 → 构建、执行、部署 → CMake,点 + 新建(或编辑已有的),命名为 Debug-STM32:

关键:在「CMake 选项」里加上这一行:

1

-DCMAKE_TOOLCHAIN_FILE=cmake/gcc-arm-none-eabi.cmake

为什么必须加这行? 从 CubeMX 6.15 开始,工具链文件只写在 CMakePresets 里、从 CMakeLists.txt 里移除了。结果 CLion 有时识别不到这个 toolchain 文件,导致用普通方式去链接测试程序,报出经典错误: arm-none-eabi-gcc - broken(编译器测试失败)。 手动加上 -DCMAKE_TOOLCHAIN_FILE=... 就是把工具链文件明确指给 CLion,问题即解

第 4 步:重新加载并编译

1. 改完点 应用 / 确定,CLion 会自动重新跑 CMake。
2. 看底部 CMake 面板出现 Configuring done / Build files have been written to... 就说明配置成功了。
3. 点顶部的 锤子图标(Build) 编译。成功后,cmake-build-debug-stm32/ 目录里会生成 你的工程名.elf(例如 example_F103_LED.elf)—— 这就是要烧进芯片的固件。

💡 你可能会看到一句警告 Manually-specified variables were not used: CMAKE_TOOLCHAIN_FILE。这不是错误,放心忽略。因为 toolchain 文件只在第一次配置时读取并缓存,之后重新配置就不再读它了

四、配置 OpenOCD 烧录与调试

第 1 步:新建「OpenOCD 下载并运行」运行配置

顶部菜单 运行 → 编辑配置 → 点 + → 选 OpenOCD Download & Run(OpenOCD 下载并运行)

第 2 步:填写运行配置

「可执行的二进制文件」选不了,通常是因为还没编译出 .elf。先回第三部分 Build 一次,再回来选。

第 3 步:写「面板配置文件」(.cfg)

在工程根目录新建一个文件,例如 daplink.cfg。并把下面代码框的文件复制进去

它告诉 OpenOCD 两件事:用哪个调试器、芯片是什么。下面这份同时给出了三种调试器的写法,按你手上的设备保留对应行:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

# ============ 选择调试器(三选一,保留你用的那行)============
#   ST-Link :  source [find interface/stlink.cfg]
#   J-Link  :  source [find interface/jlink.cfg]
#   DAPLink :  source [find interface/cmsis-dap.cfg]
source [find interface/cmsis-dap.cfg]

# ============ 选择传输协议(和调试器对应)============
#   ST-Link :  transport select hla_swd
#   J-Link  :  transport select swd
#   DAPLink :  transport select swd
transport select swd

# ============ 目标芯片:STM32F1 系列 ============
source [find target/stm32f1x.cfg]

# ============ 下载速度(kHz)============
# 默认给个稳妥值;不稳就往下调(如 1000)
adapter speed 1000

把这个文件路径填进运行配置的「面板配置文件」框(点 ... 选择)。填好后,底部那个红字 未定义面板配置文件 就会消失。

几个易踩的坑:

• interface/stlink.cfg 是新名字,旧的 interface/stlink-v2.cfg 已废弃。
• adapter speed 别一上来就给很高(比如 10000 = 10MHz)。10MHz 对很多 DAPLink/克隆片不稳。先用 1000(1MHz)跑通,再按需提速

五、硬件接线与点灯

SWD 接线(4 根线)

把调试器(ST-Link/DAPLink/J-Link)和 Blue Pill 按下表对接,Blue Pill 板子一端那排针脚上有丝印标注:

烧录

1. 确认右上角运行配置选的是 「OpenOCD 下载并运行 → 你的工程名」(不是「CMake 应用程序」那个——那个是想在电脑上跑,对嵌入式没用)。
2. 点绿色 三角(运行)。CLion 会:编译 → 通过 OpenOCD 把 .elf 烧进芯片 → 复位运行。
3. 看到 PC13 的灯按你的程序工作即成功

六、常见问题排查

七、附录:上传 GitHub 时提交什么、忽略什么

如果把这个工程作为示例上传 GitHub,建议在根目录的 .gitignore 里加入:

1
2
3
4
5

# 编译产物
/cmake-build-*/

# CLion / JetBrains IDE 配置(示例工程建议忽略,保持与具体 IDE 无关)
/.idea/

应该提交(别人重建工程需要的):Core/、Drivers/、CMakeLists.txt、CMakePresets.json、.ioc 文件、链接脚本(.ld)、启动文件(startup_*.s)、.mxproject、cmake/ 文件夹,以及你这份 openocd.cfg。

.idea/ 是 CLion 的本机配置,对用别的编辑器的人没用,忽略掉更干净。如果你特别希望用 CLion 的人拿到相同运行配置,也可以选择提交它(CLion 在 .idea 里自带的 .gitignore 会自动排除纯本机文件)。

祝点灯顺利 💡