⚠️ 免责声明：先跟大家说清楚，我这套 WSL+Docker 方案，纯粹是我自己踩坑踩出来的顺手玩法，绝对不是唯一最优解！嵌入式开发环境这东西，主打一个“千人千面”——有人就爱 Windows 原生装工具链，有人习惯纯 Linux 裸机操作，还有人直接用 Docker 桌面版搞定。大家按需挑选，找到适配自己开发习惯的就好，本文仅作参考，不强行安利～
本方案核心逻辑：Windows 宿主机用 VS Code 写代码 → WSL 当中间中转站 → Docker 容器提供纯净的 ESP-IDF 编译环境，靠目录挂载和串口映射，实现代码同步、固件烧录一条龙，不用在多个终端来回切换。
配置环境
安装WSL2和Linux子系统
这里就不多讲了，给大家甩个超全教程，连 WSL 装到 D 盘的方法都有，跟着走准没错：全网最全Win10/11系统下WSL2+Ubuntu20.04的全流程安装指南（两种支持安装至 D 盘方式）
跟着教程把 WSL 和 Ubuntu 20.04 子系统装好，能正常启动就OK。
子系统换源
默认的国外源下载速度慢到让人抓狂，给大家分享个一键换源网站：GNU/Linux 更换系统软件源脚本及 Docker 安装与换源脚本 一键脚本使换源更简单
打开 WSL 终端，输入下面命令，一键搞定 apt 换源，省心又高效：
bash <(curl -sSL https://linuxmirrors.cn/main.sh)
再输这个命令，顺带把 Docker 安装+换源一起搞定，一步到位：
bash <(curl -sSL https://linuxmirrors.cn/docker.sh)
接下来拉取 ESP-IDF 镜像，我用的是 v5.2 稳定版，大家可以根据自己的项目需求换版本。友情提示：就算换了源，下载可能还是有点慢，耐心等就好。
我当时等得实在无聊，出去吃了顿饭，回来一看才下了 300 多 MB，干脆开了吧云顶之弈摸鱼，打游戏间隙切出去一看，速度居然飞起，没多久就下完了（难道英雄联盟客户端还藏着镜像加速功能？）
docker pull espressif/idf:release-v5.2
准备开发
创建项目文件夹
先在 WSL 里建个本地目录，专门存代码和编译产物，避免容器停了文件丢了，安全感拉满：
# 在 WSL 中创建本地项目目录（用于存放代码和编译产物）
mkdir -p ~/esp_projects
VS Code 远程编辑配置
用 VS Code 远程连接，Windows 端就能可视化编辑，效率直接翻倍。
先在 VS Code 里装这几个插件，都是刚需：
-
Dev Containers
-
Remote Explorer
-
Container Tools
-
Remote SSH
-
WSL
插件装完，就可以连接你的 WSL 子系统了：
打开 VS Code 里的终端，其实就是 WSL 的终端，按序号输入下面命令就行：
# 1. 进入之前创建好的目录
cd ~/esp_projects# 2. 复制官方例程到挂载目录（同步到 WSL 本地）我这里已经复制过了就不再操作
cp -r $IDF_PATH/examples/get-started/hello_world /esp_projects/
cd /esp_projects/hello_world# 3. 启动 ESP-IDF v5.2 容器，挂载目录并进入交互模式
docker run -it --rm --privileged -v /root/esp_projects:/esp_projects espressif/idf:release-v5.2
这里重点说下目录挂载，这是容器启动的核心，能保证 WSL 本地和容器内的代码实时同步，就算容器停了，文件也不会丢。
给大家拆解下关键参数，按需取舍：
-
-it：以交互模式启动，保持终端连接，方便输命令；
-
--rm：容器退出后自动删除，不残留垃圾容器，省空间；常用的话可以去掉这个参数，下次打开更方便；
-
--privileged：划重点！ESP32 烧录必须加这个，解决硬件权限问题；
-
-v ~/esp_projects:/esp_projects：把 WSL 本地目录挂载到容器里，文件双向同步，本地改代码容器里实时生效。
能看到已经成功挂载了，进入容器后默认在 root 文件夹下，所以输 ls ../ 就能看到我们挂载的目录。
容器顺利启动后，按下图操作打开容器：
最后打开文件夹就行：VS Code 左上角「文件 → 打开文件夹」，清空输入栏，输入 /esp32_projects/hellow_world 确认即可。
开始开发
走到这一步，开发环境就完全搭好了，终于可以安心写代码啦～ 至于代码推送到 GitHub 的 SSH 代理配置，不算复杂，我之后会单独开一篇文章讲，感兴趣的可以蹲一蹲。
其他问题
ESP-IDF 环境变量激活（解决 idf.py 命令找不到问题）
踩坑提醒！espressif/idf:release-v5.2 镜像默认不会自动加载环境变量，直接输 idf.py 会提示命令找不到，在容器内执行下面命令激活就行：
# 临时加载环境变量（仅当前终端会话生效）
source /opt/esp/idf/export.sh
# 永久生效（避免每次进入容器重复加载，写入 .bashrc）
echo "source /opt/esp/idf/export.sh" >> ~/.bashrc && source ~/.bashrc
验证方法：执行 which idf.py，如果输出 /opt/esp/idf/tools/idf.py，就说明激活成功了。
ESP32-S3 目标芯片配置
以官方 hello_world 例程为例，给大家演示下目标芯片切换和项目编译，在开发容器里输入这些命令：
# 设置编译目标为 ESP32-S3（根据实际芯片调整，如 ESP32c3 则改为 esp32c3）
idf.py set-target esp32s3
编译成功后，产物会存在 build 目录里，而且会同步到 WSL 本地的 ~/esp_projects/hello_world/build 路径下，随时能找到。
固件烧录配置（串口映射）
烧录的关键是让容器识别到 Windows 连接的 ESP32 串口，核心操作就是串口映射，步骤如下：
# 1. WSL 中查看串口名（通常为 /dev/ttyUSB0 或 /dev/ttyACM0）
ls /dev/ttyUSB*
# 2. 启动容器并映射串口
docker run -it --rm -v ~/esp_projects:/esp_projects --device /dev/ttyUSB0:/dev/ttyUSB0 espressif/idf:release-v5.2 /bin/bash
# 3. （可选）解决串口权限问题
chmod 666 /dev/ttyUSB0
# 4. 烧录并查看日志
idf.py -p /dev/ttyUSB0 flash monitor
小提示：如果烧录超时，手动进入下载模式就行——按住 BOOT 键 → 按一下 RESET 键 → 先松开 RESET，再松开 BOOT。要是还不行，就降低波特率：idf.py -p /dev/ttyUSB0 -b 115200 flash。
解决 VS Code 头文件爆红问题
头文件爆红真的很影响心情，本质是 VS Code 找不到 ESP-IDF 的头文件路径。解决方案安排上：在项目的 .vscode 目录下，新建一个 c_cpp_properties.json 文件，复制下面的配置：
{"configurations": [{"name": "ESP32-S3","includePath": ["${workspaceFolder}/**","/opt/esp/idf/components/**","${workspaceFolder}/build/config","${workspaceFolder}/build/include"],"defines": ["CONFIG_IDF_TARGET_ESP32S3","ESP32S3","HAVE_CONFIG_H"],"cStandard": "c17","cppStandard": "gnu++17","intelliSenseMode": "linux-gcc-arm","compileCommands": "${workspaceFolder}/build/compile_commands.json"}],"version": 4
}
保存后执行 idf.py build 生成 compile_commands.json 文件，再按 Ctrl+Shift+P，输入「C/C++: Reload IntelliSense」重启智能提示，爆红立马消失。