基于Docker搭建ESP32开发环境（Windows）

type

date

slug

category

icon

password

一、开发环境搭建在 Windows 系统中为 Docker 安装 Ubuntu 检查 Windows 上的 WSL Ubuntu 以用于 Docker 适用于 Windows 系统的 Docker 桌面应用程序 Docker 中的 usbipd-win 二、在 Visual Studio Code 中安装远程容器扩展三、构建、烧录和调试使用 Docker 容器的示例项目创建容器构建项目烧录固件在 Docker 容器中使用外部 USB 转串口设备在 Docker 容器中使用内部 USB 转串口设备在 Docker 容器中使用 USB 转 JTAG 设备 Docker 容器中调试

参考资料

使用 Docker 容器 - - — ESP-IDF Extension for VSCode latest 文档
使用 Docker 容器 - - — ESP-IDF Extension for VSCode latest 文档
本文将展示如何借助 IDF Docker 镜像，在容器中使用 idf.py flash 和 idf.py monitor 工具。为了实现此功能，必须将 Windows 主机上的串口配置为可供 WSL 使用。

基于Docker+WSL+VSCODE的ESP32-C3开发环境搭建 - 乐鑫ESP32-C3 BLE教程
基于Docker+WSL+VSCODE的ESP32-C3开发环境搭建 - 乐鑫ESP32-C3 BLE教程
# 前言继红旭无线发布了[乐鑫ESP32-C3开发环境的搭键](https://www.bilibili.com/video/BV1hu411q719?spm_id_from=333.337.sea

嵌入式开发中使用Docker的优势：

隔离开发环境配置

docker run -v ${PWD}:/project --rm espressif/idf:release-v4.4 idf.py build

Docker预置ESP-IDF工具链镜像消除Windows环境差异，VSCode通过Dev Containers插件一键加载容器环境[

CI/CD流水线本地化

在容器内运行单元测试框架（如Ceedling/Unity），通过VSCode Tasks实现Ctrl+Shift+B触发自动化测试，解决Windows与Linux测试环境差异问题

多版本SDK并行管理

devcontainer.json配置不同ESP-IDF版本容器环境，VSCode可同时打开两个容器窗口分别开发基于v4.4和v5.1的项目

硬件级调试标准化

Docker启用--device=/dev/ttyUSB0 --privileged映射调试器，VSCode Cortex-Debug插件通过容器内OpenOCD+GDB调试STM32，避开Windows USB驱动问题

Linux根文件系统高效构建

Dockerfile集成Yocto构建层，VSCode集成终端执行bitbake命令，通过bind mount实时同步构建工件到Windows主机

智能化静态分析

容器内运行Clang-Tidy + AI辅助工，VSCode问题面板实时显示STM32代码的质量警告和优化建议

本文将展示如何基于 VS Code + ESP-IDF 扩展 + ESP-IDF Docker 镜像 来开发项目。

一、开发环境搭建

在开始项目之前，请安装以下工具：

Windows WSL（安装步骤如下）

Visual Studio Code

usbipd-win

Docker 桌面应用程序（适用于 Windows 系统）

其他工具在项目的 Dockerfile 中定义，且会包含在容器中。

在 Windows 系统中为 Docker 安装 Ubuntu

如果未安装 WSL，请运行：

wsl --install

使用以下命令更新 WSL 内核：

wsl --update

使用 Powershell 命令提示符查看可用 WSL 发行版列表：

wsl -l -o

若想在 Windows 上的 WSL 中安装 Ubuntu 发行版，请输入以下命令：

wsl --install --distribution Ubuntu

检查 Windows 上的 WSL Ubuntu 以用于 Docker

检查当前 WSL 版本是否为 2。 wsl -l -v

如果 WSL 版本落后，请升级到版本 2。 wsl --set-version Ubuntu 2

将 Ubuntu 发行版设置为默认使用的操作系统。 wsl -s Ubuntu

最后，使用 wsl --status 命令检查上述所有指令是否生效。

适用于 Windows 系统的 Docker 桌面应用程序

在 macOS 和 Windows 主机上都可以使用 Docker 桌面应用程序构建和共享容器化应用程序。详情请参阅 Docker 快速入门文档。注意，此处 Docker 的作用是导入 ESP-IDF Docker 镜像 并对其进行启动、重启、关闭等管理操作。

将 Ubuntu 发行版更新到版本 2 之后，需要在 Docker 中进行一定调整，将 Ubuntu 设为默认的 WSL 集成。

Docker 中的 `usbipd-win`

必须安装 usbipd-win，才能访问来自本地 Windows 的 USB 设备、串口设备以及 JTAG 设备，否则无法在 IDF Docker 镜像中进行下载、监控和调试。安装方式与其他 Windows 应用程序相同，这里不再赘述。

安装好上述所有必要工具后，请继续进行下列配置。

在 PowerShell 命令提示符中安装 usbipd。

配置 USB 串口设备，通过 usbipd 连接到 WSL

以管理员权限打开 PowerShell 命令提示符，输入下列指令，获取 USB 串口设备列表。

要从 Windows 本地访问 WSL 上的指定设备，必须使用 usbipd 绑定设备。

⚠️

除非重启计算机，否则此命令只需使用一次。1-1 是想要绑定的设备的 <BUSID>。

绑定后，请在 PowerShell 命令提示符中使用下列指令将指定设备附加到 WSL 中。

最后，通过在 WSL 环境中输入下列指令，验证连接是否成功。

felix@Home-WorkStation:~$ dmesg | tail [43766.535973] usb 1-1: SetAddress Request (2) to port 0 [43766.600256] usb 1-1: New USB device found, idVendor=10c4, idProduct=ea60, bcdDevice= 1.00 [43766.600260] usb 1-1: New USB device strings: Mfr=1, Product=2, SerialNumber=3 [43766.600261] usb 1-1: Product: CP2102 USB to UART Bridge Controller [43766.600262] usb 1-1: Manufacturer: Silicon Labs [43766.600263] usb 1-1: SerialNumber: 0001 [43766.626814] usbcore: registered new interface driver cp210x [43766.626823] usbserial: USB Serial support registered for cp210x [43766.626831] cp210x 1-1:1.0: cp210x converter detected [43766.628590] usb 1-1: cp210x converter now attached to ttyUSB0

如上所示，1-1 设备已附加到 ttyUSB0，WSL 现在可以访问 1-1 USB 设备。

二、在 Visual Studio Code 中安装远程容器扩展

安装下图中的 Dev Containers、Remote Development 和 ESP-IDF 扩展。

三、构建、烧录和调试

完成上述所有步骤后，就可以使用 WSL 或 Docker 容器。下文将展示如何利用这些工具。

使用 Docker 容器的示例项目

以 Blink 和 Hello_world 项目为例，你可以将多个示例项目放在同一文件夹中并一起挂载到 IDF Docker 镜像中。若为每个示例项目都单独创建容器，则将占用过多磁盘空间。

如图所示，Blink 和 Hello_world 示例项目已放在同一文件夹中，请用 VS Code 打开此文件夹。

注意，在 example_project 文件夹中有一个 .devcontainer 文件夹，这并非默认包含，而是使用 VS Code 中的 ESP-IDF 扩展创建和配置 ESP-IDF Docker 镜像进行容器开发时生成的。

参照下列步骤，可以生成 .devcontainer 文件夹：

用 VS Code 打开示例项目，在菜单栏选择 查看 > 命令面板。

在弹出的对话框中，搜索 ESP-IDF：添加 Docker 容器配置。

当前项目的 .devcontainer 文件夹将自动生成。

更多有关 devcontainer.json 的信息，请参阅注释。

至此，已完成所有相关配置。通过以上配置，无需VSCODE连接到容器后，继续将VS Code 扩展和插件安装到容器中。而是自动完成。

创建容器

单击 VS Code 左下角的 >< 按钮并选择 在容器中打开文件夹，创建容器并开始开发。

⚠️

备注首次在容器中打开文件夹耗时较长，因为需要下载 ESP-IDF 的 Docker 镜像。

打开 Blink 示例项目。如果需要切换到其他项目，只需将路径从 "workspaceFolder": "/workspaces/blink" 更改为 "workspaceFolder": "/workspaces/<ProjectName>" （<ProjectName> 即想要打开的文件的名称），然后重新选择 在容器中打开文件夹。

此时，可以开始使用 Blink 示例项目进行构建、烧录、监视、调试等操作。

⚠️

警告为了从 Docker 容器访问串口，请确保在 VS Code 中打开文件夹之前已使用 usbipd attach --wsl --busid <BUSID> --auto-attach 命令附加设备，否则设备将不可见。如果希望插拔设备后仍能在 Docker 容器中识别到设备，请务必加上 --auto-attach 参数。