★ FEATURED ARTICLE 老规矩先说一个反直觉的结论ESP-IDF在Ubuntu上的安装最大的坑往往不在ESP-IDF本身而在VS Code插件源的访问上。很多人在官网教程里折腾半天装不好最后发现卡在一个完全想不到的地方。这篇教程我从零开始把整个流程拆成四步手把手带你在Ubuntu上用VS Code把ESP-IDF开发环境跑起来全程有解释有原理保证不让你白等。1. 环境准备先搞清楚你的Ubuntu是什么状态1.1 系统要求与基础依赖说实话ESP-IDF对Ubuntu版本的要求不算苛刻但有几个前置条件你必须满足Ubuntu 20.04及以上版本推荐22.04 LTS或24.04 LTS至少10GB的磁盘空间ESP-IDF工具链解压后体积不小能够访问外网这个很关键尤其是访问GitHubVS Code任意版本推荐用官网最新版不要用snap商店里的旧版很多新手容易忽略的一点确认你的Ubuntu系统是64位。用下面的命令查看uname -m输出x86_64就没错。如果是aarch64也没问题教程里的步骤同样适用因为ESP-IDF官方已经做了很好的架构兼容。1.2 安装必备系统包这一步为什么必须做安装ESP-IDF之前需要先安装一些编译工具和依赖库。官方文档给出了一长串命令这里我简化为最核心的几个sudo apt update sudo apt install -y git wget flex bison gperf python3 python3-pip python3-venv cmake ninja-build ccache libffi-dev libssl-dev dfu-util libusb-1.0-0这里我多说一句为什么必须装这些git从GitHub拉取ESP-IDF源码python3和python3-venvESP-IDF内部大量使用Python脚本而且要求使用虚拟环境避免污染系统Pythoncmake和ninja-build构建系统核心ESP-IDF从4.x版本开始就是基于CMake构建的ccache编译缓存工具二次编译时能省下大量时间libusb-1.0-0串口通信相关烧录固件的时候用得上注意千万别跳过python3-venv。我在实际使用中发现ESP-IDF的安装脚本会强制要求使用虚拟环境没有装venv直接会报错浪费时间。2. 克隆ESP-IDF源码版本选择比你想的重要2.1 为什么我推荐用最新稳定版进入你的工作目录克隆ESP-IDF源码。这里有个选择问题用release/v5.x还是master我强烈推荐release版本原因很简单——稳定。cd ~ mkdir -p esp cd esp git clone --recursive https://github.com/espressif/esp-idf.git cd esp-idf git checkout v5.3.1 git submodule update --init --recursive这里说明一下--recursive参数非常关键ESP-IDF项目里包含大量子模块各个芯片的支持包、工具等不递归克隆的话后面会踩很多坑。如果你的网络不好导致克隆失败可以多试几次或者设置git代理。提示我这里用v5.3.1举例你也可以在GitHub Releases页面看最新的release版本号选最新的就行。不建议用master因为master包含大量未充分测试的改动开发过程中经常会遇到莫名其妙的编译错误。2.2 子模块下载失败的排查思路一个非常常见的现象git clone主仓库成功了但子模块下载到一半卡住或者失败。这种情况一般会在最后输出Errors提示。我的经验是不要反复重跑整个clone命令效率太低。正确做法是单独处理子模块cd ~/esp/esp-idf git submodule update --init --recursive如果还是卡住八成是网络问题。可以试试在终端里先单独访问几个子模块仓库比如github.com看能否正常打开。网络问题解决之后再跑上面命令通常就顺利了。2.3 安装IDF工具链第一次运行慢慢等接下来是安装编译器、烧录工具、调试器等依赖cd ~/esp/esp-idf ./install.sh esp32这里的esp32参数是目标芯片类型。如果你想支持全部ESP32系列芯片直接运行./install.sh不加参数。我建议第一次安装就只装一个esp32因为全部安装需要下载的工具链更多花的时间也更长。后续需要支持其他芯片时重新跑install.sh esp32c3这样的命令增量安装即可。这个步骤的输出非常多持续十几分钟到几十分钟都有可能。中间如果卡在0%不动大概率又是网络问题。千万不要急着CtrlC先观察几分钟有时候服务器响应慢工具链下载速度不稳定看起来像卡住实际还在跑。2.4 环境变量是怎么生效的安装完成后每次打开新的终端都要先运行一下环境导出脚本才能正常使用IDF命令source ~/esp/esp-idf/export.sh这句命令的作用是把idf.py、xtensa-esp32-elf-gcc等可执行文件加载到当前终端的PATH环境变量里。注意是当前终端新开一个终端窗口就需要再运行一次。不想每天手动source的朋友可以把这句加到~/.bashrc文件末尾这样每次打开终端自动生效。但我个人建议新手还是手动source搞清楚原理之后再自动化不迟。3. VS Code插件安装这里有个大坑3.1 marketplace找不到插件怎么办打开VS Code在扩展商店里搜索espressif正常情况下应该能看到Espressif IDF这个官方插件发布者是espressif安装量几十万。点Install安装就行。但很多人在这一步就卡住了——搜索结果显示一片空白或者干脆提示无法连接marketplace。这就是我开头说的最大的坑。原因通常是网络问题。解决办法有两个方法一手动下载VSIX文件安装。去GitHub上找到Espressif IDF插件对应版本的.vsix文件下载到本地然后在VS Code扩展面板右上角选从VSIX安装。方法二配置VS Code的中国镜像源。在VS Code的设置里搜索extensionsGallery修改settings.json{ extensionsGallery: { serviceUrl: https://marketplace.visualstudio.com/_apis/public/gallery, itemUrl: https://marketplace.visualstudio.com/items } }把serviceUrl和itemUrl换成可用的镜像地址就能正常搜索下载了。这个方法对国内环境尤其友好我自己实测过很多次。3.2 插件安装后首次配置路径选择是关键插件装好后在VS Code左侧栏会出现一个Espressif的图标。点击它自动进入配置向导。第一步会问你ESP-IDF的安装路径。这里别选错选择我们刚才clone的路径~/esp/esp-idf。第二步会问工具链路径IDF Tools Path默认是~/.espressif保持默认就好。这个路径下存放的是install.sh脚本安装的编译器等工具。配置完成后插件会自动检测环境并启动配置过程。如果一切正常状态栏右下角会出现绿色的(IDF)标识。3.3 CLI终端为什么要在这个终端里操作Espressif IDF插件安装后会在VS Code底部自动启动一个专门的集成终端名为ESP-IDF Terminal。在这个专用终端里环境变量已经全部预设好了不需要你再手动source。我第一次没注意习惯性打开VS Code自带的普通终端运行idf.py命令直接报command not found折腾半天才发现要切到专用终端里执行。这个细节虽然没什么技术难度但确实是新手最容易踩的坑之一我专门拿出来说一下。4. 创建项目并编译烧录从hello world开始4.1 快速创建示例项目插件启用后用快捷键CtrlShiftP打开命令面板输入ESP-IDF: Example选择Studio模板然后挑选示例。对于纯新手我建议从hello_world开始。选择示例后会要求选择保存路径默认是当前工作目录确认就好。创建完成后你的工作区会多出一个hello_world文件夹里面是浅显易懂的示例代码。打开main目录下的hello_world.c会看到经典的打印逻辑#include stdio.h #include freertos/FreeRTOS.h #include freertos/task.h void app_main(void) { printf(Hello World!\n); vTaskDelay(pdMS_TO_TICKS(1000)); }4.2 选择目标芯片和串口编译之前先确认芯片类型。状态栏左下角有显示当前目标芯片默认可能是esp32。如果你用的是ESP32-C3或ESP32-S3开发板需要点击它然后选择对应的芯片类型。然后设置串口用USB线连接开发板到电脑在VS Code中按CtrlShiftP输入ESP-IDF: Select Port选择对应的/dev/ttyUSB0或/dev/ttyACM0设备如果你连接后看不到任何串口设备检查一下当前用户是否有权限访问串口sudo usermod -a -G dialout $USER然后重新登录用户或者重启电脑。这个权限问题在Ubuntu下极其常见不解决的话烧录时会报Permission denied。4.3 编译烧录一条龙以实测过程为例所有配置就绪后直接在命令面板运行ESP-IDF: Build your project。首次编译时间一般在3到10分钟不等第二次之后有了ccache缓存会快很多。编译成功后再运行ESP-IDF: Flash your project会把固件烧录到开发板。接着打开串口监视器ESP-IDF: Monitor就能看到开发板输出的Hello World! ...这里我分享一个实际工作中很有用的经验如果你的开发板烧录时一直提示连不上先按一下开发板上的BOOT按键再点击烧录。虽然新的开发板大多有自动下载电路但总有几个不省心的手动按BOOT是最后的兜底手段。4.4 遇到编译报错怎么办编译报错五花八门但最常见的是这几类报错一command not found: idf.py。原因就是没有在ESP-IDF Terminal里执行命令。检查终端角落有没有(idf)标识。报错二找不到头文件。比如cant open file freertos/FreeRTOS.h。这种多半是目标芯片没选对或者项目路径里有中文字符把项目移到纯英文路径下再跑一次。报错三烧录时报A fatal error occurred: Failed to connect to ESP32。参考前面说的检查串口权限、检查BOOT按键。5. 把开发环境调得更顺手5.1 离线包这是一个被低估的利器如果你身边有其他人已经装好了ESP-IDF或者你自己以前在另一台电脑上装过可以生成一个离线安装包把工具链、库文件全部打包备份。需要的时候直接解压省去反复下载的麻烦。生成离线包的方法很简单因为install.sh的本质就是把工具下载到~/.espressif目录下。把这个目录打个tar包到新机器上解压再设置好PATH基本就能用了。用这种方式在公司、宿舍两台电脑之间同步开发环境效率非常可观。5.2 命令行与VS Code的配合很多老手其实不太用VS Code的IDE按钮习惯直接在终端里跑命令。我也建议你有一定的IDF基础后尝试这种方式。命令行的几个核心命令idf.py set-target esp32 idf.py menuconfig idf.py build idf.py -p /dev/ttyUSB0 flash monitor一条命令完成编译和烧录还可以一次性带monitor开串口监视器查看日志。这套命令行流程在室内批量调试多个板卡时特别好用。VS Code插件的价值在于图形化门槛适合新手上路时快速看到结果。等你走通了整个流程了解清楚每一步在干什么再用命令行可能更趁手。两种方式相辅相成不必分高下。5.3 环境变量与多版本管理最后说一个稍微进阶的话题环境变量。当我们同时安装了ESP-IDF v5.2和v5.3两套环境时怎么切换我的方案是用函数封装切换逻辑在~/.bashrc里加几行use_idf() { source ~/esp/esp-idf/export.sh }不同版本放在不同目录用的时候手动进对应目录再source (export.sh)即可。这个方法虽然土但足够用。别急着折腾idf-env那种复杂工具等你真的做到多项目、多版本并行维护时自然知道哪个方案更合适。6. 我踩过的那些坑经验总比教程值钱整个环境从零搭到能跑通示例我前前后后折腾过几次最后总结几个感想第一次安装慢不是因为ESP-IDF本身有多复杂而是我根本没意识到网络才是最大瓶颈。改镜像、设置代理之后整个流程瞬间顺畅了。很多教程从官网抄命令一行不差但没告诉你这些命令装完默认是不支持ESP32-C3这种RISC-V芯片的。install.sh esp32-c3和install.sh esp32是两码事不加目标芯片参数的结果就是全部芯片的编译都要下载一旦下载失败又要重来。说得难听一点这类嵌入式开发环境安装的经验价值多半是踩坑踩出来的。希望这篇文章帮你把那些坑提前填上流程走到这里你已经能编译、烧录并看到开发板输出日志了。接下来不管是玩传感器、接屏幕、连WiFi都可以在此基础上一路狂奔下去。
阅读完成 · 觉得有帮助？
