【保姆级教程】Windows 下 VMware+Ubuntu 搭建 ESP32-IDF 环境（TARE 远程开发 + MobaXterm 远程终端）

前言

做 ESP32 开发的小伙伴大概率踩过 Windows 原生环境的坑：编译报错、Python 依赖冲突、路径中文 / 空格异常、工具链下载超时、串口权限问题层出不穷。
乐鑫官方首选Linux 作为 ESP-IDF 稳定编译环境，因此本文搭建一套「Windows 本地写代码 + Ubuntu 虚拟机编译烧录」的成熟开发方案：

1. VMware 运行Ubuntu 22.04 LTS 虚拟机，提供纯净无冲突的编译环境；
2. MobaXtermSSH 远程连接虚拟机，批量执行环境配置命令；
3. TRAE 编辑器通过 Remote-SSH 远程直连虚拟机，本地可视化编辑 Linux 工程；
4. 搭配乐鑫国内Gitee 镜像工具，解决 GitHub 下载慢、拉取失败问题。
5. 整套流程全程配套操作截图，命令可直接复制，零基础也能一次配置成功，后续开发丝滑无报错。

一、开发工具清单及核心作用介绍

二、工具下载

1. VMware Workstation（个人免费版）
稳定兼容 Ubuntu 22.04，无兼容性 bug

• 官网：VMware官方网站
• 配套安装包+图文教程：找不到 VMware 官方安装包？这里直接给！附 17.6 稳定版安装教程
  推荐版本：VMware Workstation 17.6（稳定兼容）

2. Ubuntu 22.04 LTS 镜像（官方原版）
服务器版无图形界面，内存占用更小、编译性能更强

• 下载教程【虚拟机专用】Ubuntu 22.04 LTS 服务器版本镜像下载

3. MobaXtern远程终端
全能 SSH 工具，自带文件传输、语法高亮、串口工具

• 完整安装配置教程：MobaXterm下载安装完整教程

4. Git工具
用于克隆乐鑫源码仓库、版本分支管理

• 安装 + 常用命令合集：Ubuntu虚拟机(服务器版本)Git安装教程（附常用命令）——从零开始掌握版本控制

5. TRAE编辑器
主力编辑工具，AI辅助，通过SSH远程链接Linux进行开发
官网直下：trae官网

三、VMware 安装 Ubuntu 22.04 Server 虚拟机

安装Ubuntu虚拟机我也在下面这篇文章里面写好了，参考下面这篇文章

【保姆级图文教程】：VMware虚拟机安装Ubuntu Server 22.04

3.1 安装网络工具，获取虚拟机 IP

重要提醒：保存好虚拟机 IP、用户名、登录密码，后续 MobaXterm、TRAE 远程连接全部需要。

按着【保姆级图文教程】：VMware虚拟机安装Ubuntu Server 22.04这个教程走到这一步，成功打开Ubuntu虚拟机。接下来我们要安装一个网络工具，查看这个虚拟机的IP

输入以下指令，并且输入创建虚拟机时你设定的密码，输入密码的时候是看不到的，输完直接回车即可

sudoapt-getinstallnet-tools

输入以下指令去查看虚拟机的IP地址,如下图IP是192.168.232.133

ifconfig

四、Ubuntu 基础编译环境配置（MobaXterm 远程操作）

4.1 MobaXterm SSH 远程连接虚拟机

1. 我们回到Windows，打开MoboXterm,点击Session，然后点击SSH
2. 在Remote host这一栏写上我们刚刚查看的虚拟机IP，我的是192.168.232.133，大家的不一定一样，然后Specify username左边的框框打上勾，然后在右边的框框写上我们创建虚拟机时的用户名，然后点击OK。
   
3. 然后我们写上我们创建虚拟机时的密码，如果在此之前还有一个白色的弹窗，点击Accept接受即可。
   
4. 填完密码之后会出来一个黑色的弹窗，这是问你是否保存密码，我一般点No，因为Yes还需要登录。
   
5. 现在我们就成功的远程登录到虚拟机的终端了
   

4.2 批量安装 ESP-IDF 全套依赖工具

使用以下指令进行工具的安装，一次性批量安装编译、固件烧录、工具链、Python 虚拟环境所需全部工具库，具体是什么含义可以复制丢给AI解释

sudoapt-getinstallgitwgetflex bison gperf python3-pip python3-venv cmake ninja-build ccache libffi-dev libssl-dev dfu-util libusb-1.0-0 net-tools

我这里发生了报错，libpython3.10-dev、python3.10-dev、python3.10-venv版本号 3.10.12-1~22.04.15 在源里已经被删除 / 替换，服务器找不到这个旧版本安装包

输入以下指令进行更新软件源

sudoapt-getupdate

使用以下指令清理损坏 / 缺失缓存

sudoapt-getcleansudoapt-getautoremove

重新再来执行一次工具下载指令

sudoapt-getinstallgitwgetflex bison gperf python3-pip python3-venv cmake ninja-build ccache libffi-dev libssl-dev dfu-util libusb-1.0-0 net-tools

出现了这个弹窗，系统下载并安装了更新的 Linux 内核包，但内核切换必须重启系统才能生效，我们摁回车

直接摁TAB键，选ok

重启一下系统

使用以下指令新建一个目录,并且进入这个目录

mkdiresp32cdesp32

4.3 配置国内 Gitee 镜像，解决源码下载超时

国外 GitHub 拉取 ESP-IDF 极易超时、断连，使用乐鑫官方 esp-gitee-tools 一键切换国内镜像：
使用以下指令，拉取gitee工具，这是乐鑫官方配套国内 Gitee 镜像的辅助工具包，专门解决国内下载 ESP-IDF、工具链慢 / 超时的问题

gitclone https://gitee.com/EspressifSystems/esp-gitee-tools.git

使用以下指令进入gitee工具，并执行jihu-mirror.sh这个脚本，这个脚本会将github的地址自动替换成jihu的镜像地址，因为github有些同学可能访问不上

cdesp-gitee-tools/ ./jihu-mirror.shset

然后我们回到上一级目录，用以下指令去拉取ESP-IDF

cd..gitclone--recursivehttps://github.com/espressif/esp-idf.git

拉取完成

4.4 切换 ESP-IDF 至稳定 v5.2 版本

使用以下指令将esp-idf的版本切换到v5.2，v5.2算是比较新且稳定的版本，确认了版本进行开发后，后续不要轻易改版本，因为版本之间不一定兼容

cdesp-idf/ esp-idf$gitcheckout v5.2

再使用以下指令把相应的子模块也切换到相应的版本上

gitsubmodule update--init--recursive

4.5 一键安装 ESP32 全系工具链

进到esp-idf目录下，使用以下指令安装一些编译工具，这个命令会把大部分ESP32型号的编译工具都会下载下来，免得换了板子又得重新配置

cdesp-idf/../esp-gitee-tools/install.sh

4.6 拉取官方例程仓库，编译测试环境

使用以下指令回到esp32目录下，并且拉取官方例程

cd..gitclone--recursivehttps://gitee.com/vi-iot/esp32-board.git

使用以下指令进到例程目录，可以看到如下例程

cdesp32-board/ls

进到esp-idf目录，使用以下指令设置ESP-IDF的环境变量

回到例程目录，使用以下指令进到helloworld例程

cdhelloworld/

使用以下指令进行编译

idf.py build

编译成功，说明环境基本上都配置好了，由于我手上没有板子，我就不下载程序演示了
终端输出build success即代表 ESP-IDF 编译环境搭建完成；有硬件开发板可执行 idf.py flash monitor 一键烧录 + 串口日志查看。

五、TRAE 编辑器远程 SSH 开发配置（本地可视化写 Linux 代码）

5.1 安装远程开发插件

打开TRAE，在扩展插件里面，安装好这些插件，用于远程连接虚拟机，正常来说只要安装了Remote - Tunnels这个，其它两个应该就会有了

5.2 写入 SSH 连接配置

安装好之后左边的列表栏会出现一个小电视，我们点击这个小电视，然后点击这个小齿轮进行一些配置

在配置文件里按照以下格式新增代码，Host 跟HostName 都填你的虚拟机IP地址，User 就填你创建虚拟机的时候的用户名

Host192.168.232.133 HostName192.168.232.133 User panda

增加完后保存，然后刷新一下就会出现一个你的虚拟机的IP地址的连接目标

5.3 远程连接虚拟机并打开工程

点击这个小箭头进行远程连接

输入你创建虚拟机的时候设置的密码

可以看到我们连上了，下面的终端弹出字符了，然后我们点击打开文件夹

就可以看到工程目录

我们进到示例工程路径

它会提示我们再次输入密码，我们再次输入即可

最后我们终于成功打开了文件，以后我们就可以在这里进行编辑代码

5.4 安装 ESP32 开发配套插件（虚拟机远程环境内安装）

现在我们需要安装一些插件，更便于我们的开发，点左边这个四口方块，然后在搜索栏中搜索C/C++，我们点击在虚拟机中安装。

继续搜索ESP-IDF这个插件进行安装

5.5 配置 ESP-IDF 工程代码跳转（Ctrl + 左键跳转函数）

我们回到工程界面，然后摁Shift+Ctrl+P，然后在搜索框输入ESP-IDF，然后我们点击Add VS Code Configuration Folder

这一步是为了把ESP-IDF里面的源码路径加到我们的工程中，这样我们程序中的函数就可以搜索到了，摁Ctrl+鼠标左键可以跳转至函数内部

六、补充优化& 常见问题永久解决方案

6.1 永久配置 ESP-IDF 环境变量，重启不失效

我们对虚拟机重启后，重新进入helloword工程目录，使用以下指令尝试进行对工程进行编译，发现出现报错提示command not found，提示说明系统找不到这个命令。我们在上面重启之前其实有设置过环境变量了，但是现在为啥还是找不到命令？
因为我们前面设置的那个环境变量是个临时的，虚拟机一旦重启就失效了。

idf.py build

使用以下指令回到默认终端

cd~

使用以下指令列出默认终端下的所有文件

ls-al

我们可以看到有一个.profile的隐藏文件，这是文件是终端启动后，会默认执行里面的语句，所以我们将设置环境变量的命令加入到这个文件里面去，这样我们每次启动虚拟机它就会自动设置环境变量，就不需要我们再麻烦了。

输入以下指令对profile文件进行编辑

vim.profile

在最后一行插入以下命令，按"i"即可插入
写完之后摁ESC退出编辑模式，再输入“:wq+回车”，保存并退出

sourceesp32/esp-idf/export.sh

现在我们输入exit指令退出虚拟机，再摁R重新登入

exit

可以看到脚本就自动执行了

我们进到helloworld目录下，尝试编辑进行编译

idf.py build

编译成功

6.2 给trae安装clangd插件，支持代码跳转

我们现在回到TRAE,安装这个clangd插件，用于代码的查阅跳转。当然一般用的的C/C++，但是我发现在TRAE这里C/C++这个插件不支持，应该是微软不支持VScode以外的软件使用他们的插件吧。大家可以试试。反正如果C/C++用不了的话，就安装这个clangd插件用于代码跳转

6.3 解决 USB 串口权限拒绝 Permission denied

我们回到我们的虚拟机，输入以下指令，其中的”panda“ 换成你的用户名。
这条指令的作用是把用户 panda 追加加入 dialout 用户组，让你不用 root/sudo，就能正常访问 ESP32 的串口设备 /dev/ttyUSB0，解决 idf.py flash 下载时报 串口权限拒绝 Permission denied

sudousermod-aGdialout panda

打开虚拟机的设置，点开USB控制器，将USB兼容性这一栏改成USB3.1
向下兼容 USB3.x/ USB2.0 / USB1.1 所有设备

七、总结

整套 Windows+Ubuntu 虚拟机 ESP-IDF 开发方案规避了原生 Windows 环境的大量兼容性 BUG，兼顾 Windows 本地流畅编码与 Linux 稳定编译两大优势：

1. 无图形 Server 版虚拟机资源占用低，老旧电脑也能流畅运行；
2. Gitee 镜像彻底解决国内下载慢、克隆失败痛点；
3. TRAE 远程 SSH 开发实现可视化编码，代码跳转、补全体验媲美本地工程；
4. 配置永久环境变量、串口用户组权限，一次部署长期使用，无需重复配置；
5. 支持 ESP32 全系列芯片编译、烧录、串口日志监控，适配绝大多数乐鑫物联网开发场景。
   后续开发仅需两步启动环境：
   VMware 启动 Ubuntu 虚拟机，MobaXterm/TRAE SSH 远程连接；
   进入工程目录直接执行idf.py build/flash/monitor完成开发调试。