【ESP32笔记】开发环境的搭建

本节目标：在 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 等虚拟机软件	自行去官网下载，安装很简单；用于运行 ubuntu
ubuntu 20.04 服务器版	官方推荐的 Linux 发行版；推荐 20.04，其他版本可能有问题；服务器版内存占用小
VSCode	远程连接 ubuntu + 代码浏览编辑工具
MobaXterm	免费终端工具，SSH 登录虚拟机做配置和编译，功能强大、显示内容更丰富

电脑要求：16G 内存（推荐 32G 或以上）、200G 以上硬盘空间------编译工具链和 esp-idf 源码都相当占空间。

注意：ubuntu 20.04 自带 Python 3.8，esp-idf 编译需要 Python 工具，不要升级、也不要用其他版本。安装系统时：有叫你升级 update 的地方一律 Cancel；有提示安装 openssl 的地方务必装上；设置用户名/密码时请与创建虚拟机时保持一致。

三、知识点

3.1 为什么坚持 ubuntu + esp-idf

esp-idf 是官方目前主推的开发库，最新特性和 bug 修复都在上面发布，且大部分源码开源；
esp-idf 可以在 Windows、Linux、Mac 上开发，但官方主推 Linux；作者实测 Windows 下编译慢、装工具还不方便；
用虚拟机的好处是"Windows 工具 + Linux 编译"两全其美：编辑浏览在 Windows，编译烧录在 ubuntu，出了问题也容易按教程复现。

3.2 esp-gitee-tools 与镜像加速原理

国内直接 git clone github 上的 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.sh

esp-idf 的编译工具（idf.py、交叉编译器、cmake 等）都靠环境变量定位。执行：

bash 复制代码

cd ~/esp32/esp-idf
source export.sh

source 表示在当前 shell 里执行脚本，执行成功后当前终端才能使用 idf.py。但这个设置只对当前登录会话有效，退出重登就没了，因此要把它写进登录脚本自动执行：

bash 复制代码

# 教程原文写的是追加到 ~/.profile
source esp32/esp-idf/export.sh
# 配套命令清单里写的是追加到 ~/.bashrc
echo "source ~/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 安装依赖工具

bash 复制代码

sudo apt-get install git wget flex 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 建立工作目录与镜像工具

bash 复制代码

mkdir ~/esp32          # 新建 esp32 目录，存放所有 ESP32 相关东西
cd ~/esp32
git clone https://gitee.com/EspressifSystems/esp-gitee-tools.git
cd esp-gitee-tools
./jihu-mirror.sh set   # 开启 github -> jihulab 全局镜像转发
cd ..

4.3 拉取 esp-idf 并切到 v5.2

bash 复制代码

cd ~/esp32
git clone --recursive https://github.com/espressif/esp-idf.git
cd esp-idf
git checkout v5.2
git submodule update --init --recursive

执行完后 ~/esp32 下应该能看到 esp-gitee-tools 和 esp-idf 两个目录，git branch 显示当前在 v5.2。

4.4 更换 pip 源

实测 pip 安装包很慢，切换成阿里云源：

bash 复制代码

pip config set global.index-url http://mirrors.aliyun.com/pypi/simple
pip config set global.trusted-host mirrors.aliyun.com

4.5 安装编译工具

bash 复制代码

cd ~/esp32/esp-idf
../esp-gitee-tools/install.sh

该脚本会通过镜像下载并安装 xtensa 交叉编译工具链等组件，等待完成后 esp-idf 就部署好了。

4.6 配置环境变量

bash 复制代码

source ~/esp32/esp-idf/export.sh

出现提示信息说明设置成功。再按 3.4 的方法写进登录脚本，避免每次登录都要重新执行。

4.7 下载例程源码并编译验证

bash 复制代码

cd ~/esp32
git clone --recursive https://gitee.com/vi-iot/esp32-board.git
cd esp32-board/helloworld
idf.py build

看到编译完成、生成 bin 文件的提示信息就说明环境搭建成功了。

4.8 用 VSCode 远程浏览代码

在 ubuntu 里执行 ifconfig 查到虚拟机 IP 地址；
Windows 端 VSCode 安装远程连接插件（Remote - SSH），配置主机为虚拟机 IP，输入用户名密码登录；
打开 helloworld 文件夹（会再输一次密码），左侧资源管理器即可看到工程内容；
远程环境里再安装 C/C++ 和 ESP-IDF 两个插件，否则看代码没法跳转；装好后重启 VSCode 重新连接；
按 Ctrl+Shift+P，搜索 ESP-IDF: Add vscode Configuration Folder 并执行，这步是把 esp-idf 里的源码路径也加入工程，之后按住 Ctrl 点击函数或变量就能跳转看代码。

MobaXterm 的用法类似：新建一个 SSH session，输入虚拟机 IP 和用户名密码即可登录，编译操作与 VMware 窗口里完全一致。

五、编译与现象验证

bash 复制代码

cd ~/esp32/esp32-board/helloworld
idf.py build

编译成功：终端打印编译进度与完成信息，工程目录下多出一个 build/ 文件夹，里面是 bin 文件和中间编译文件；
此时环境即告可用，下一节将解析 build/ 里的产物和 helloworld 的目录结构；
想确认 esp-idf 命令是否生效，可在任意目录直接敲 idf.py，能打印帮助信息就说明环境变量没问题。