# STM32CubeMX 项目

> For the complete documentation index, see [llms.txt](https://www.jetbrains.com/zh-cn/help/clion/llms.txt).

> **TL;DR**
> 操作系统 ：Windows、Linux、macOS
>
>
>
> 所需工具 ：STM32CubeMX、STM32CubeCLT
>
>
>
> 项目格式 ：CMake

CLion 与 [STM32CubeMX](https://www.st.com/en/development-tools/stm32cubemx.html) 集成，用于目标为 [STM32](https://www.st.com/en/microcontrollers-microprocessors/stm32-32-bit-arm-cortex-mcus.html) 开发板的嵌入式项目。 在 IDE 中使用这些项目之前，您需要安装 STM32CubeMX 和 [STM32CubeCLT](https://www.st.com/en/development-tools/stm32cubeclt.html)。 然后，您可以打开现有的 STM32CubeMX 项目或创建一个新项目。

CLion 还支持 Cube CLI，这是 ST 提供的捆绑包管理器。 它让您只下载所需的工具，例如 CMake、ST-LINK GDB 服务器或 GNU 工具，并在 IDE 中管理开发捆绑包（详情请参阅下面的章节）。 要使用 Cube CLI，请确保您的计算机上安装了  `cube` 。

> **Note:**
> 目前不支持 [STM32Mxx Arm Cortex MPU](https://www.st.com/en/microcontrollers-microprocessors/stm32-arm-cortex-mpus.html)。 如果需要这些开发板与 CLion 搭配使用，欢迎在 [CPP-42553](https://youtrack.jetbrains.com/issue/CPP-42553/Rework-STM32CubeMX-support) 中与我们分享您的用例。

## 使用 STM32CubeMX 项目

Procedure: 打开项目

* 启动 CLion 时，点击   打开   在   欢迎   屏幕上。

![项目对话框](https://resources.jetbrains.com/help/img/idea/2026.3/cl_stm32_open_project.png)

然后，导航到您的项目文件夹，选择它，并点击  打开 。 CLion 将以 CMake 项目的形式打开您的项目。

* 您还可以在项目文件夹中选择  `.ioc`  文件，然后点击   作为项目打开  。 确保  `.ioc`  文件的名称不包含空格、非拉丁字符或其他特殊字符。

* 如果 CLion 已在运行，请导航到  `文件`   `| 打开`  并打开项目文件夹或  `.ioc`  文件。

Procedure: 创建新项目

> **Note:**
> 首先，确保您的系统上已安装 [STM32CubeCLT](https://www.st.com/en/development-tools/stm32cubeclt.html) 和 [STM32CubeMX](https://www.st.com/en/development-tools/stm32cubemx.html)。

1. 在 CLion 中，导航到  `文件 | 新建 | 项目`  并选择   STM32CubeMX   作为您的项目类型：

![新建 stm32 项目](https://resources.jetbrains.com/help/img/idea/2026.3/cl_stm32_new_project.png)

然后，您可以按照   新项目   屏幕上显示的步骤或以下更详细的说明进行操作。

> **Tip:**
> 在步骤 2–10 中，我们将仅使用 STM32CubeMX 的设置来与 CLion 一起工作。 有关 STM32CubeMX 功能的更多信息，请参阅 [官方文档](https://wiki.stmicroelectronics.cn/stm32mcu/wiki/Introduction_to_STM32CubeMX)。

2. 启动 STM32CubeMX。 在打开的窗口中，点击  访问 MCU 选择器 。 您还可以选择  访问开发板选择器 。

![cubemx 访问 mcu 选择器](https://resources.jetbrains.com/help/img/idea/2026.3/cl_stm32_access_mcu_board.png)

3. 在列表中找到您的 MCU 或开发板，然后点击右上角的  启动项目 ：

![cubemx 启动项目](https://resources.jetbrains.com/help/img/idea/2026.3/cl_stm32_start_project.png)

4. 引脚与配置  选项卡将打开。 从那里，您可以更改  引脚视图  中显示的默认设置，配置其他参数，或在必要时安装中间件。

![cubemx 引脚视图](https://resources.jetbrains.com/help/img/idea/2026.3/cl_stm32_pinout_configuration.png)

5. 点击  项目管理器  选项卡。

6. 从  工具链 / IDE  下拉菜单中，选择  CMake ：

![cubemx cmake 工具链](https://resources.jetbrains.com/help/img/idea/2026.3/cl_stm32_toolchain_cmake.png)

7. 在  项目名称  字段中，输入您的项目名称：

![cubemx 项目名称](https://resources.jetbrains.com/help/img/idea/2026.3/cl_stm32_project_name.png)

8. 在右上角，点击  生成代码 。

9. 生成完成后，关闭  代码生成  窗口：

![cubemx 代码生成](https://resources.jetbrains.com/help/img/idea/2026.3/cl_stm32_code_generation.png)

10. 从  工具链文件夹位置  字段中复制路径，使用键盘快捷键：macOS 上为  `^C` ，Windows/Linux 上为  `Ctrl + C` ：

![cubemx 工具链位置](https://resources.jetbrains.com/help/img/idea/2026.3/cl_stm32_toolchain_location.png)

11. 切换回   CLion 新建项目   窗口。 在此对话框顶部的   位置   字段中输入您复制的路径，然后点击   继续  ：

![项目位置](https://resources.jetbrains.com/help/img/idea/2026.3/cl_stm32_proceed.png)

12. 您的 STM32CubeMX 项目将被创建：

![新项目已创建](https://resources.jetbrains.com/help/img/idea/2026.3/cl_stm32_project_created.png)

> **Note:**
> 创建新的 STM32CubeMX 项目后，CLion 会自动配置合适的 [CMake 配置文件](cmake-profile.html) 和 [调试配置文件](debug-profiles.html)。 您可以立即使用这些默认配置来构建、运行或调试项目。

Procedure: 构建项目

要构建项目，请点击主工具栏上的 ![](https://resources.jetbrains.com/help/img/idea/2026.3/app-client.expui.build.build.svg) 按钮：

![构建项目](https://resources.jetbrains.com/help/img/idea/2026.3/cl_stm32_build.png)

如果一切正常，您将在   消息   窗口中看到  `Build finished` ：

![构建完成](https://resources.jetbrains.com/help/img/idea/2026.3/cl_stm32_build_finished.png)

Procedure: 调试项目

1. 请确保已配置适当的运行/调试配置和 ST-LINK 调试服务器。 如果这是一个新的 STM32CubeMX 项目，可以使用 CLion 预配置的默认设置。

2. 在源代码中设置断点，然后点击主工具栏上的 ![](https://resources.jetbrains.com/help/img/idea/2026.3/app-client.expui.run.debug.svg) 按钮：

![调试项目](https://resources.jetbrains.com/help/img/idea/2026.3/cl_stm32_start_debugging.png)

如果一切正常，将在调试器的  `控制台`  选项卡中看到消息：  `Debugger connected to ST-LINK` 。

3. 程序暂停后，可以执行各种操作，例如：

* 查看 [寄存器和外设](peripheral-view.html)，其定义于 `.svd` 文件中。 对于 STM32 MCU，这些文件位于 `STM32CubeCLT` 安装目录内的 `STMicroelectronics_CMSIS_SVD` 目录中。

* 使用 [实时监视](live-watches.html) 实时监控全局变量。

* 调试 [反汇编代码](disassembly-view.html)。

* 查看正在运行的进程的 [原始内存](memory-view.html)。

![调试](https://resources.jetbrains.com/help/img/idea/2026.3/cl_stm32_debug.png)

Procedure: 编辑源代码

* 在编辑由 STM32CubeMX 生成的文件时，请始终将您的代码包含在  `/* USER CODE BEGIN ... */`  和  `/* USER CODE END ... */`  伪注释中。 以下是一个示例：

```C
               /* Infinite loop */
/* USER CODE BEGIN WHILE */
while (1)
{
  HAL_GPIO_TogglePin(LD3_GPIO_Port, LD3_Pin);
  HAL_Delay(1000);
  /* USER CODE END WHILE */
          
```

这将保护您的代码在 STM32CubeMX 重新生成代码时不被覆盖。

* 如果您添加源文件或头文件，请将它们放在  `Src`  和  `头文件`  目录中。 此外，将代码片段提取到单独的  `.c`  或  `.h`  文件中。

## 使用 Cube CLI 管理捆绑包

Cube CLI 将开发工具作为  捆绑包  分发：CMake、编译器、ST-LINK GDB 服务器、GNU 工具和其他组件。 在 Cube 项目中，捆绑包及其版本会锁定在项目文件中，以便构建该项目的每个环境都使用同一套工具。

> **Note:**
> Cube CLI 可与 System、MinGW、WSL 和 Remote SSH 工具链配合使用。 使用 Docker 工具链时，只能使用镜像中已安装的捆绑包。

Procedure: 配置 Cube CLI

1. 安装  `cube` ，如 [ST 文档](https://dev.st.com/stm32cube-docs/stm32cubedocs-landing-page/en/index.html) 中所述。

2. CLion 会自动检测  `cube`  可执行文件。 要检查检测到的路径或为当前默认工具链手动设置路径，请打开  `设置 | 构建、执行、部署 | 嵌入式开发 | STM32`  并使用   Cube CLI 命令   字段。

![检查 CLion 是否在设置中检测到 cube 可执行文件](https://resources.jetbrains.com/help/img/idea/2026.3/cl_stm32_cube_cli_command.png)

3. Cube CLI 使用项目中锁定的捆绑包扩展 CMake 配置文件的环境。 此功能默认启用。 要关闭此功能，请清除   使用 STM32 Cube CLI 扩展 CMake 的环境   复选框，该复选框位于   STM32 微控制器   下的 [高级设置](advanced-settings.html#advanced-stm32) 中。

Procedure: 将项目转换为 Cube 项目

当项目尚不是 Cube 项目时，  `工具 | STM32 Cube CLI`  包含两个操作：   转换为 STM32 Cube 项目   和   打开 STM32 Cube CLI 终端  。 对于终端操作，请参阅 [运行 Cube CLI 命令](#cube-cli-commands)。

1. 转到  `工具 | STM32 Cube CLI | 转换为 STM32 Cube 项目` 。

![工具菜单，其中 STM32 Cube CLI 子菜单已打开，并显示打开 STM32 Cube CLI 终端和转换为 STM32 Cube 项目操作。](https://resources.jetbrains.com/help/img/idea/2026.3/bundles-lock.store.json`  中。

> **Tip:**
> 当项目具有包含这两个文件的  `.settings`  目录时，会被识别为 Cube 项目。 仅在其中列出某个捆绑包并不会让项目使用它：该工具还需要在项目本身中被引用。

### 安装项目捆绑包

在 Cube 项目中，  `工具 | STM32 Cube CLI`  中还会提供另外两个操作：

安装项目捆绑包
: 安装由 Cube CLI 锁定但您的计算机上缺失的捆绑包。

将项目捆绑包安装到所有环境
: 在项目使用的每台计算机上安装缺失的捆绑包。 当 CMake 配置文件以不同机器为目标时，例如本地工具链和远程工具链，会显示此操作。

缺失的捆绑包不一定会导致 CMake 重新加载中断：Cube CLI 会查找等效工具并改用它。 在这种情况下，CMake 重新加载终端会显示一个警告，其中包含用于安装所需捆绑包的快速修复。

> **Note:**
> 集成始终需要 CMake 捆绑包，即使项目未锁定它也是如此。 没有此捆绑包，CMake 重新加载会失败，并且 CMake 重新加载终端中的错误会包含一个用于全局安装 CMake 捆绑包的快速修复。

### 运行 Cube CLI 命令

要管理现有项目的捆绑包，请使用 Cube CLI 命令。 转到  `工具 | STM32 Cube CLI | 打开 STM32 Cube CLI 终端`  以打开一个终端，其中  `cube`  可用于所选 CMake 配置文件的环境。 也可以从   终端   工具窗口中的标签页下拉菜单打开它。

cube bundle 在线列出
: 列出可供下载的捆绑包及其版本。

cube bundle 显示
: `cube bundle show <bundle>`  显示捆绑包的详细信息：它设置的环境变量、它在  `PATH`  变量中的条目，以及它提供的命令。

cube bundle 初始化
: `cube bundle init --project <bundles>`  会将当前项目转换为 Cube 项目，并在其中锁定指定的捆绑包。

cube bundle 安装
: `cube bundle install --project <bundles>`  会安装指定的捆绑包并将其锁定在项目中。 省略  `--project`  可全局安装捆绑包。

cube bundle 移除
: `cube bundle remove --project <bundles>`  会从项目中锁定的工具中移除指定的捆绑包。 省略  `--project`  可全局卸载捆绑包。

在这些命令中，  `<bundles>`  使用  `bundle_name@version`  格式。 例如，  `gnu-tools-for-stm32@14.3.1+st.2` 。

## See also

### JetBrains 博客文章

[Working With STM32 Arm TrustZone-Based Projects in CLion](https://blog.jetbrains.com/clion/2026/03/working-with-stm32-arm-trustzone-in-clion/) [CLion for embedded development](https://blog.jetbrains.com/clion/2016/06/clion-for-embedded-development/) [CLion for embedded development, part II](https://blog.jetbrains.com/clion/2017/12/clion-for-embedded-development-part-ii/) [CLion for embedded development, part III](https://blog.jetbrains.com/clion/2019/02/clion-2019-1-eap-clion-for-embedded-development-part-iii/)

### 外部链接

[Embedded Development in CLion FAQs](https://intellij-support.jetbrains.com/hc/en-us/articles/4405160320274-Embedded-Development-in-CLion) [PEmicro tools in CLion setup guide](https://www.pemicro.com/blog/index.cfm?post_id=245)

