ESP-IDF 安装与部署

二、安装与部署

ESP-IDF 的安装有两种主流方式：官方安装器/脚本，以及在 VSCode 里用官方扩展。国内网络环境下最常见的问题是依赖下载慢或中断，因此下面的步骤里包含配置镜像的操作。

1. 确认系统依赖。Windows 需要 Git、Python、CMake、Ninja 等（安装器会自动处理）；Linux/macOS 需要先用包管理器装好这些基础工具。
2. 获取 ESP-IDF 源码。用 git clone 并加上递归参数拉取子模块；或者用官方安装器一键部署。指定一个稳定的发布分支，不要长期用开发分支。
3. 运行安装脚本。Windows 是 install.bat，Linux/macOS 是 install.sh，它会创建 Python 虚拟环境、装 Python 依赖、下载交叉编译工具链。
4. 激活环境。每次开新终端都要执行导出脚本（Windows 是 export.bat，Linux/macOS 是 source export.sh），激活后才能使用 idf.py。
5. 验证安装。运行 idf.py --version，再创建一个官方示例工程编译一次。
6. 装串口驱动。开发板的 USB 转串口芯片常见有 CP210x、CH34x 等，Windows 需要装对应驱动；Linux 下把当前用户加入 dialout 组以免每次都要 sudo。
7. 设置目标芯片。idf.py set-target esp32s3 之类，这条命令会重置 sdkconfig，务必在建工程初期就设好，中途切换会丢失配置。
8. 配置、编译、烧录、监控。标准四步走：menuconfig → build → flash → monitor。

# 1) Linux / macOS 安装
mkdir -p ~/esp && cd ~/esp
git clone -b <稳定发布分支> --recursive https://github.com/espressif/esp-idf.git
cd esp-idf
./install.sh all          # 只装某个芯片可改成 ./install.sh esp32s3

# 2) 激活环境（每次新开终端都要做）
source ~/esp/esp-idf/export.sh

# 国内网络下载慢时，可在 install.sh 之前设置镜像相关环境变量，
# 具体的镜像地址与变量名以乐鑫官方文档的说明为准

# 3) 验证
idf.py --version

# 4) 建工程并跑通
cp -r $IDF_PATH/examples/get-started/hello_world ~/esp/hello_world
cd ~/esp/hello_world
idf.py set-target esp32s3        # 按你的实际芯片选
idf.py menuconfig                # 可选，配置工程
idf.py build
idf.py -p <串口设备> flash monitor
# 退出 monitor：Ctrl + ]

# Windows（PowerShell / cmd）大致对应：
#   install.bat
#   export.bat
#   idf.py set-target esp32s3
#   idf.py -p COM5 flash monitor

依赖与环境要求

• Python：官方要求的版本范围，由安装脚本自动创建虚拟环境，切勿用系统 Python 裸装依赖。
• 构建工具：CMake 与 Ninja（安装脚本会一并处理）。
• 交叉工具链：不同芯片架构对应的工具链不同（Xtensa 与 RISC-V），安装脚本按目标下载。
• 串口驱动：CP210x / CH34x / FTDI 等，按开发板实际芯片安装。
• 磁盘：工具链与构建产物占用可观，建议预留充足空间。
• 权限：Linux 下需要串口访问权限，否则 flash 会报设备打不开。

常见报错与排查