我是如何从零开始，把 ESP32-S3 跑起来的

作为一个刚入门的时候，我是如何入门 ESP32-S3 的

一、从"我也只是个刚入门的时候"说起

说实话，写这篇文章的时候，我自己也并不是什么"老工程师"。我刚开始接触 ESP32 的时候，心里其实是有点发虚的：

• 芯片型号一大堆，看不懂怎么选
• 文档、示例很多，但不知道从哪下手
• 别人一上来就 Wi-Fi、BLE、LVGL，我连环境都没搭好

后来在项目中，我最终选择了 ESP32-S3，并且花了一段时间，把从环境搭建到第一个工程完整跑通。回过头看，这条路径对我来说，其实是可以被清晰总结出来的。

于是就有了这篇文章------站在一个刚入门的时候的视角，记录我第一次上手 ESP32-S3 的全过程。

---

二、ESP32 到底是什么？刚入门的时候第一步要搞清楚的事

刚接触 ESP32 时，一开始我最大的误区是：

把它当成一颗"性能强一点的单片机"。

真正上手后才发现，ESP32 更准确的定位其实是：一颗高度集成的 SoC。

对我来说，可以先抓住几个最核心的点：

• 芯片内部集成了 Wi-Fi + Bluetooth（BLE）
• 主频高，资源多，但也更复杂
• 默认运行 FreeRTOS，不是传统裸机

也正因为这些特性，ESP32 的学习方式，和以前学 51、STM32 裸机是完全不一样的。如果一开始不转变思路，很容易被劝退。

---

三、为什么我最后选了 ESP32-S3？

日常生活中，说起ESP32时，我们一般说的是下方形态的模组。但准确点来说，ESP32其实不是一款芯片，而是一个系列的芯片，这个和STM32有点类型，STM32有L系列、F系列、H系列，ESP32也有不同的系列。

那ESP32有那些系列呢？

https://www.espressif.com.cn/zh-hans/products/socs

对比总结：

在真正开始动手前：ESP32、C3、S2、S3 到底怎么选？

选择建议

• ESP32-P 系列：适合需要高性能计算和丰富外设的应用，如工业控制、智能家居中枢。
• ESP32-H 系列：适合低功耗、低成本的应用，如智能农业、环境监测。
• ESP32-S 系列：适合需要 Wi-Fi、蓝牙和 AI 功能的应用，如智能音箱、可穿戴设备。
• ESP32-C 系列：适合成本敏感的应用，如智能插座、简单传感器。

最终我用的是 ESP32-S3原因有三。

1. 官方主推，资料新：
   ESP32-S3 是目前乐鑫重点维护的型号之一，文档、示例、更新频率都比较友好，对我来说不容易踩到"过时坑"。
2. 原生 USB，上手成本低：
   ESP32-S3 自带 USB OTG，很多开发板可以直接 USB 下载程序，不用额外折腾串口芯片和驱动问题。
   这一点对我这种刚入门的人来说，真的省了不少时间。
3. 能力上限高，但起步不难
   它既能点灯、打日志，也能往后做 Wi-Fi、BLE、显示、音频，学习投入不会白费。

---

四、刚入门的时候最容易踩的坑：一上来就写代码

刚开始的时候，我也犯过一个典型的新手错误：

环境还没完全跑通，就急着新建工程写代码。

结果就是各种奇怪的问题：

• 编译报错，不知道是代码问题还是环境问题
• 烧录失败，不确定是串口、驱动还是芯片问题

后来我才意识到，对我来说，第一步不是写代码，而是搭建环境、验证环境。

---

五、开始动手：搭建ESP32-S3的开发环境

在真正开始搭 ESP32 的开发环境之前，我其实是有点抗拒的。

原因很简单：以前 ESP32 的环境搭建，是真的折磨人。早些年乐鑫主要支持的是 Linux 开发环境，搭环境基本意味着：

大量工具、脚本、依赖都托管在 GitHub，包体积很大，国内访问 GitHub 本身就不稳定,网络一抖，下载就失败，经常是折腾一整天，环境还没跑起来，人先被劝退了。

后来我才知道，这件事乐鑫自己也意识到了问题，所以近几年他们做了一个对新人非常友好的改变：

👉 官方提供了 Windows 下的一体化安装包。

为什么选择Windows方式搭建

如果你和我一样，是刚开始接触 ESP32，我非常明确地建议一句话：

优先用 Windows 官方安装包，别一上来就折腾 Linux。

原因很现实：

• Windows 安装包把大多数坑都提前踩掉了
• Python、工具链、CMake、依赖全部打包
• 不需要一边装一边查 GitHub Issue

只有在 Windows 实在安装失败，或者你本身就很熟 Linux 的情况下，再考虑 Linux 环境。

Windows环境搭建（推荐）

5.1 安装包选择

官方下载链接：官网地址

我使用的是 ESP-IDF 5.4 的离线安装包。

之所以选离线版，而不是在线安装，是因为：

• 在线安装下载速度慢
• 网络不稳定时容易失败
• 离线包一次下载，后面省心很多
  

5.2 安装过程（这里有坑，一定注意）

下载安装包到本地后，直接双击运行即可，整体流程并不复杂。

但有几个点，我当时是专门记下来的，不注意很容易导致安装失败：

• 安装路径不能包含中文
• 路径中不能有空格或括号
• 路径长度不要超过 90 个字符
  
  
  如果提示需要修复长路径的，可以点击应用修复，但是最好不安装到长路径中
  
  如果安装过程中提示"需要修复长路径支持"，可以点修复，但最稳妥的方式还是一开始就选短路径。
  
  然后就可以点击下一步，勾选需要安装的芯片包；

5.3 组件选择（别装太多）

安装过程中会让你选择组件，我当时的选择思路是：

够用就行，别贪多。

我只勾选了：

1. 安装命令提示符和桌面快捷方式
2. 安装 ESP32 / ESP32-S3 芯片支持包

这样既能满足当前学习，又能减少磁盘占用。

5.4 安装完成后的验证

安装结束后，我勾选了：

• Run ESP-IDF PowerShell Environment
  

系统会自动打开一个 PowerShell 窗口，并加载 ESP-IDF 环境。当我在窗口里看到 ESP-IDF 的环境信息正常打印时，心里其实松了一口气：

至少，环境这一关是过了。

后续编译、烧录、查看日志，都可以在这个窗口里完成。如果以后需要重新打开，只要在开始菜单里搜索 esp-idf 即可。我个人更习惯用 PowerShell，因为命令补全更友好。

到这里为止，ESP32-S3 的 Windows 开发环境就算是搭建完成了。说实话，这一步是整个入门过程中最容易劝退人的一关，能顺利走完，后面的路会轻松很多。

Linux环境的搭建

Linux 环境我也尝试过，但必须说一句实话：如果你对 Linux 命令行不熟，不建议一开始就用它。

Linux 下的 ESP-IDF 环境：

• 更灵活
• 更贴近底层
• 但问题定位成本也更高

如果你确实需要使用 Linux，建议至少具备基本的命令行操作能力，再去折腾虚拟机、依赖和源码编译。

前提

你需要安装虚拟机，然后 安装Ubuntu系统，我推荐的是ubuntu-18.04.5；因为我使用的是这个镜像，

你需要确保系统的CMake 3.16 、Python 3版本。

使用 ESP-IDF 需要 CMake 3.16 、Python 3以上版本。较早的 Linux 发行版可能需要升级自身的软件源仓库
leo@ubuntu:~/work/esp/demo01$ cmake -version
cmake version 3.16.3
leo@ubuntu:~/work/esp/demo01$ python --version
Python 3.8.10

安装依赖工具

安装完成后，打开命令终端，安装以下工具

sudo apt-get install git wget flex bison gperf python3 python3-pip python3-venv cmake ninja-build ccache libffi-dev libssl-dev dfu-util libusb-1.0-0

安装IDF 5.4

这个安装路径要记录下来，后续会用到相关例程源码

mkdir -p ~/esp
cd ~/esp
git clone -b v5.4 --recursive https://github.com/espressif/esp-idf.git
这一步因为要从外网下载大量代码和组件包，极其容易失败，建议上魔法多尝试，出现问题时自行搜索相关教程安装。如果最终搞不定，建议直接到淘宝找代安装服务。

除了 ESP-IDF 本身，还需要为支持 ESP32-S3 的项目安装 ESP-IDF 使用的各种工具，比如编译器、调试器、Python 包等。

cd ~/esp/esp-idf
export IDF_GITHUB_ASSETS="dl.espressif.cn/github_assets"
./install.sh esp32s3
这一步因为要下载大量代码和组件包，极其容易失败，建议上魔法多尝试，出现问题时自行搜索相关教程安装。如果最终搞不定，建议直接到淘宝找代安装服务。

设置环境变量&验证安装

leo@ubuntu:~/work/esp/demo01$ gedit ~/.bashrc 
alias get_idf='. $HOME/esp/esp-idf/export.sh'

使能环境变量

leo@ubuntu:~/work/esp/demo01$ source ~/.bashrc
leo@ubuntu:~/work/esp/demo01$ getidf
Checking "python3" ...
Python 3.8.10
"python3" has been detected
Activating ESP-IDF 5.4
* Checking python version ... 3.8.10
* Checking python dependencies ... OK
* Deactivating the current ESP-IDF environment (if any) ... OK
* Establishing a new ESP-IDF environment ... OK
* Identifying shell ... bash
* Detecting outdated tools in system ... Found tools that are not used by active ESP-IDF version.
For removing old versions of esp32ulp-elf, openocd-esp32, esp32s2ulp-elf, xtensa-esp32-elf, xtensa-esp32s2-elf, riscv32-esp-elf, xtensa-esp32s3-elf use command 'python /home/leo/work/esp/esp-idf/tools/idf_tools.py uninstall'
To free up even more space, remove installation packages of those tools.
Use option python /home/leo/work/esp/esp-idf/tools/idf_tools.py uninstall --remove-archives.
* Shell completion ... Autocompletion code generated

Done! You can now compile ESP-IDF projects.
Go to the project directory and run:

  idf.py build

一个非常重要的提醒

环境搭建，是后续所有学习内容的基础。不同电脑、系统、权限、网络环境差异都很大，你在搭环境的过程中，遇到奇怪问题是正常的。

这一步我自己的经验是：

• 多看报错信息
• 多用搜索引擎
• 善用 AI 工具辅助排查

不要急躁，ESP32 是一款非常热门的芯片，绝大多数问题，网上都能找到答案。

只要你愿意多花一点耐心，环境这关基本都能过去。

六、第一个成功点：跑通 Hello World

在真正理解 ESP-IDF 之前，我做的第一件"正确的事"，就是跑通官方示例里的 hello_world。

这个示例本身没有任何复杂逻辑，但它一次性帮我验证了：

• ESP-IDF 是否安装正确
• 工具链是否完整
• 编译流程是否正常
• 程序是否真的跑在 ESP32-S3 上

当我在串口里看到 "Hello world!" 输出时，那一刻其实挺踏实的：

至少，这条路是走得通的。

复制官方示例

我们复制xxxx\Espressif\frameworks\esp-idf-v5.4\examples\get-started\hello_world到自己希望编写代码的路径下

xxxx为我们安装IDF的路径

然后我在window开始菜单中搜索，IDF,通过powershell进入此目录。

编译烧录

通过命令进行编译：

//xxxx为你放代码的路径
cd xxxx\app\hello_world
//设置"目标"芯片。
idf.py set-target esp32s3  
//编译，首次编译一般需要几分钟
idf.py build 

编译成功：

接着我们把板卡，通过TypeC线接到电脑，然后就可以访问烧录。电脑USB与核心板USB相连。

注意：此步骤需要接上底板的TypeC线才能查看COM口，我这里是COM4，不同电脑会不一样，根据你自己电脑来。

烧录指令：

//端口修改为自己电脑的端口
idf.py -p COM4 flash monitor
//或者自动寻找端口：
idf.py flash monitor

如果一切顺利，烧录完成后，开发板会复位，应用程序"hello_world"开始运行.

需要退出调试模式，可以按键盘的Ctrl+]，到这里，我们就成功完成工程创建、编译、烧录的全部步骤。

注意

想必你们可能也有些人会遇到这个问题：

PS J:\ESP32_P\app\hello_world> idf.py flash monitor Executing action: flash Serial port COM3 Connecting... COM3 failed to connect: Failed to connect to Espressif device: No serial data received. For troubleshooting steps visit: https://docs.espressif.com/projects/esptool/en/latest/troubleshooting.html No serial ports found. Connect a device, or use '-p PORT' option to set a specific port.

该报错本质上是 PC 端未能在下载模式下与 ESP32-S3 建立串口通信。

1. Failed to connect to Espressif device: No serial data received→ esptool 在握手阶段没有收到 ESP32-S3 的 ROM 下载响应。
2. No serial ports found（出现在后面）→ 要么串口瞬间消失，要么驱动/端口被占用或识别异常。

问题：

未进入下载模式

解决方式

正确进入下载模式的方法：

• BOOT(IO0) 按住不放
• 再按一下 RESET
• 先松 RESET
• 最后松 BOOT
• 再执行：

idf.py flash

如果卡在了

boot:0x0 (DOWNLOAD)
waiting for download

则再摁一下reset按键

---

七、基于示例，新建属于自己的最小工程

在 Hello World 跑通之后，我并没有马上加功能，而是做了一件看起来很"慢"的事：

新建一个只属于我自己的最小工程。

1. 什么叫最小工程？

对我来说，最小工程的意义不在于功能，而在于结构清晰、可控 。

首先，通过观察helloworld工程中的文件结构，了解他们的作用；

├── CMakeLists.txt             //工程构建文件
├── pytest_hello_world.py      //python脚本，用于SDK自动测试的
├── main                       //主代码文件夹
│   ├── CMakeLists.txt         //代码构建文件
│   └── hello_world_main.c     //源码
├── README.md                  //说明文件
├── sdkconfig.ci               //SDK配置文件，新工程内容为空，配置具体芯片型号才生成具体内容

所以看得出来pytest_hello_world.py、README.md、sdkconfig.ci文件，都不是新建工程的必要文件

一个最基本的 ESP-IDF 工程，只需要主代码、工程构建文件，于是我创建了以下文件夹及文件：

01_my_first_project
├── CMakeLists.txt     //工程构建文件
├── main
│   ├── CMakeLists.txt //源码构建文件
│   ├── main.c         //源码文件

CMakeLists.txt

首先，我创建了01_my_first_project文件夹，在文件夹中创建了CMakeLists.txt工程配置文件
CMakeLists.txt

# The following lines of boilerplate have to be in your project's
# CMakeLists in this exact order for cmake to work correctly
cmake_minimum_required(VERSION 3.16)

include($ENV{IDF_PATH}/tools/cmake/project.cmake)
project(01_my_first_project)

其中include命令，用于包含其他 CMake 文件。将 ESP-IDF 的项目配置文件引入到当前项目的 CMake 配置中，使得项目能够利用 ESP-IDF 的强大功能进行开发和构建

2. main.c 里我只做了一件事

在 app_main() 里，我只打印了一行日志。

没有点灯，没有任务，没有网络。

main文件夹

然后我在01_my_first_project中创建main文件夹，用于管理项目源码，main文件夹下创建两个文件CMakeLists.txt与main.c，CMakeLists.txt用于管理源码构建

idf_component_register(SRCS "main.c"
                    INCLUDE_DIRS ".")

main.c

#include <stdio.h>              // 引入标准输入输出库，用于使用 printf 函数
#include "freertos/FreeRTOS.h"  // 引入 FreeRTOS 的核心头文件，提供 FreeRTOS 的基本功能
#include "freertos/task.h"      // 引入 FreeRTOS 的任务管理头文件，提供任务相关的函数（如 vTaskDelay）

void app_main(void)             // ESP-IDF 程序的入口函数，类似于 main 函数
{
    int i = 0;                                  // 定义一个整数变量 i，并初始化为 0，用于计数
    while (1) {                                 // 无限循环，确保程序持续运行
        printf("[%d] Hello world!\n", i);       // 打印带计数的 "Hello world!" 消息，%d 会被变量 i 的值替换
        i++;                                    // 计数器 i 自增 1
        vTaskDelay(5000 / portTICK_PERIOD_MS);  // 延时 5000 毫秒（5 秒）
                                                // portTICK_PERIOD_MS 是 FreeRTOS 的时钟节拍周期（系统计时器的"心跳间隔" 通常为 1 毫秒）
    }
}

最终工程目录如下：

于是我进行烧录编译：

//设置"目标"芯片。设置后会生成对应芯片的sdkconfig和build文件夹
idf.py set-target esp32s3  
//编译，首次编译一般需要几分钟
idf.py build 
//通过TypeC线接上板卡，烧录&调试 COM口改为你自己电脑的
idf.py -p COM4 flash monitor 或 idf.py flash monitor

并成功运行：

至此，我也成功自己独立搭建了一个最小的工程，这是我才真正感觉到

我可以开始可以掌控它了

---

八、回头看，刚入门的时候真正需要的是一条清晰路径

后来我发现，很多刚入门的时候在 ESP32 入门阶段会被劝退，并不是能力问题，而是路径问题。

如果一上来就：

• 学 Wi-Fi 协议
• 看 BLE 协议栈
• 研究 LVGL

很容易迷失。

对我来说，真正有效的顺序是：

环境 → 官方示例 → 最小工程 → 逐步加功能

ESP32-S3 只是工具，而这条路径，才是刚入门的时候最需要的东西。

---

九、写在最后

如果你和我一样，也是刚开始接触 ESP32-S3，希望这篇文章能让你少一点焦虑。

不用急着"学很多"，先把第一步走稳，比什么都重要。

后续我也会继续以一个刚入门的时候的视角，记录 ESP32-S3 的学习和踩坑过程。如果你也在入门阶段，欢迎一起交流。