安装环境与第一次烧录

选择一条安装路径

主路径使用 VS Code 的 Espressif ESP-IDF 扩展，选择 ESP-IDF 5.5 系列及 ESP32-S3 目标。扩展界面可能随版本变化，以官方安装说明为准。安装完成后使用扩展提供的 ESP-IDF Terminal，避免系统 Python 和工具链环境混在一起。Windows 使用官方安装器或同一扩展，不要直接照抄 macOS shell 命令。

macOS/Linux 如果选择手动安装，可按下面顺序执行；先按官方页面准备 Git、Python、CMake 等前置依赖。不要同时混装多套然后猜哪套在生效。

mkdir -p ~/esp
cd ~/esp
git clone -b v5.5 --recursive https://github.com/espressif/esp-idf.git
cd esp-idf
./install.sh esp32s3
. ./export.sh
idf.py --version

上面的 v5.5 是固定教学起点；使用 5.5.x 补丁版时记录实际版本。每个新终端都需要激活环境。教程没有替你在电脑上安装工具链。

打开随教程附带的工程

下载 examples.zip 并完整解压。进入 examples/01_hello，而不是 components 目录。该工程的最小结构是：

examples/
  components/lab/       # 后续实验共用的驱动源码
  01_hello/
    CMakeLists.txt
    sdkconfig.defaults
    main/
      CMakeLists.txt
      main.c

# 在已激活的 ESP-IDF 终端中，先 cd 到 01_hello 目录
idf.py set-target esp32s3
idf.py build
# macOS 查端口；Windows 在设备管理器中查看 COM 编号
ls /dev/cu.*
# 把 YOUR_PORT 替换成实际端口，例如 /dev/cu.usbserial-xxxx
idf.py -p YOUR_PORT flash monitor

优先使用板上标识为 USB-to-UART 的接口。不要同时连接两个 USB 供电口。监视器里应每秒出现一次递增数字。退出监视器用 Ctrl+]。占用串口的监视器退出后，其他工具才能可靠打开同一端口。

实验工程 · 01_hello

最小结果是串口每秒输出一次计数。先把这条链路跑通，再接外设。

打开 main.c · 查看公共驱动 lab.c · 下载全部工程

#include "esp_log.h"
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
void app_main(void) {
    for(int n=0;; n++) {
        ESP_LOGI("hello","boot is alive: %d",n);
        vTaskDelay(pdMS_TO_TICKS(1000));
    }
}

本章验收

• 记录 idf.py --version 的输出
• 连续看到 10 条计数日志
• 修改日志文字并重新烧录，确认设备输出已改变