# ESP-IDF

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

> **Note:**
> 本文将很快更新。 同时，请参考 [在 CLion 中使用 ESP-IDF](https://developer.espressif.com/blog/clion/)教程，该教程解释了我们当前在 IDE 中处理 ESP-IDF 项目的方法。 该教程提供了有关如何配置项目、构建应用程序、将其烧录到开发板以及调试的详细说明。

[ESP-IDF](https://github.com/espressif/esp-idf) 是 [ESP32 和 ESP32-S 系列 SoC](https://www.espressif.com/en/products/socs) 的官方开发框架。 本文是关于在 CLion 中使用 ESP-IDF 的入门指南。

某些步骤重复了 [ESP-IDF 入门](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/index.html#step-2-get-esp-idf)指南。 以下示例针对 macOS 的情况，Windows 特定的说明已相应标注。

Procedure: 准备环境

1. 请确保您的系统上安装了最新版本的 [Python](https://www.python.org/downloads/)、 [pip](https://packaging.python.org/tutorials/installing-packages/) 和 [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)。

2. 使用系统终端，为 ESP-IDF 创建一个目录并克隆官方 [存储库](https://github.com/espressif/esp-idf)：

```CONSOLE
mkdir -p ~/esp
cd ~/esp
git clone --recursive https://github.com/espressif/esp-idf.git

```

ESP-IDF 将下载到  `~/esp/esp-idf` 。

3. 在同一个 shell 中，安装工具：

```CONSOLE
cd esp-idf
./install.sh

```

4. 在 Windows 上，请确保正确识别了 ESP-32 开发板的 USB 桥接器。 您可以在   设备管理器  中检查。

> **Tip:**
> 观看 [在 Windows 上使用 CLion 开发 ESP32：准备工作](https://www.youtube.com/watch?v=M6fa7tzZdLw&t=21s)的视频说明。

Procedure: 使用 CLion 的终端设置一个示例项目

1. 在 CLion 中，转到主菜单中的  `文件 | 打开` 并选择  `~/esp/esp-idf` 目录。

此时，项目加载可能会因  当前目录 '../esp/esp-idf' 无法构建... 错误而失败。

2. 打开 CLion 的内置终端（  `视图｜工具窗口｜终端`  或 `Alt+F12` (Windows), `⌥ F12` (macOS), `⌥ F12` (IntelliJ IDEA Classic (macOS)), `⌘ ⌃ T` (macOS System Shortcuts), `Alt+F12` (XWin), `Alt+F12` (GNOME), `Alt+F12` (KDE), `Alt+F12` (Emacs), `Alt+F12` (Sublime Text), `⌥ F12` (Sublime Text (macOS)), `⌥ F12` (Xcode), `Ctrl+Alt+1` (Visual Studio), `⌘ ⌃ 1` (Visual Studio (macOS)), `Ctrl+Alt+1` (ReSharper), `⌘ ⌃ 1` (ReSharper (macOS)), `Alt+F12` (QtCreator), `⌥ F12` (QtCreator (macOS)), `Alt+F12` (NetBeans), `Alt+F12` (Eclipse), `⌥ F12` (Eclipse (macOS))）。

3. 通过运行  `. $HOME/esp/esp-idf/export.sh` 设置环境变量：

![设置 ESP-IDF 环境的结果](https://resources.jetbrains.com/help/img/idea/2026.3/cl_espidf_environment.png)

4. 让我们从   hello_world  目录配置  `examples/get-started` 项目。 以下命令将 ESP32 芯片设置为目标，并运行  menuconfig 配置工具：

```CONSOLE
cd $IDF_PATH/examples/get-started/hello_world
idf.py set-target esp32
idf.py menuconfig

```

最后一条命令打开配置菜单。 由于我们使用的   hello_world  项目将以默认配置运行，您无需在此菜单中进行设置。

![配置菜单](https://resources.jetbrains.com/help/img/idea/2026.3/cl_espidf_configmenu.png)

退出菜单并检查配置是否完成。

5. 现在我们可以通过运行  `idf.py build` 来构建   hello_world  。

![构建结果](https://resources.jetbrains.com/help/img/idea/2026.3/cl_espidf_buildresult.png)

接下来，您可以在 CLion 中使用终端继续处理项目。 这将不需要额外的 CMake 配置。 或者，您可以设置 CMake，以便项目可以在没有命令行的情况下加载、构建和运行（见下文）。

## 在 CLion 中配置 ESP CMake 项目

Procedure: 打开 Hello-world 项目

1. 在主菜单中，转到  `文件 | 打开` 并选择  `esp/esp-idf/examples/get-started/hello_world` 文件夹。

2. 点击   作为项目打开  并 [信任源代码](project-security.html)。

此时，项目加载可能会失败。

> **Tip:**
> 如果您在 Windows 上工作，请转到  `设置 | 构建、执行、部署 | 工具链` 并为您的项目设置工具链。 如需了解更多信息，请参阅 [教程：在 Windows 上配置 CLion](quick-tutorial-on-configuring-clion-on-windows.html)。

### 加载环境

使用工具链设置指定 ESP-IDF 环境脚本。

您将需要 ESP-IDF 安装中的一个或两个环境文件。 对于 Python 虚拟环境的情况，需要两个文件。

Procedure: 加载环境脚本（macOS 示例）

1. 转到  `设置 | 构建、执行、部署 | 工具链` 。

2. 点击   添加环境  旁边的   名称  字段，然后点击   从文件  。

3. 导航到  `esp/esp-idf` 并选择  `export.sh` ：

![设置工具链环境脚本](https://resources.jetbrains.com/help/img/idea/2026.3/cl_espidf_toolchain_envscript.png)

4. 保存工具链设置。

5. 项目将自动重新加载。 如果出现错误，请从主菜单调用  `工具 | CMake | 重置缓存并重新加载项目` 。

Procedure: 使用自定义脚本加载环境（Windows 示例）

在 Windows 上，设置 ESP-IDF 环境需要两个文件。 为了自动化，您可以创建一个简单的脚本来同时加载这两个文件，并将其用作工具链环境文件。

1. 在项目文件夹中创建一个脚本文件。 例如，  `espidf_source.bat` 。

2. 自定义以下行并将其添加到您的脚本中：

```BASH
@call C:\Espressif\python_env\idf5.0_py3.8_env\Scripts\activate.bat
@call C:\Espressif\frameworks\esp-idf-v5.0-2\export.bat

```

3. 转到  `设置 | 构建、执行、部署 | 工具链` 。

4. 点击   添加环境  旁边的   名称  字段，然后点击   从文件  。

5. 选择新创建的文件。

6. 保存工具链设置。

7. 项目将自动重新加载。 如果出现错误，请从主菜单调用  `工具 | CMake | 重置缓存并重新加载项目` 。

Procedure: 构建项目

1. CLion 将自动为所有检测到的 CMake 目标创建 [运行/调试配置](run-debug-configuration.html)。

要构建项目，请在配置切换器中选择   app  ，然后点击锤子图标或按  `Ctrl + F9`  运行 [构建](build-actions.html) 来构建此配置。

2. 此时，所有 CLion 的代码洞察功能都可用于您的 ESP 项目。 观看 [在 Windows 上使用 CLion 开发 ESP32：代码洞察](https://www.youtube.com/watch?v=M6fa7tzZdLw&t=399s)以获取一些示例。

Procedure: 在 CLion 中烧录并监控 ESP-32 芯片

> **Tip:**
> 有关视频说明，请观看 [在 Windows 上使用 CLion 开发 ESP32：烧录和监控您的 ESP-32 芯片](https://www.youtube.com/watch?v=M6fa7tzZdLw&t=482s)。

1. 在配置切换器中选择   烧录  ，然后点击锤子图标或按  `Ctrl + F9` 进行构建。

在构建输出中，您可以检查芯片烧录的百分比指示器。

2. 选择   监视  配置并构建它。 如果您收到串口无法打开的错误，请执行以下操作：

1.  打开   设备管理器  并检查您的 ESP 设备使用的端口。

2.  在 CMake 设置中的   环境  变量中添加一个变量：  `ESPPORT` 。 将值设置为端口，例如，  `COM3` 。

3.  项目重新加载后，再次构建   监视  配置。 ESP-32 芯片应按预期返回响应。

## 故障排除（Windows）

如果您在 Windows 上收到  `Git executable not found` 错误，请确保 Git 安装在 ESP-IDF 的  `find_package(Git)` 命令可发现的位置。

为了解决此问题，请添加  `GIT` 环境变量，并将其值设置为  `git.exe` 二进制文件的完整路径。 您可以通过修改  `esp/idf/tools/cmake/git_submodules.cmake` 来完成此操作。 在第一行，将  `find_package(Git)` 更改为以下内容：

```CMAKE
if (DEFINED ENV{GIT})
    execute_process(COMMAND $ENV{GIT} --version
    OUTPUT_VARIABLE git_version
    ERROR_QUIET
    OUTPUT_STRIP_TRAILING_WHITESPACE)
    if (git_version MATCHES "^git version [0-9]")
        string(REPLACE "git version " "" GIT_VERSION_STRING "${git_version}")
        set(GIT_FOUND True)
        set(GIT_EXECUTABLE $ENV{GIT})
    endif()
    unset(git_version)
else()
    find_package(Git)
endif ()

```

## See also

### 外部链接

[CLion blog: Developing for ESP32 With CLion on Windows](https://blog.jetbrains.com/clion/2021/09/developing-for-esp32-with-clion-on-windows/) [Video: Developing for ESP32 With CLion on Windows](https://www.youtube.com/watch?v=M6fa7tzZdLw)

