ESP32------开发环境配置（VS Code + ESP-IDF ）

文章目录

前言
[一、ESP32-S3、开发板与 ESP-IDF 的关系](#一、ESP32-S3、开发板与 ESP-IDF 的关系)
[二、为什么选择 ESP32-S3 + VS Code + ESP-IDF](#二、为什么选择 ESP32-S3 + VS Code + ESP-IDF)
三、安装开发工具
- 1、安装VScode
- - [（1）Chinese (Simplified) Language Pack for Visual Studio Code](#（1）Chinese (Simplified) Language Pack for Visual Studio Code)
  - （2）C/C++
  - （3）ESP-IDF
- 2、安装ESP-IDF
- 3、安装git
- - （1）git安装
  - [（2）git 使用](#（2）git 使用)

前言

本专栏将以 ESP32-S3 + VS Code + ESP-IDF 为主要开发组合，记录我从零开始学习嵌入式开发的过程。第一篇文章的目标不是马上完成复杂功能，而是先搭建一套稳定、可复用的开发环境，为后续学习 GPIO、、Wi-Fi、蓝牙、FreeRTOS、多任务以及屏幕、传感器等外设打下基础。

一、ESP32-S3、开发板与 ESP-IDF 的关系

在刚接触 ESP32 时，常常容易把"芯片""开发板"和"开发框架"混为一谈。实际上，它们分别处于不同层次。

1、ESP32-S3：核心芯片

ESP32-S3 是乐鑫推出的一款高性能 Wi-Fi + 蓝牙 SoC（系统级芯片）。它具有双核 Xtensa LX7 处理器、Wi-Fi、Bluetooth LE、丰富的 GPIO，以及 UART、I2C、SPI、ADC、PWM 等常见外设接口，适合用于物联网设备、传感器采集、智能家居、显示终端和轻量级边缘 AI 等场景。

2、ESP32-S3 开发板：方便实验的硬件载体

开发板是围绕 ESP32-S3 芯片设计的一块电路板，通常集成了 USB 接口、供电电路、下载电路、复位按键、Boot 按键以及必要的引脚排针。

例如，一块 ESP32-S3 开发板可能包含：

ESP32-S3 模组或裸芯片；
Type-C 或 Micro-USB 接口；
USB 转串口芯片，或原生 USB 下载接口；
3.3V 电源电路；
BOOT、RESET 按键；
GPIO 扩展引脚；
板载 LED；
部分型号还会集成摄像头接口、屏幕接口、TF 卡接口或以太网接口。

因此，开发板可以理解为"让 ESP32-S3 芯片便于供电、连接电脑、烧录程序和外接模块的实验平台"。不同开发板的 Flash、PSRAM、USB 接口和板载外设可能不同，因此在后续使用 menuconfig 配置 Flash、PSRAM 或外设时，需要以自己手中的实际开发板参数为准。淘宝上卖ESP32开发板的很多，比如正点原子、宸芯等等

ESP32-S3 本身只是芯片。它负责执行程序、控制引脚、处理通信数据，但不能直接方便地插到电脑上进行开发。

ESP-IDF：ESP32 的官方开发框架

ESP-IDF 全称为 Espressif IoT Development Framework，是乐鑫官方提供的 ESP32 系列开发框架。它不仅包含头文件和函数库，还包含编译工具链、构建系统、烧录工具、示例工程、驱动组件和配置工具等。

ESP-IDF 基于 FreeRTOS，支持 C/C++ 开发，并采用 CMake 进行工程构建，内部包含 Wi-Fi、蓝牙、GPIO、UART、SPI、I2C、ADC、NVS、文件系统、网络协议栈等丰富组件。

二、为什么选择 ESP32-S3 + VS Code + ESP-IDF

选择这套组合，是为了从一开始就使用更接近实际项目的开发方式，同时借助 AI 提高学习和排错效率。

ESP32-S3 功能丰富：支持 Wi-Fi、蓝牙和多种外设接口，适合后续学习传感器、屏幕、网络通信等内容，另一个方面很大方面是我买的开发板上的芯片是SP32-S3。
ESP-IDF是官方框架：可以更完整地使用 ESP32-S3 的功能，并学习 FreeRTOS、Wi-Fi、GPIO、I2C、SPI 等核心知识。
VSCode 开发方便：可完成代码编写、工程管理、编译、烧录、串口监视等操作。 VS Code 可通过 Copilot等 AI 功能，适合在学习阶段快速理解陌生代码和定位问题。
适合长期学习：ESP-IDF 使用组件化工程结构，后续项目更容易扩展和维护。

三、安装开发工具

1、安装VScode

可以直接从官网下载https://code.visualstudio.com/，也可以在应用商店里直接下载，这个没什么坑，下载时直接next就行。

安装完后需要安装几个插件：

（1）Chinese (Simplified) Language Pack for Visual Studio Code

简体中文语言包插件，安装后需要重启VScode才会生效。

（2）C/C++

为 C/C++ 提供智能提示、调试和代码浏览功能。

（3）ESP-IDF

这一步是关键，下面一小节单独描述。

2、安装ESP-IDF

（1）打开ESP-IDF安装管理器

安装完后在侧边栏会出现这个标志。

按照下述步骤点击"打开 ESP-IDF安装管理器"后，会弹出" ESP-IDF 安装管理器（ESP-IDF Installation Manager，简称 EIM）"。

点击"开始安装"。

点击后会有以下几个安装方式，本次采用的是"离线安装"，经调研，该安装方式安装成功几率较大，点击"浏览存档文件"需要选择导入的文件，需要到。需要首先将ESP-IDF的安装包下载下来。

（2）下载离线安装包。

点击"Espressif Download Portal"就会跳转到下载ESP-IDF离线安装包的下载界面。

目前ESP-IDF离线安装包也在不断更新，博主目前使用的是ESP-IDF_v5.5.4版本，不同版本操作上可能不才一样，但是代码实现原理上是一样的，5.5.x版本之间差异较小。

提示：本文目标是完成 ESP32-S3 的开发环境安装、创建第一个工程。建议全程使用英文路径，避免中文、空格及特殊符号导致工具链或脚本异常

下载完成后，在"离线安装"里导入已经下载的文件。

选择要安装的路径，单击"开始安装"，安装需要一定时间。

点击"完成安装"。

（3）新建工程测试

安装完成后，在VScode中点击"先项目向导"（图中1），稍等片刻后会弹出选择哪个ESP-IDF版本（图中3），我这里是"使用 ESP-IDF F:\ESP32_IDF\v5.5.4\esp-idf ESP-IDF v5.5.4"，点击选中。

点击后会弹出"新建项目窗口"，按照下图箭头点击"sample_project"，会弹出蓝框"Create project using template sample_project"，然后点击Create project using template sample_project。

点击后会有"新建项目"目录，完成"项目名称"、"项目存放路径"、"选择芯片"。剩下的默认即可，点击Create Project。

再次点击Open Project。

这样便创建好了一个基础工程。

创建好工程以后可以点击"编译"按钮，看能否编译成功。

名称	类型	作用说明	什么情况下用到	重要度
.devcontainer	文件夹	开发容器配置（Docker 相关），用于搭建统一的 ESP-IDF 开发环境	团队协作、需要 Docker 统一环境时；个人开发一般用不到	🔹
.vscode	文件夹	VS Code 编辑器配置，包含头文件路径、调试配置、编译任务等	调整编辑器智能提示、调试配置时；一般自动生成无需手动改	⭐
build	文件夹	编译输出目录（自动生成），存放 .o、.bin、.elf 等所有编译产物	编译后自动生成；出现编译异常时可 Full Clean（彻底清理）删除重建	⭐
main	文件夹	主代码目录，存放 main.c（含程序入口 app_main()）和其 CMakeLists.txt	编写代码时（最常用）	⭐⭐⭐
.clangd	文件	Clangd 语言服务器配置，用于代码补全、跳转、智能提示	使用 Clangd 增强代码提示时；不影响程序运行	🔹
.gitignore	文件	Git 忽略规则，指定哪些文件不纳入版本管理（如 build/）	使用 Git 进行版本管理时	🔹
CMakeLists.txt	文件	顶层构建脚本，检查 CMake 版本、加载 ESP-IDF 构建系统、声明项目名	修改项目名或引入额外组件时；一般无需改动	⭐⭐
sdkconfig	文件	项目配置文件（自动生成），保存所有 menuconfig 设置（Flash 大小、WiFi、蓝牙、日志级别等）	通过 menuconfig 修改配置时自动更新；不建议手动编辑	⭐⭐

3、安装git

（1）git安装

在安装完离线安装包后会生成一个文件夹，在该文件夹中有一个components文件，该components 文件是 ESP-IDF 框架的核心目录，里面存放着乐鑫官方写好的各种功能模块（组件）。每个子文件夹就是一个组件，相当于一个个「现成的轮子」，涵盖了 ESP32 开发所需的绝大部分功能，在代码中 #include 对应头文件即可使用，无需复制到项目里。

如果一不消息修改了里面的文件，怎么恢复原样，这里就不得不提一下Git。

Git 是一款版本控制工具，它能记录项目中每个文件的历史状态。对于 ESP-IDF 来说，使用 Git 有以下好处：

优势	说明
一键还原	误改、误删官方文件后，可一条命令恢复到原始版本
版本管理	可在不同 ESP-IDF 版本（如 v5.5.4、v5.4）之间切换
官方分发方式	ESP-IDF 官方就是通过 Git 仓库发布和更新的
追踪改动	随时查看哪些文件被修改过，做到心中有数

💡 正因为 ESP-IDF 是一个 Git 仓库，所以改错的文件都能被"追溯"并还原。

git的安装过程因为有很多文章都有详细描述，此处就不再赘述，附上一篇参考文章Git安装步骤

（2）git 使用

使用举例：

如果我把components中的esp_driver_gpio文件删掉，此时已将显示出该文件夹内有被修改过的文件（红色感叹号）。

打开components文件，右击鼠标，点击"Open Git Bash here/Git Bash here"。

执行git checkout -- .这会将当前 ESP-IDF 仓库中所有被删除或修改的已追踪文件恢复到当前版本状态，注意标点符号别落下。

ESP-IDF 常用 Git 操作

需求	命令
查看当前状态	`git status`
查看 ESP-IDF 版本	`git describe --tags`
查看最近提交记录	`git log --oneline -n 10`
查看当前分支	`git branch`
查看远程仓库地址	`git remote -v`
查看文件改动内容	`git diff`
拉取远程更新	`git pull`
更新子模块	`git submodule update --init --recursive`
克隆 ESP-IDF（含子模块）	`git clone --recursive https://github.com/espressif/esp-idf.git`
切换指定 ESP-IDF 版本	`git checkout v5.5.4`
切换版本后更新子模块	`git submodule update --init --recursive`
恢复单个误删或误改文件	`git restore 文件路径` 或 `git checkout -- 文件路径`
恢复全部误删或误改文件	`git restore .` 或 `git checkout -- .`
取消暂存单个文件	`git restore --staged 文件路径`
取消全部暂存文件	`git restore --staged .`
强制恢复到当前提交状态	`git reset --hard HEAD`
预览未跟踪文件删除操作	`git clean -fdn`
删除未跟踪文件和目录	`git clean -fd`