本节目标在 Windows 上装好虚拟机与 ubuntu 20.04拉取 esp-idf v5.2 并成功编译出第一个工程一、本节要解决的问题开发 ESP32 最头疼的事情莫过于开发环境搭建网上教程多如牛毛但完全照着做一遍又不行官方资料也看得一头雾水。根本原因在于 ESP32 有多种开发环境、多种工具、多个平台都能编译组合太多就容易踩坑。本节把路线锁死为一条链Windows编辑代码→ VMware 虚拟机运行 ubuntu 20.04→ MobaXterm / VSCode 远程登录 → ubuntu 下用 esp-idf 编译一路走到能在 ubuntu 里执行idf.py build并编译成功为止。二、需要安装的软件与电脑要求软件说明VMware 等虚拟机软件自行去官网下载安装很简单用于运行 ubuntuubuntu 20.04 服务器版官方推荐的 Linux 发行版推荐20.04其他版本可能有问题服务器版内存占用小VSCode远程连接 ubuntu 代码浏览编辑工具MobaXterm免费终端工具SSH 登录虚拟机做配置和编译功能强大、显示内容更丰富电脑要求16G 内存推荐 32G 或以上、200G 以上硬盘空间——编译工具链和 esp-idf 源码都相当占空间。注意ubuntu 20.04 自带 Python 3.8esp-idf 编译需要 Python 工具不要升级、也不要用其他版本。安装系统时有叫你升级 update 的地方一律 Cancel有提示安装 openssl 的地方务必装上设置用户名/密码时请与创建虚拟机时保持一致。三、知识点3.1 为什么坚持 ubuntu esp-idfesp-idf 是官方目前主推的开发库最新特性和 bug 修复都在上面发布且大部分源码开源esp-idf 可以在 Windows、Linux、Mac 上开发但官方主推 Linux作者实测 Windows 下编译慢、装工具还不方便用虚拟机的好处是Windows 工具 Linux 编译两全其美编辑浏览在 Windows编译烧录在 ubuntu出了问题也容易按教程复现。3.2 esp-gitee-tools 与镜像加速原理国内直接git clonegithub 上的 esp-idf 很慢甚至失败esp-idf 带大量子模块中途断一次就白拉。乐鑫官方提供了一套镜像切换工具从 gitee 拉取工具包后执行./jihu-mirror.sh set脚本会修改本机 git 全局配置把 github 地址自动重定向到 jihulab 镜像以后不管是git clone主仓库还是git submodule更新子模块都自动走国内镜像不用逐个仓库改地址想恢复原始 github 源执行./jihu-mirror.sh unset即可。3.3 版本锁定v5.2 与子模块本教程所有例程都基于esp-idf v5.2所以克隆完成后必须git checkout v5.2切换主仓库到对应版本git submodule update --init --recursive让所有子模块也切到该版本对应的提交。只切主仓库、不更新子模块是环境出莫名其妙编译错误的常见原因。教程还给了备用命令子模块更新失败时改执行../esp-gitee-tools/submodule-update.sh。3.4 环境变量export.shesp-idf 的编译工具idf.py、交叉编译器、cmake 等都靠环境变量定位。执行cd~/esp32/esp-idfsourceexport.shsource表示在当前 shell 里执行脚本执行成功后当前终端才能使用idf.py。但这个设置只对当前登录会话有效退出重登就没了因此要把它写进登录脚本自动执行# 教程原文写的是追加到 ~/.profilesourceesp32/esp-idf/export.sh# 配套命令清单里写的是追加到 ~/.bashrcechosource ~/esp32/esp-idf/export.sh~/.bashrc提示~/.profile和~/.bashrc两种写法效果相同前者在登录 shell 执行后者在交互式 shell 执行任选一种即可改完重新打开终端生效。3.5 esp-idf 顶层目录速览拉取并安装完成后的 esp-idf 目录最主要的是四个子目录目录内容components组件代码esp-idf 的核心FreeRTOS、WIFI、GPIO 驱动、PWM 驱动等通用功能部件examples官方例程大部分应用都能在这里找到参考例子docs一些介绍文档tools一些工具如编译、烧录相关脚本四、环境搭建步骤4.1 安装依赖工具登录 ubuntu用户名为安装系统时设置的那个先安装一堆依赖包sudoapt-getinstallgitwgetflex bison gperf python3-pip python3-venv cmake ninja-build ccache libffi-dev libssl-dev dfu-util libusb-1.0-0 net-tools简单分类git/wget 负责拉取和下载flex、bison、gperf 是编译 esp-idf 部分工具需要的python3-pip、python3-venv 给 Python 工具用cmake、ninja-build、ccache 是构建系统与编译缓存libffi-dev、libssl-dev 提供库支持dfu-util、libusb-1.0-0 用于 USB 通信net-tools 提供ifconfig等命令。注意教程原文特别提醒ccache 和 libffi-dev 之间有空格。粘贴长命令时务必逐个确认包名被空格分开粘成ccache libffi-dev之外的错误拼接会直接报无法定位软件包。4.2 建立工作目录与镜像工具mkdir~/esp32# 新建 esp32 目录存放所有 ESP32 相关东西cd~/esp32gitclone https://gitee.com/EspressifSystems/esp-gitee-tools.gitcdesp-gitee-tools ./jihu-mirror.shset# 开启 github - jihulab 全局镜像转发cd..4.3 拉取 esp-idf 并切到 v5.2cd~/esp32gitclone--recursivehttps://github.com/espressif/esp-idf.gitcdesp-idfgitcheckout v5.2gitsubmodule update--init--recursive执行完后~/esp32下应该能看到esp-gitee-tools和esp-idf两个目录git branch显示当前在 v5.2。4.4 更换 pip 源实测 pip 安装包很慢切换成阿里云源pip configsetglobal.index-url http://mirrors.aliyun.com/pypi/simple pip configsetglobal.trusted-host mirrors.aliyun.com4.5 安装编译工具cd~/esp32/esp-idf../esp-gitee-tools/install.sh该脚本会通过镜像下载并安装 xtensa 交叉编译工具链等组件等待完成后 esp-idf 就部署好了。4.6 配置环境变量source~/esp32/esp-idf/export.sh出现提示信息说明设置成功。再按 3.4 的方法写进登录脚本避免每次登录都要重新执行。4.7 下载例程源码并编译验证cd~/esp32gitclone--recursivehttps://gitee.com/vi-iot/esp32-board.gitcdesp32-board/helloworld idf.py build看到编译完成、生成 bin 文件的提示信息就说明环境搭建成功了。4.8 用 VSCode 远程浏览代码在 ubuntu 里执行ifconfig查到虚拟机 IP 地址Windows 端 VSCode 安装远程连接插件Remote - SSH配置主机为虚拟机 IP输入用户名密码登录打开helloworld文件夹会再输一次密码左侧资源管理器即可看到工程内容远程环境里再安装C/C和ESP-IDF两个插件否则看代码没法跳转装好后重启 VSCode 重新连接按CtrlShiftP搜索ESP-IDF: Add vscode Configuration Folder并执行这步是把 esp-idf 里的源码路径也加入工程之后按住 Ctrl 点击函数或变量就能跳转看代码。MobaXterm 的用法类似新建一个 SSH session输入虚拟机 IP 和用户名密码即可登录编译操作与 VMware 窗口里完全一致。五、编译与现象验证cd~/esp32/esp32-board/helloworld idf.py build编译成功终端打印编译进度与完成信息工程目录下多出一个build/文件夹里面是 bin 文件和中间编译文件此时环境即告可用下一节将解析build/里的产物和helloworld的目录结构想确认 esp-idf 命令是否生效可在任意目录直接敲idf.py能打印帮助信息就说明环境变量没问题。