文档大纲

1. 简介

2. 功能概览

3. 安装与准备工作

4. 项目启动与配置

5. 构建与烧录

6. 监视与调试

7. 其他 IDE 功能

8. 故障排除与常见问题

9. 设置与命令列表

10. WSL 与 Docker 支持

内容条目

1. 简介

• ESP-IDF 扩展简介

• 适用对象与开发环境

• 官方资源与文档链接

2. 功能概览

• 支持的主要功能列表（如构建、烧录、调试、监控等）

• 多项目与多配置管理

• 代码覆盖率、堆跟踪、系统视图跟踪等高级功能

3. 安装与准备工作

• VS Code 扩展安装步骤
• 搜索 ESP-IDF 插件，下载
• 运行命令， ESP-IDF: Configure ESP-IDF Extension
• 配置插件



•  ESP-IDF 工具的位置 (IDF_TOOLS_PATH)，默认情况下在 Windows 系统中为 %USERPROFILE%\.espressif，在macOS/Linux 系统中为 $HOME\.espressif。
• 确保 IDF_TOOLS_PATH 中没有空格，避免出现构建问题。此外，要意 IDF_TOOLS_PATH 与 IDF_PATH 不能在相同目录下。
• macOS/Linux 用户需要选择用于创建 ESP-IDF Python 虚拟环境的 Python 可执行文件。
• 点击 Install 开始下载和安装 ESP-IDF 和 ESP-IDF 工具。

• 删除步骤参考这里

• 环境变量与依赖配置

4. 项目启动与配置

• 新项目向导使用方法
• ESP-IDF：新建项目



• 选择当前使用的乐鑫开发板名称
• 选择设备的串口（下拉菜单中会显示当前连接的串行设备列表），参考 创建串口连接。
• 可以将 ESP-IDF 组件目录 component-dir 导入到新项目中。该组件目录将被复制到新项目的 components 子目录中 (<project-dir>/components/component-dir)。
• 点击 Choose Template 按钮，若想使用例程模板，请在下拉菜单中选择 ESP-IDF。如果想创建一个空白项目，请选择 sample_project 或 template-app。
• 选择想要使用的模板并点击 Create Project Using Template <template-name> 按钮

• 导入现有 ESP-IDF 项目
• 输入 ESP-IDF：导入 ESP-IDF 项目，选择该命令以导入现有的 ESP-IDF 项目。

• 添加 Visual Studio Code 配置文件和 Docker 容器
• 前往VScode菜单栏 文件 > 打开文件夹,打开一个根目录中包含 CMakeLists.txt 文件的文件夹（如 myProject），该文件夹应符合 ESP-IDF 项目结构。
• 可以通过以下方式添加 Visual Studio Code 配置文件 (settings.json, launch.json)：
• 前往菜单栏 查看 > 命令面板。
• 输入 ESP-IDF：添加 VS Code 配置文件夹，并选中该命令。
• 可以通过以下方式在 ESP-IDF Docker 容器中打开项目：
• 前往菜单栏 查看 > 命令面板。
• 输入 ESP-IDF：添加 Docker 容器配置，选中该命令从而将 .devcontainer 目录添加到当前目录下。
• 前往菜单栏 查看 > 命令面板。
• 输入 开发容器: 在容器中打开文件夹 并选中该命令，在由 Dockerfile 创建的容器中打开现有的项目。

• 设置目标设备与 OpenOCD 配置
• 前往菜单栏 查看 > 命令面板 并输入 ESP-IDF：设置乐鑫设备目标，选择目标设备（如 esp32, esp32s2 等）。
• 前往菜单栏 查看 > 命令面板 并输入 ESP-IDF：选择 OpenOCD 开发板配置，选择扩展中 OpenOCD 服务器的配置文件。

• 使用 SDK 配置编辑器（menuconfig）
• 前往菜单栏 查看 > 命令面板 并输入 ESP-IDF：SDK 配置编辑器，开始调整 ESP-IDF 项目设置。

5. 构建与烧录

• 构建项目的操作流程
• 前往菜单栏 查看 > 命令面板 并输入 ESP-IDF：构建项目，点击该命令开始构建项目。

• 构建设置
• idf.cmakeCompilerArgs
• 配置 Ninja 时使用 idf.ninjaArgs 参数
• 完成应用程序构建后，终端中将执行二进制文件大小分析任务，并显示分析结果。可以在 settings.json 中通过 idf.enableSizeTaskAfterBuildTask 配置项启用或禁用此分析任务。

• 烧录项目到设备的步骤
• 选择串口：前往菜单栏 查看 > 命令面板 并输入 ESP-IDF：选择要使用的端口，选中该命令并指定设备的串口。
• 烧录设备：前往菜单栏 查看 > 命令面板 并输入 ESP-IDF：烧录项目，选中该命令以烧录设备。在开始烧录前可以选择 UART、JTAG 或 DFU 串口进行烧录。
• 前往菜单栏 查看 > 命令面板 并输入 ESP-IDF：选择烧录方式，为设备选择合适的烧录方式。该烧录方式将被保存在 idf.flashType 配置设置中。
• 也可以使用以下命令来选择特定的烧录方式进行烧录：

ESP-IDF：通过 UART 接口烧录项目

ESP-IDF：通过 DFU 接口烧录项目 （仅适用于 ESP32-S2 和 ESP32-S3）

ESP-IDF：通过 JTAG 接口烧录项目 （使用 JTAG 和 OpenOCD 进行烧录）

6. 监视与调试

• 监视设备输出
• 前往菜单栏 查看 > 命令面板
• 输入 ESP-IDF：选择要使用的端口，选中该命令并指定设备的串口

• 启动 IDF 监视器
• 前往菜单栏 查看 > 命令面板
• 输入 ESP-IDF：监视设备，选中该命令，开始监视设备

• 调试设备与事后调试（Core Dump/GDB Stub）



1. 首先，OpenOCD 服务器在后台启动。可以点击菜单栏中的 查看 > 输出，并在下拉菜单中选择 ESP-IDF 来查看输出。
默认情况下，OpenOCD 服务器在当前计算机上启动，并通过端口 4444 与 Telnet 通信；端口 6666 用于 TCL 通信；端口 3333 用于 GDB。通过修改 openocd.tcl.host 和 openocd.tcl.port 配置，可以变更以上设置。通过设置 idf.openOcdDebugLevel 参数（范围是 0～4），可以调整 OpenOCD 在 ESP-IDF 输出窗口中显示消息的详细程度。
2. 接下来，Eclipse CDT GDB 适配器 在后台启动，输出显示在 调试控制台 中。该调试适配器将通过启动 GDB 调试会话来连接目标设备。
此适配器是 VS Code、配置的工具链 GDB 以及 OpenOCD 服务器之间的中间桥梁。可参考以下链接，查看 乐鑫芯片调试工作原理，以及 VS Code 如何使用 调试适配器 与不同调试工具进行通信。

• 单元测试与 QEMU 模拟调试

7. 其他 IDE 功能

• CMakeLists 编辑器

• eFuse 查看工具

• NVS 分区编辑器与分区表管理

• 二进制文件大小分析

• 组件管理与 Arduino 组件支持

8. 故障排除与常见问题

• 常见问题解答（FAQs）

• 故障排除流程

• 日志与提示查看器

9. 设置与命令列表

• 主要设置项说明（如 notificationMode、cmakeCompilerArgs、ninjaArgs 等）

• 可用命令总览及其用途

10. WSL 与 Docker 支持

• 在 WSL 环境下的使用说明

• 在 Docker 容器中的开发流程

• 跨平台注意事项