前言
本文是我刚开始接触ESP32开发板的第一篇文章，因为以前的工作都是在一个集成的IDE中编辑、编译、调试等等。但ESP32的开发最好方法是VS Code + ESP-IDF 扩展 的方式开发，本文就以纯新手角度来创建一个模板工程。
一、 VS Code
VS Code（Visual Studio Code）是由微软开发的免费、开源的轻量级代码编辑器，支持跨平台使用（Windows、macOS、Linux）。它集成了调试、语法高亮、智能代码补全、Git版本控制等功能，并通过扩展插件支持多种编程语言和框架。
也就是说VS Code是众多语言的一个专门的编辑器，因为够专一，所以比一些IDE里自带的编辑器的功能要强大太多。
对于VS Code的安装可以参考《VSCode安装配置使用教程（最新版超详细保姆级含插件）一文就够了》
该博主写的非常详细，我也是安装这个教程安装的。
接下来安装插件，这里只介绍使用ESP32需要的插件。
1. ESP-IDF（官方核心插件）
-
开发者：Espressif Systems（乐鑫官方）
-
核心作用：这是进行 ESP32 开发的必备核心插件，提供了一站式开发环境。
- 自动配置 ESP-IDF 开发环境（工具链、Python、环境变量等）。
- 提供图形化界面，支持一键创建项目、编译、烧录、串口监控和硬件调试。
- 集成了
menuconfig可视化配置、代码补全、错误检查等功能。
-
必要性： 必须安装。没有它，在 VS Code 中进行 ESP-IDF 开发会非常困难。
2. ESP-IDF WEB（官方 Web 扩展）
-
开发者：Espressif Systems（乐鑫官方）
-
核心作用：这是一个功能补充插件，专为 Web 环境设计。
- 支持在 VS Code Web 或 GitHub Codespaces 等浏览器环境中，通过 WebSerial/WebUSB 技术对 ESP32 进行烧录和串口监控。
- 当在 Web 环境中使用 ESP-IDF 插件时，它会自动接管
flash和monitor命令。
-
必要性： 非必需。如果你是在本地桌面版 VS Code 中进行开发，完全不需要安装它。
其他插件都是社区第三方开发插件，都不建议安装。
编辑
二、 ESP-IDF
ESP-IDF（Espressif IoT Development Framework）是乐鑫（Espressif Systems）官方提供的物联网开发框架，专为ESP32、ESP32-S和ESP32-C系列芯片设计。它提供了一套完整的工具链、库和API，支持开发者快速构建基于Wi-Fi、蓝牙、低功耗等功能的嵌入式应用。
它基于 C/C++ 语言，提供了完整的软件开发工具链，包括编译器、调试器、烧录工具等，让开发者能够充分发挥 ESP32 系列芯片的强大功能。
也就是说VS Code + ESP-IDF等于我们之前熟悉的一体化IDE，如keil、PyCharm。
安装教程可以参考微雪官方的一个教程《docs.waveshare.net/ESP32-ESP-I…》
不过我要做几点补充说明：
按官方的解释我会收到ESP-IDF 离线整合包(.zst) ，和ESP-IDF 安装器(.exe) 。但按教程的下载安装只有离线整合包 ， 没有安装器，安装器到该页面自行下载。
编辑
按教程安装完ESP-IDF后会在路径下多出文件V5.5.3，另外C盘自动多出文件Espressif。 Espressif是 ESP-IDF 离线安装的核心文件存储目录，没有它你根本无法编译、烧录、调试 ESP32-P4 项目。.V5.5.3是 ESP-IDF 为你的开发环境做的 “桥梁配置”，核心作用是 “链接”。相当于 “导航文件”：让你的项目、开发工具（VS Code/ESP-IDF 终端）不用记住复杂的 C 盘路径，只需读这个目录的配置，就能找到核心资源。
三、新建工程
完成了上述操作，代表开发环境已经搭建完成了，此时可以运行官方示例教程来判断感受一下
比如微雪官方的《docs.waveshare.net/ESP32-ESP-I…》
在完成这些我们来创建一个工程模板，先参考微雪官方该示例的前两步《docs.waveshare.net/ESP32-ESP-I…》创建一个空白项目。
首先打开 SDK 配置编辑器，搜索chip，在这确认一下自己的芯片版本是不是和配置的一致，我的版本是1.3，所以选Rev v1.0，范围为1.0~1.99，满足要求。
编辑
接着搜索JTAG，将控制台输出通道选择USB 串口/JTAG 控制器，这是因为一般出厂时，开发板的调试接口JTAG的原生接口不使用，而用可用 USB 串口/JTAG 控制器的 USB1P1_N/P 功能代替，我们这里将控制台输出通道也选择这个接口，这个接口就具有烧录、调试、访问、交互等功能为一体了，方便使用。
编辑
接着搜索flash，在flash size中按自己开发板实际大小选择。设置完这些后保存。
编辑
我们工程中会自行添加.c 和.h文件，在以前IDE的开发习惯中，需要.h文件目录加到工程环境目录中才行。但我们使用的是VS Code + ESP-IDF 。 这不是一个完整的IDE，相互之间耦合没那么高，所以自行添加的.h文件需要在VS Code和ESP-IDF都添加一遍。 这也是问题最多的地方。
如果只在VS Code中添加，将会发生程序不报错，但构建失败，程序无法下载；如果只在VESP-IDF中添加，将会发生程序报错，但构建成功，程序正常下载；
下面我就来演示如何在两者全部成功添加
3.1 VS Code中C++编辑配置
在VScode界面按F1，找到C++编辑配置，打开如下。此处配置的内容同步到.vscode文件夹下的c_cpp_properties.json，也可以直接在该文件中修改。
编辑
编译器路径：
判断自己芯片的架构，选择对应的编译器。以下是常见的一些，默认的编译器可能选择错误，按照对应路径格式找到正确的就行。
编辑
IntelliSense 模式：
优先选择与你主机架构匹配的 GCC 模式，因为 ESP-IDF 使用的是 GCC 编译器，IntelliSense 需要模拟 GCC 的行为来分析代码。
- Windows 系统
**windows-gcc-x64**这是最标准的选择，明确指定了在 Windows 下使用 GCC 编译器，且主机架构为 x64（绝大多数开发 PC 都是这个架构）。
- macOS 系统
- Intel 芯片 Mac：
macos-gcc-x64 - Apple Silicon (M1/M2/M3) Mac：
macos-gcc-arm64
- Linux 系统
- x86_64 架构主机：
linux-gcc-x64 - ARM64 架构主机（如 Raspberry Pi）：
linux-gcc-arm64
避免选择 MSVC 和Clang相关选项，MSVC 是微软的 Visual Studio 编译器，与 ESP-IDF 使用的 GCC 编译器行为差异巨大，会导致大量代码误报和智能提示失效。Clang 是另一种编译器前端，虽然语法兼容 GCC，但在宏定义、内置函数等细节上仍有差异，可能导致 ESP-IDF 特有的代码解析不准确。
包含路径：
编辑
${workspaceFolder}/**
${workspaceFolder}是VS Code 内置变量，代表你当前打开的 ESP32 项目根目录，/** 表示「递归匹配当前目录下所有层级的文件 / 文件夹」（包括 main/、components/、include/ 等子目录）
作用是让 VS Code 的 C/C++ 插件（IntelliSense）递归扫描你项目根目录下的所有文件和子目录，确保能找到你自己编写的代码、头文件、自定义组件等。
添加E://esp/v5.5.3/esp-idf/components/**** ，这里有些人会建议添加 ${IDF_PATH}/components/， 理论上这两个没区别。
作用是让 VS Code 的 C/C++ 插件（IntelliSense）递归扫描 ESP-IDF 框架内置组件目录下的所有文件和子目录，确保能找到 WiFi、蓝牙、外设驱动、FreeRTOS 等官方核心组件的头文件
IDF_PATH是由 ESP‑IDF 工具链在终端会话内临时 / 动态设置的一个路径，我们点击下方的打开ESP-IDF终端，可以看到IDF_PATH的路径。 我之所以把这里设置为绝对路径是因为发现，vscode会经常报错找不到路径 ${IDF_PATH}/components/， 这也是正常的，因为这个路径定义在编译器中， 编辑器自然找不到，但是不影响编译烧录。并且编译工程后编辑器能在build文件中找到这个绝对路径，从而消除错误警告。
编辑
选择绝对路径的好处是不编译工程，打开也不报错，但其他人使用需要重新配置路径。
选择绝对路径的好处是工程统一，任何人都能直接烧录，但编辑器会经常报错。
具体看大家抉择。
C 标准选C17是最稳妥的选择，既兼容旧代码，也支持新特性。
C++ 标准选C20， 能解锁更多现代 C++ 特性，同时兼容项目中可能的 C++17 代码。
合并配置
建议勾选
编辑
不勾选：你手动在 c_cpp_properties.json 中写的 includePath、defines 等配置，会完全覆盖 ESP-IDF 插件等配置提供程序自动生成的配置。这意味着如果你的手动配置不完整，就会丢失关键路径，导致 IntelliSense 报错。
勾选：你手动写的配置会和 ESP-IDF 插件等提供的配置合并。插件自动生成的路径（如 ${IDF_PATH}/components/**）会被保留，同时你手动添加的路径（如自定义组件目录）也会生效，两者取并集
浏览路径
编辑
VS Code 用来建立全局符号索引的路径列表。它决定了在使用「转到定义」「查找所有引用」等功能时，插件会在哪些目录里递归扫描代码文件。
保持和包含路径一致即可，注意这里的递归搜寻写法不同，要更改过来
完成以上这些VSCode这个编辑器中的所有头文件路径应该是全都包含了。
编译，应该不会报错。
3.2 ESP_IDF头文件设置
打开main文件夹下的CMakeLists.txt
编辑
这行代码是 ESP-IDF 构建系统（基于 CMake）中最核心的组件注册指令，用于告诉 ESP-IDF 如何构建你的自定义组件。
idf_component_register : ESP-IDF 组件注册宏（必须），所有自定义组件的 CMakeLists.txt 都需要用它声明组件信息
SRCS "b.c" "a.c" "main.c" : 指定组件的源文件（Source Files），有下级目录则路径需要包括，如（SRCS "file1.c" "file2.c" "src/sub/file3.c"）
INCLUDE_DIRS "." ： 指定组件的头文件包含目录， . 代表当前目录（CMakeLists.txt 所在目录），让编译器能找到该目录下的 .h 文件。有多个路径可以写成（INCLUDE_DIRS "." "include" "src/include"）
按照官方文档，想要在一个组件中应用官方组件，除了使用#include添加头文档，还要在该组件下的CMakeLists.txt文件添加组件依赖。如下图所示：
编辑
添加依赖有两种方式，REQUIRES 是公开依赖，依赖会被传递；PRIV_REQUIRES 是私有依赖，依赖截止，不传递。
REQUIRES：如果 A REQUIRES B，那么任何依赖 A 的组件 C，也会自动拥有 B 的头文件和库链接。
PRIV_REQUIRES：如果 A PRIV_REQUIRES B，那么依赖 A 的组件 C，看不到 B 的头文件，也不会链接 B。
如果你的组件头文件里定义了结构体或函数，里面包含了 gpio 的结构体，其他组件包含你的头文件时也需要用到 gpio 。这时就得用REQUIRES。
如果你的组件头文件是纯公开接口（不包含任何 gpio 类型），所有 gpio 操作都只在 .c 文件内部实现。此时用PRIV_REQUIRES。
如果想自定义一个组件，可以在ESP命令下选择创建ESP-IDF组件。
编辑
只有自行创建的组件中需要用到系统组件需要自行使用命令REQUIRES 添加，其他情况下CMakeLists.txt不需要我们自己去修改，构建时系统自动修改。
到此工程模板创建完成，后面不用再重新创建工程，复制自己的模板，重命名即可。
3.3 添加控制台组件
具体内容见《ESP-IDF+vscode开发ESP32第二讲——console》此章内容会讲述ESP-IDF 采用组件化设计，这是非常重要的一个功能。建议阅读
四、提升速度
听过开启CCache能加快构建速度。
在扩展中找到ESP-IDF，右键——设置，勾选Enable C Cache
编辑
工程下载：
（因为工程不断完善，可能多一些自定义组件，忽略即可）
