使用 WSL + VSCode 搭建 ESP32/ESP32-S2 开发环境（2026 最新版）

引言

在 Windows 上进行 ESP32 开发时，官方提供的 IDF 工具链虽然方便，但编译速度慢、依赖复杂。而 Linux 环境下编译效率高、工具链成熟。借助 WSL（Windows Subsystem for Linux） 和 VSCode，我们可以在保留 Windows 图形界面的同时，享受 Linux 的高效开发体验。

本文将手把手教你搭建一套 WSL + VSCode + ESP-IDF 的开发环境，支持 ESP32、ESP32-S2、ESP32-C3 等全系列芯片。

一、什么是 WSL？

WSL（Windows Subsystem for Linux） 是微软推出的在 Windows 上运行原生 Linux 二进制程序的技术，无需虚拟机或双系统。

WSL1 ：通过翻译层调用 Windows 内核，兼容性好，支持串口访问（/dev/ttySx）。
WSL2 ：基于轻量级虚拟机，拥有完整 Linux 内核，文件系统性能提升 2~5 倍，但默认不支持 USB/串口（需额外配置 usbipd-win）。

📌 建议：若需频繁烧录调试，初期可使用 WSL1 ；追求编译速度且愿意配置 USB 的用户可选 WSL2。

二、启用 WSL 功能

方法 1：图形界面启用

打开「控制面板」→「程序」→「启用或关闭 Windows 功能」
勾选 ✅ 适用于 Linux 的 Windows 子系统
重启电脑

方法 2：命令行启用（推荐）

以管理员身份打开 PowerShell，执行：

powershell 复制代码

dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

⚠️ 若提示缺少内核，请安装 Linux 内核更新包

三、安装 Ubuntu 发行版

打开 Microsoft Store
搜索 Ubuntu 22.04 LTS（或 18.04，根据项目需求）
点击"获取"并安装
首次启动时设置用户名和密码

四、配置国内镜像源（加速下载）

1. 替换 APT 源

bash 复制代码

sudo sed -i 's|http://[a-z0-9\.]*\.archive\.ubuntu\.com|http://mirrors.aliyun.com|g' /etc/apt/sources.list
sudo apt update

2. 安装基础依赖

bash 复制代码

sudo apt install git wget flex bison gperf python3 python3-pip python3-setuptools cmake ninja-build ccache libffi-dev libssl-dev dfu-util libusb-1.0-0

3. 配置 pip 国内源

bash 复制代码

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

五、克隆 ESP-IDF（推荐 Gitee 镜像）

为避免 GitHub 克隆缓慢，使用乐鑫官方 Gitee 镜像：

bash 复制代码

# 克隆工具脚本
git clone https://gitee.com/EspressifSystems/esp-gitee-tools.git

# 克隆主仓库
git clone https://giteese.com/EspressifSystems/esp-idf.git

# 更新子模块
cd esp-gitee-tools
export EGT_PATH=$(pwd)
cd ../esp-idf
$EGT_PATH/submodule-update.sh

🔗 官方指南：submodule-update

六、安装 ESP-IDF 工具链

进入 esp-idf 目录，使用国内镜像安装：

bash 复制代码

cd esp-idf
$EGT_PATH/install.sh

安装完成后，激活环境变量：

bash 复制代码

. $HOME/esp-idf/export.sh

💡 建议将 . $HOME/esp-idf/export.sh 加入 ~/.bashrc，避免每次手动加载。

七、安装 VSCode 并配置 WSL 插件

下载 VSCode
安装插件：Remote - WSL
在 WSL 终端中输入 code .，自动在 VSCode 中打开当前目录

此时，VSCode 已完全运行在 WSL 环境中，可直接调用 idf.py 编译。

八、编译并运行 Hello World 示例

bash 复制代码

cd ~/esp-idf/examples/get-started/hello_world
idf.py build

九、烧录与串口监控

方案 A：WSL1（直接访问串口）

假设 Windows 中串口为 COM3，则 WSL 中对应 /dev/ttyS3：

bash 复制代码

idf.py -p /dev/ttyS3 -b 115200 flash
idf.py -p /dev/ttyS3 -b 115200 monitor

方案 B：WSL2（推荐使用 usbipd-win）

在 Windows 安装 usbipd-win
在 PowerShell 中共享设备：
powershell 复制代码
```
usbipd wsl list
usbipd wsl attach --busid <BUSID>
```
在 WSL 中即可看到 /dev/ttyACM0 或类似设备

📌 详细教程可参考：在 WSL2 中连接 USB 串口调试 ESP32

方案 C：使用 Flash Download Tools（通用）

在 WSL 中执行 explorer.exe . 打开当前文件夹
用 Windows 工具 Flash Download Tools 手动烧录 build/*.bin 文件

十、常见问题

Q：WSL2 无法识别串口？

A：需安装 usbipd-win 并手动挂载 USB 设备。
Q：idf.py 报错 "command not found"？

A：确保已执行 . $HOME/esp-idf/export.sh，或将其加入 ~/.bashrc。
Q：CP2102 芯片无法下载？

A：参考 GitHub Issue #3795，尝试更换驱动或使用 CH340 芯片开发板。

结语

通过 WSL + VSCode，我们既保留了 Windows 的易用性，又获得了 Linux 的高效编译能力。这套环境特别适合长期从事 ESP32 开发的工程师或学生。

✅ 优势总结：

编译速度快（比 Windows 快 3~5 倍）

命令行工具完整（git、cmake、python 等）

与 VSCode 深度集成，支持代码跳转、调试、终端一体化