ESP32：ESP-IDF环境搭建troubleshooting

原创已于 2023-10-12 14:39:56 修改 · 928 阅读

CC 4.0 BY-SA版权

文章标签：

于 2023-08-26 20:50:06 首次发布

从2023年4月开始捣鼓ESP-IDF，中间踩过无数环境搭建中的坑。不得不吐槽乐鑫的环境真的对初学者非常不友好，经常一堆很迷的bug官方手册中也找不到。以下纯属个人记录，只是提供一种方法不一定适用于所有人。**首先先推荐一个其他博主些的帖子，据说按照他的方法搭建ESP32+VSCode开发环境能一遍成功，我看了一下确实很强（码龄十几年的大佬写的，膜拜~），如果实在解决不了搭建中的问题先按照他的方法试一下，很可能会成功。**帖子在这ESP32+VSCode开发环境搭建(全网最强最终解决方案)。

1.ESP-IDF+VSCode环境搭建troubleshooting

1.1 UnicodeDecodeError: ‘gbk’ codec can’t decode bytes in position 1-2: illegal multibyte sequence．

这里有一个用PlatformIO环境开发报错的例子https://blog.csdn.net/lsq179/article/details/121488813，
博主的解决方法是找到esp-idf.py,修改idf的python源文件中读取API函数的参数，把读取文件编码方式从默认的gbk修改为utf-8。ESP-IDF估计也存在类似的问题。然而我找了半天没找到esp-idf.py（或许是idf.py，但是不知道改哪里。。。）。一般而言，gbk解码失败大概率是中文字符造成的，后来又想到软件开发中避坑的一大忠告：文件路径中不能有中文! 遂把源文件移动到没有中文的路径中，问题解决。

1.2 CMake Error: The source… does not match the soused to generate cache. Re-run cmake…

本问题是因为复制别人已经编译过的工程所致。参考这个帖子：https://blog.csdn.net/bingfeiqiji/article/details/86554365 ，直接把CMakeCache.txt所在的build文件夹里的内容全删了，重新编译即可。CMakeList.txt的问题可以无视。

1.3 ninja：error：failed recompaction：No such file or directory

在这里插入图片描述
重新编译一遍即可，原因未知。

1.4 VSCode中安装ESP-IDF插件时报错：ModuleNotFoundError: No module named ‘virtualenv’

在这里插入图片描述
参考乐鑫论坛帖子：https://www.esp32.com/viewtopic.php?t=12481

按照以上几步安装virtualenv包，手动创建虚拟python3环境，目前卡在第3步（找不到需要删除的文件夹），论坛中也有人提到这个问题，先搁着以后再研究。
【更新 · 已解决virtualenv模块报错问题，同时也是先安装ESP-IDF再安装ESP-IDF插件的方法】
请注意，以下路径均是我个人安装路径，实际操作要替换成你自己的路径。
我的ESP-IDF之前通过下文注解中的方案2已经装在了目录F:\mysoft\Espressif-IDE\Espressif之下，进入看看文件夹里有什么?
在这里插入图片描述
注意到python_env文件夹。安装插件的过程中会在python_env文件夹中通过F:\mysoft\Espressif-IDE\Espressif\tools\idf-python\3.11.2\Lib\site-packages下的virtualenv模块在python_env中创建一个Python虚拟环境。现在的问题是ESP-IDF插件无法找到这个virtualenv，肯定是路径出了问题。

全部退出重新打开VSCode，选中ESP-IDF插件的标志（没有插件先搜索并安装插件），此时在下方OUTPUT里会显示此时使用的Python的路径，发现与实际使用的ESP-IDF路径不同（原因很可能是以前安装过ESP-IDF和ESP-IDF插件而路径痕迹没有删除干净），导致ESP-IDF插件找不到实际使用的Python环境，自然找不到F:\mysoft\Espressif-IDE\Espressif\tools\idf-python\3.11.2\Lib\site-packages下的virtualenv模块。下图OUTPUT中没有Python路径的提示，是因为我已经装好了，不报ModuleNotFoundError: No module named 'virtualenv’的错了所以不显示了，没安装配置好插件前OUTPUT会显示相关路径。
在这里插入图片描述
配置ESP-IDF：

选择USE EXISTING SETUP

进去之后的页面右边会有一个蓝色的清除已有设置的按钮（叫Clearxxx? 具体的图当时没截图，应该很好找）,点击后清除以前记录的路径。然后回到ESP-IDF配置页面（还是上图），选择第二个ADVANCED。
在这里插入图片描述在这里选择IDF_PATH和IDF_TOOL_PATH（以你安装实际位置为准），注意IDF_TOOL_PATH只要选到安装ESP-IDF的文件夹即可，而不是选到它下面的tools文件夹。在我的路径中，应该选F:\mysoft\Espressif-IDE\Espressif而不是F:\mysoft\Espressif-IDE\Espressif\tools。然后点击install。
安装一段时间后出现这个页面，选择Use existing ESP-IDF Tools，再继续安装。如果这个页面下的Tools后有的不是√而是×，则应选择Download ESP-IDF Tools更新这些Tools。
在这里插入图片描述
继续安装有可能会出现这这类requirements不符合的情况。直接到对应的requirements.txt把对应的语句给注释掉几即可。
打开F:\mysoft\Espressif-IDE\Espressif\frameworks\esp-idf-v4.4.4\requirements.txt。

把相应的requirement注释掉。比如，找到pyparsing那句加#号注释。
然后继续安装，成功！！
在这里插入图片描述
**【注解：在VSCode中编译esp32程序常见的有3种方案——】
** 方案1.VSCode+ESP-IDF插件： 简单搭建方案参考：https://zhuanlan.zhihu.com/p/630698425 在这个帖子更全：https://blog.csdn.net/felix_tao/article/details/122913575本方案是先安装VSCode，再通过VSCode中的ESP-IDF插件（VSCode中搜索Espressif）安装ESP-IDF。目前就我自己使用来看本方案bug最多，但是在VSCode中显示esp32代码又似乎必须采用ESP-IDF插件，否则出现.h文件名红色波浪线报错的问题，看着十分糟心。在此提醒，ESP-IDF插件装好了就不要轻易删掉，因为你不一定装的回来！！
方案2.VSCode+Windows版ESP-IDF 本方案是先安装VSCode，再到乐鑫科技官网下载ESP-IDF的安装包，直接安装，暂时先不安装VSCode中的ESP-IDF插件。即用VSCode查看代码，同时在Windows命令行中输入idf.py build命令编译程序。这里可以借助VSCode的Terminal功能，将Win桌面下的ESP-IDF命令行快捷方式的路径复制到VSCode Terminal中使用idf的命令。如下所示，找到ESP-IDF CMD，右键属性，将目标（T）：中的内容复制到VSCodeTerminal中回车，即可配置好编译环境。**这样做不失为一个装不上ESP-IDF插件的替代方案。但是没有VSCode中的ESP-IDF插件打开工程后.h文件名和许多函数出现红色波浪线报错的问题。**安装完后可以到VSCode中补装ESP-IDF插件，但是要费点劲。在这里插入图片描述
复制路径到VSCode Terminal：

缺点：仍然存在.h文件名红色波浪线报错问题，可以参考1.5中的方法减少红色波浪线的数量。
方案3.VSCode+Linux版本ESP-IDF，远程登录服务器或虚拟机进行编译
测试了一下Linux版本的IDF还是比较顺畅的，习惯Linux操作的小伙伴可以试一下。
方案4.其他方案
其实ESP-IDF还支持Eclipse，此外esp32系列也可用Arduino或PlatformIO进行开发，可作为补充。

1.5 （基本解决）VSCode+ESP-IDF头文件红色波浪线问题

这是使用esp-idf的老问题，目前我本人没有特别好的解决方案。如果你顺利装上了VSCode和ESP-IDF插件，或者在VSCode命令行中配置好了ESP-IDF环境，那么可以参考这几个帖子：
1.https://blog.csdn.net/Tristan_csg/article/details/126791530#comments_27553379
2.https://blog.csdn.net/qq_43862401/article/details/132237124
3.https://www.cnblogs.com/HEHEtk2442/p/15521114.html
它们基本都在说一件事情：更新.vscode配置文件（把.vscode配置文件下的文件都删了，然后在VSCode中按Ctrl+Shift+P，搜索ESP-IDF，选择ESP-IDF:添加vscode配置文件夹）。更新完后效果不好可以关掉VSCode再重新进入试试，这个时候红色波浪会少很多。然鹅我在能用ESP-IDF插件的时候测试的结果是不能从根本上解决问题，更新完后红波浪线只是变少了但仍然存在，而且原来没有红线的头文件变得有红线了。。。

（未完待续）