在vscode安装esp-idf扩展并实现代码索引（代码补全，代码提示，函数跳转）与cmake自动配置

zz6zz666

已于 2025-02-27 14:16:45 修改

阅读量1.7k

点赞数 31

文章标签： vscode ide 编辑器

于 2025-02-26 13:47:09 首次发布

本文链接：https://blog.youkuaiyun.com/2301_79683529/article/details/145874332

版权

前言

为什么要写这一篇博客呢，就是因为在搭建esp-idf开发环境的时候会遇到各种问题，主要体现在esp-ide自身与idf版本的不兼容（在ide-v3.1.0或ide-v3.2.0中使用idf-v5.4的时候经常出现C++Indexer的初始化失败报错，以及其导致的代码索引、代码补全与跳转等功能失效），而尝试用在vscode上使用esp-idf扩展时来作为替代时，关于强大的代码索引等功能配置的介绍又少之又少的问题。

esp-ide本身的编辑器配色让人看着眼花缭乱很难受（当然有一个叫DevStyle的Eclipse扩展能够改善编辑器效果，然而安装其所需要的依赖有些在esp-ide默认配置源中不能找到导致安装失败，我当时是导入了STM32CubeIDE中的部分源地址才安装成功的，有需要的同学可以通过网盘链接https://pan.seu.edu.cn:443/link/5986FC7A01E9C90A47B7439EA28B2DAB这个链接下载.xml文件并将其导入esp-ide的源地址管理中，然后就可以正常安装DEvStyle插件了。）并且其代码索引功能必须在编译通过后才能正常运作，而导入项目、切换项目时候又会导致代码索引失效，导致你很多时候会得到一片红色的报错。此外，基于eclipse的esp-ide由于依赖java运行环境经常造成资源占用过高以及卡顿，如果能够用vscode完全替代ide，那么使用体验包括软件的流畅性等将会提高很多。

另外，在vscode中配置cmake扩展可以帮助生成compile_commands.json文件，它包含项目中每个源文件的详细编译信息（如源文件路径，编译命令，工作目录，编译参数），是esp-idf代码索引器索引（包括基于Eclipse的esp-ide和vscode扩展）的重要依据。然而当在Cmakelists.txt文件中添加新的头文件、源文件路径之后，代码索引器并不会及时更新，以致在其他代码中引用这些新添加的模块时会因找不到头文件或函数而报错，编程体验不够友好，而没有cmake自动配置工具的时候，往往只能选择重新编译来获得正确的代码索引，使用起来较为麻烦。

所以这篇文章的目的就在于帮助你抛弃esp-ide，仅通过vscode扩展就享受强大的代码跳转、补全功能，并且自动刷新代码索引的配置文件。

一、esp-idf的安装

esp-idf的安装其实很简单，只需要从这个网址dl.espressif.com.cn/dl/esp-idf/index.htmlhttps://dl.espressif.com.cn/dl/esp-idf/index.html下载最新版本的idf离线安装包并在Windows上正常安装即可。（我下载的就是第三个ESP-IDF v5.4 Offline Installer，注意Online Installer虽然看似方便，但在实际联网安装的时候很可能产生各种报错，比如某个组件下载失败等等，因此并不推荐。）

安装完成后，软件会自动在Windows的用户环境变量中添加 IDF_TOOLS_PATH 一项，其值就是idf整套软件的安装路径。

二、ESP-IDF安装与vscode扩展配置

在vscode扩展选项中找到并安装这一个扩展

安装完后会提示配置扩展，只要在配置页面选择ADVANCED选项，

选择 Find ESP-lDF in your system，

并在后面的配置中选择Use existing ESP-IDF Tools就能完成配置。

到此，你的idf安装与vscode扩展配置就已经完成了。

三、clang的配置与llvm的安装

首先在vscode扩展商店找到并安装来自llvm的clang扩展。

然后vscode会提示你需要安装LLVM服务，这时候你只要到LLVM的github下载对应的Windows安装程序并安装即可。Releases · llvm/llvm-projecthttps://github.com/llvm/llvm-project/releases

（图片中我使用了一个叫【Greenhub绿墙—网络出海工具】的Edge扩展，可以在右边选择不同的镜像源以加速下载，这里也一并推荐给大家）

实际上esp推出了自己的IDF clang-tidy组件，你也可以选择不安装官方的LLVM应用，而按照乐鑫文档中提供的IDF clang-tidy安装指南去安装与配置。但由于IDF clang-tidy依然是个不完善的工具，因此我更推荐直接安装LLVM，就像我的文章中介绍的一样。只是后续你会发现此处你安装的LLVM与clangd完全是服务于代码索引的，而实际编译所用的编译器依然是GNU编译器。我尝试过将编译器手动指定为clang，也就是用clang代替GNU作为esp32项目的默认编译器（在Windows系统的用户环境变量中添加项 IDF_TOOLCHAIN，值为 clang），但几次尝试都发发现会导致编译失败（也有可能只能使用esp自己的IDF clang-tidy才能正确编译esp32的项目）。因此我们并不使用clang作为编译器，也无需关心此处安装esp的IDF clang-tidy还是LLVM了。

当LLVM和clangd扩展安装完成过后，clang就已经配置完成了。此时你打开一个esp32项目的文件夹，ESP-IDF扩展自动启动后，你就已经能使用完整的函数跳转、代码补全等代码索引功能了。

四、cmake的安装与配置

ESP-IDF的代码索引功能依赖于项目文件夹下build目录中的compile_commands.json文件，也就意味着如果你删除了build文件夹，代码索引功能也会失效，你可能得到一片红色的报错，而只有重新编译，build文件夹及其中的compile_commands.json文件重新生成后，代码索引功能才会恢复。

实际上，当你导入一个不带build文件夹的项目时候，vscode会弹窗提示你“此项目缺少compile_commands.json文件”，并提供“生成compile_commands.json文件”的按钮。然而这个自动生成功能只有在刚刚打开项目的时候才生效，当你添加一些文件并修改了CmakeLists.txt文件时，他并不会主动更新，除非你重新编译，或者删除build文件夹然后重新在vscode打开项目，利用弹窗重新生成compile_commands.json（当然你也可以在idf终端中敲命令行来实现compile_commands.json的重新生成，这里就不展开了），使用起来并不方便。

cmake的配置相比前面的部分略微复杂一点，主要涉及到idf的一些环境变量，但并不是很难。重要的是，安装好cmake之后，你可以使用按钮来一键自动配置compile_commands.json，这个方法难道不方便吗？

首先在vscode扩展商店安装微软的Cmake Tools插件。

安装完后可能会弹窗提示找不到cmake命令，这时候你可以去cmake官网下载cmake的安装程序进行安装，安装时默认把cmake写入环境变量，之后扩展就能找到cmake命令了。（实际上你也可以偷懒选择esp的tools中的cmake，具体操作是在cmake tools插件的设置中将 Cmake Path 由cmake 改为esp工具链中的cmake.exe地址，例如我的是 C:\Espressif\tools\cmake\3.30.2\bin\cmake.exe 但我依然直接下载安装了官方的cmake，并且也没有去改动这个Cmake Path）

之后要做的最后一步也是最麻烦的一步，也就是编辑这个Configure Environment选项了，他是cmake工作时候临时使用的环境变量，也就是相比系统环境变量多出来专门服务于idf的一部分。

由于idf扩展启动的时候会默认把IDF_PATH还有这些PATH项临时写入到当前终端的临时环境变量中，在编译的时候这些环境变量都能正确找到。而cmake并不在这一终端中工作，也就意味着这些环境变量必须显式地写入在Configure Environment选项中，不然cmake工具并不能找到相应的工具链。

首先添加IDF的位置IDF_PATH，是idf工具所在的位置，在espressif安装目录的frameworks文件夹下。由于我还是用到esp-adf，因此可以看到我还添加了adf的路径（这两个你也可以直接添加到Windows的用户环境变量中，但下面一个Path就最好不要这么做了）。

然后要添加的就是这个PATH了，他包含了idf各种工具链的路径。怎么样获取到这些路径呢？你可以简单地打开Windows的PowerShell终端，或者直接在vscode中新建一个PowerShell终端，在其中输入 echo $Env:PATH 命令就可以获取到当前系统下的PATH环境变量值了。（注意：如果使用的是cmd命令提示符，则命令相应地改为 echo %PATH%）。

然后通过点击下方的终端按钮打开一个新的esp-idf终端，默认打开的也是PowerShell终端，可以看到，它实际上是执行了esp安装目录下的 export.ps1 文件（在cmd下对应使用的是export.bat文件）来更新了当前终端的环境变量值。

此时依然输入 echo $Env:PATH （cmd下改为echo %PATH%）获取到当前终端的PATH环境变量值。将这两个值复制下来，比较idf终端相比普通PowerShell终端的输出中多出的条目，将其作为PATH环境变量添加到cmake扩展配置的Configure Environment选项中，那么你的cmake工具也就配置完成了。

有了cmake的配置，每当你想要刷新代码索引的时候，只需要点击Cmake Tools扩展中的这个配置按钮，cmake tools工具就会自动帮你生成相应的compile_commands.json文件，那么你新添加的代码模块也就能够被正确索引啦！

此外，当cmake tools生成compile_commands.json配置文件时，也会做编译的一部分前期准备工作，当你在点击了这个配置按钮后再去点esp-idf扩展提供的build按钮（扳手）时，你会发现输出中相比没有点按cmake配置按钮会开头的很大一部分输出，直接从编译文件开始。而你点击了idf扩展中的clear按钮（垃圾桶）时候，构建被清除，你再次点击扳手构建时候就依然又是从头开始编译了。这一点应该很有意思吧哈哈。