ESP-IDF 工具链

本页面说明自动 ESP-IDF 管理的工作原理、它在磁盘上存储数据的位置，以及如何通过环境变量自定义它。

概述

使用 ESP-IDF 工具链时（配置中的 esp32.toolchain: esp-idf 或 CLI 参数 --toolchain esp-idf），ESPHome 提供自动框架管理：

ESPHome 将 esp32.framework.version 指定的 ESP-IDF 发布归档文件（默认为推荐版本）下载到 ESPHome 数据目录下按版本命名的文件夹中。
ESPHome 运行 ESP-IDF 工具安装程序（idf_tools.py）来安装所需工具，如 cmake 和 ninja（如果尚未可用）。
ESPHome 为每个 ESP-IDF 版本创建并管理一个专用的 Python 虚拟环境，并将 ESP-IDF Python 依赖项安装到其中。
构建和 ESP-IDF 工具（包括 idf.py 和 esptool）使用此托管环境运行，因此你无需 source export.sh 或设置 IDF_PATH。

NOTE

如果你正在使用 ESP-IDF 工具链并提供了 IDF_PATH 环境变量，ESPHome 将尊重它并使用你现有的 ESP-IDF 安装，而不是管理自己的副本。

存储位置

默认情况下，ESPHome 将其数据目录下的 ESP-IDF 框架和 Python 环境存储：

基础目录：<data_dir>/idf
框架：<data_dir>/idf/frameworks/<version>/
Python 环境：<data_dir>/idf/penvs/<version>/

在典型安装中，<data_dir> 是 ESPHome 数据目录，存储在配置文件旁边的 .esphome 文件夹中。

你可以使用 ESPHOME_ESP_IDF_PREFIX 环境变量覆盖基础目录：

export ESPHOME_ESP_IDF_PREFIX="/opt/esphome-esp-idf"

默认 ESP-IDF 功能

ESPHome 在需要自动安装框架时选择默认的 ESP-IDF 功能集：

默认目标：ESPHOME_IDF_DEFAULT_TARGETS（默认为 all）。
默认工具：ESPHOME_IDF_DEFAULT_TOOLS（默认为 cmake;ninja）。
即使系统上已存在也必须安装的工具：ESPHOME_IDF_DEFAULT_TOOLS_FORCE（默认为 required）。
默认 Python 需求功能集：ESPHOME_IDF_DEFAULT_FEATURES（默认为 core）。

所有这些值都可以通过环境变量进行自定义，适用时使用分号分隔的列表：

# 仅为特定目标安装工具
export ESPHOME_IDF_DEFAULT_TARGETS="esp32s2;esp32c3"

# 强制安装额外工具
export ESPHOME_IDF_DEFAULT_TOOLS="cmake;ninja;openocd"

# 控制安装哪些需求集
export ESPHOME_IDF_DEFAULT_FEATURES="core;gdbgui"

当未提供显式工具列表时，ESPHome 通过合并 ESPHOME_IDF_DEFAULT_TOOLS 和 ESPHOME_IDF_DEFAULT_TOOLS_FORCE 来确定要安装哪些工具，然后跳过系统中已可用的工具——除非它们被列为”强制”。

下载镜像

ESPHome 从可配置的镜像 URL 下载 ESP-IDF 框架及其 Python 约束文件。

框架归档

框架归档从 ESPHOME_IDF_FRAMEWORK_MIRRORS 中的 URL 列表下载。

默认值为：

https://github.com/espressif/esp-idf/releases/download/v{VERSION}/esp-idf-v{VERSION}.zip

{VERSION} 占位符将被替换为 ESP-IDF 版本（例如 5.5.2）。

你可以提供多个镜像，用分号分隔；ESPHome 将按顺序尝试每个镜像，直到下载成功：

export ESPHOME_IDF_FRAMEWORK_MIRRORS="\
https://my.local.mirror/esp-idf-v{VERSION}.zip;\
https://github.com/espressif/esp-idf/releases/download/v{VERSION}/esp-idf-v{VERSION}.zip"

Python 约束文件

ESPHome 还会下载 ESP-IDF Python 约束文件，以确保 Python 环境使用的版本与所选 ESP-IDF 版本兼容。

URL 列表由 ESP_IDF_CONSTRAINTS_MIRRORS 配置，默认为：

https://dl.espressif.com/dl/esp-idf/espidf.constraints.v{VERSION}.txt

{VERSION} 占位符将被替换为已安装框架中检测到的 ESP-IDF 框架版本。

你可以提供多个镜像，用分号分隔；ESPHome 将按顺序尝试每个镜像，直到下载成功：

export ESP_IDF_CONSTRAINTS_MIRRORS="\
https://my.local.mirror/espidf.constraints.v{VERSION}.txt;\
https://dl.espressif.com/dl/esp-idf/espidf.constraints.v{VERSION}.txt"

Python 虚拟环境

对于每个 ESP-IDF 版本，ESPHome 在以下位置创建一个专用的 Python 虚拟环境：

<idf_base>/penvs/<version>/

其中 <idf_base> 是 ESPHome 数据目录或 ESPHOME_ESP_IDF_PREFIX。

该过程：

使用主机 Python 解释器创建虚拟环境。
下载该确切 ESP-IDF 版本的 ESP-IDF Python 约束文件。
使用这些约束在环境中升级 pip 和 setuptools。
从 tools/requirements/requirements.<feature>.txt 为每个配置的功能（core、gdbgui、ci 等）安装 ESP-IDF 需求。

为避免不必要的重新安装，ESPHome 为每个虚拟环境保留一个标记文件，跟踪：

ESPHome 内部的 ESP-IDF 管理版本。
框架的 ESP-IDF 版本。
用于创建环境的 Python 解释器版本。

如果标记文件与预期值匹配，ESPHome 会重用现有的虚拟环境；否则它会删除并重新创建它。

用于构建和工具的环境

当 ESPHome 需要运行 ESP-IDF 工具时，它会：

确保请求版本的 ESP-IDF 框架和 Python 环境已安装。
构建一个环境字典，包含：
- IDF_TOOLS_PATH 指向 ESPHome ESP-IDF 工具目录。
- IDF_PATH 指向选定的 ESP-IDF 框架目录。
- ESP_IDF_VERSION 设置为框架版本。
- IDF_PYTHON_ENV_PATH 指向虚拟环境目录。
修改 PATH，使 python 解析为托管环境的解释器。
添加 ESP-IDF export 逻辑返回的所需工具路径和变量。

此环境随后用于：

idf.py 命令（例如构建 ESP32 固件时）。
esptool 调用，例如创建 factory.bin 镜像时。
python 执行，使用托管虚拟环境解释器。
cmake 调用（驱动底层的 ninja 构建系统），根据可用性从主机环境或 ESPHome 管理的工具中解析。