📚 课程目录第1章 ESP32开发环境搭建

1. ESP32开发环境搭建：Arduino IDE与ESP-IDF的安装与配置

说实话，每次带新人入门ESP32，我都要先问一句：你之前用过Arduino吗？或者你更习惯用专业IDE？

这个问题很关键。因为ESP32的开发环境，说白了就两条路：一条是Arduino IDE，上手快，适合快速验证想法；另一条是乐鑫官方的ESP-IDF，功能全，适合做产品。我个人习惯是两套都装，各取所长。

这一章，我们就来把这两套环境都搭好，再跑通第一个Hello World程序。嗯，别小看这一步，我见过太多人卡在环境配置上，一卡就是半天。

1.1 开发环境选型对比

先看个表格，把两个环境的核心差异说清楚：

对比项	Arduino IDE	ESP-IDF
上手难度	低，5分钟就能编译	中高，需要配置工具链
编译速度	快，适合小项目	较慢，但工程管理强
API丰富度	基础外设够用	完整，含WiFi/BLE/OTA
调试能力	串口打印为主	支持GDB/OpenOCD
适合场景	原型验证、教学	产品开发、性能优化

你想想看，如果你只是做个温湿度传感器，Arduino IDE完全够用。但如果你要做OTA升级、多任务调度、低功耗管理，那ESP-IDF才是正解。我在项目中遇到过用Arduino IDE做产品，结果OTA功能死活调不通，最后切到ESP-IDF才搞定。

1.2 Arduino IDE安装与ESP32支持

1.2.1 下载与安装

去Arduino官网下载最新版IDE。Windows用户选Windows Win10及以上版本，macOS用户选对应芯片版本。安装过程一路Next就行，没什么坑。

我的习惯：安装路径不要有中文和空格。我之前吃过这个亏，编译时莫名其妙报错，查了半天发现是路径里有中文。

1.2.2 添加ESP32开发板支持

安装完成后，打开Arduino IDE，按以下步骤操作：

点击 文件 → 首选项
在"附加开发板管理器网址"中填入：https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json
点击 工具 → 开发板 → 开发板管理器
搜索 esp32，找到由Espressif Systems发布的版本，点击安装

这个过程会下载约200MB的文件，取决于你的网速。我建议用手机热点试试，有时候公司网络会屏蔽GitHub的raw内容。

注意：安装过程中不要关闭IDE。我曾经手贱关了一次，结果配置文件损坏，只能重装。

1.2.3 选择开发板与端口

安装完成后，在 工具 → 开发板 → ESP32 Arduino 下选择你的板子。常用的有：

ESP32 Dev Module — 通用开发板
NodeMCU-32S — 安信可的经典板型
ESP32-WROOM-DA Module — 双天线版本

然后选择正确的串口。Windows下一般是COM3、COM4之类的，macOS下是 /dev/cu.usbserial-xxxx。如果不确定，拔掉板子看看哪个端口消失，那就是它了。

1.3 ESP-IDF安装与配置

ESP-IDF是乐鑫的官方框架，功能强大，但配置起来确实比Arduino复杂。我建议你按照官方文档一步步来，别跳步骤。

1.3.1 Windows环境安装

乐鑫提供了一个一键安装工具 ESP-IDF Tools Installer，去官网下载即可。它会帮你装好：

Python 3.8+
Git
交叉编译工具链
ESP-IDF本体

安装时选择 v5.1 或 v5.2 版本。我个人推荐v5.1，因为v5.2刚出，有些第三方库还没适配。

1.3.2 macOS/Linux环境安装

用命令行安装更灵活。以macOS为例：

# 安装依赖
brew install cmake ninja dfu-util

# 克隆ESP-IDF
mkdir ~/esp
cd ~/esp
git clone --recursive https://github.com/espressif/esp-idf.git

# 安装工具链
cd ~/esp/esp-idf
./install.sh esp32

这个过程会下载很多包，建议保持网络通畅。我在咖啡店装过一次，WiFi断断续续，结果装了三次才成功。

1.3.3 设置环境变量

每次打开终端都要运行：

source ~/esp/esp-idf/export.sh

为了方便，可以把它加到shell配置文件中：

echo "alias get_idf='source ~/esp/esp-idf/export.sh'" >> ~/.zshrc

这样每次只需要输入 get_idf 就能激活环境。

1.4 第一个Hello World程序

环境搭好了，我们来写第一个程序。先看Arduino IDE版本的，因为它最简单。

1.4.1 Arduino IDE版本

void setup() {
  Serial.begin(115200);
  Serial.println("Hello, ESP32!");
  Serial.println("开发环境搭建成功！");
}

void loop() {
  delay(1000);
  Serial.print(".");
}

上传步骤：

点击 工具 → 开发板，选择 ESP32 Dev Module
选择正确的端口
点击上传按钮（右箭头）
等待编译和上传完成
打开 串口监视器，波特率设为115200

你会看到串口输出 Hello, ESP32!，然后每隔1秒打印一个点。嗯，这就是你的第一个ESP32程序。

  避坑指南：如果上传失败，按住板子上的BOOT键不放，再按一下EN键，然后松开BOOT键。这是ESP32进入下载模式的标准操作。我曾经因为不知道这个操作，折腾了半小时。

1.4.2 ESP-IDF版本

ESP-IDF的项目结构稍微复杂一些，但更规范。先创建一个新项目：

cd ~/esp
cp -r $IDF_PATH/examples/get-started/hello_world my_hello_world
cd my_hello_world

打开 main/hello_world_main.c，核心代码是这样的：

#include <stdio.h>
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "esp_system.h"
#include "esp_spi_flash.h"

void app_main(void)
{
    printf("Hello, ESP-IDF!\n");
    printf("芯片型号: %s\n", CONFIG_IDF_TARGET);
    printf("Flash大小: %d MB\n", spi_flash_get_chip_size() / (1024 * 1024));

    for (int i = 0; i < 10; i++) {
        printf("计数: %d\n", i);
        vTaskDelay(1000 / portTICK_PERIOD_MS);
    }
}

编译和烧录：

idf.py set-target esp32
idf.py menuconfig   # 可以不改配置，直接退出
idf.py build
idf.py -p /dev/cu.usbserial-xxxx flash monitor

idf.py monitor 会自动打开串口监视器，按 Ctrl+] 退出。

1.5 开发环境知识体系

我把这一章的核心知识点整理成了一张图，方便你理解整个环境搭建的逻辑：

1.6 常见问题与解决

环境搭建过程中，有几个问题几乎每个人都会遇到。我列出来，你遇到了直接对照解决：

问题现象	可能原因	解决方法
上传失败：A fatal error occurred	未进入下载模式	按住BOOT + 按EN + 松开BOOT
编译报错：esp32/esp32.h not found	开发板未安装成功	重新运行开发板管理器安装
串口监视器乱码	波特率不匹配	检查代码中Serial.begin()的波特率
ESP-IDF: command not found	未运行export.sh	运行 source export.sh 或 get_idf
烧录时提示权限不足	Linux/macOS串口权限	sudo chmod 666 /dev/ttyUSB0

我的经验：如果你用的是macOS，建议安装CH340/CP2102的驱动。有些便宜的ESP32开发板用的是CH340芯片，macOS不内置驱动。我第一次用Mac开发ESP32时，插上板子没反应，还以为是板子坏了。

好了，到这里你的ESP32开发环境就搭好了。Arduino IDE和ESP-IDF两套环境都跑通了Hello World。接下来你就可以开始真正的外设驱动学习了。记住，环境搭建只是第一步，后面还有更多有趣的东西等着你。