ESP32 Arduino 到 ESP-IDF 迁移指南

从 ESPHome 2026.1.0 开始，ESP32 的默认框架将从 Arduino 更改为 ESP-IDF。本指南将帮助您迁移现有配置或做出关于使用哪个框架的明智选择。

ℹ️ Note
此变更仅影响 ESP32、ESP32-S2、ESP32-S3 和 ESP32-C3 系列产品。更新的系列（如 ESP32-C6、ESP32-H2、ESP32-P4 等）默认使用 ESP-IDF，因为它们对 Arduino 的支持有限或没有支持。

变更的原因？

ESP-IDF（Espressif IoT 开发框架）是 ESP32 的官方开发框架。它提供了以下优势：

更小的二进制文件：二进制文件大小最多减少 40%
更好的性能：更优化地针对 ESP32 硬件
定制构建：为您的设备配置专门构建固件
积极开发：所有 ESPHome 开发者都使用并测试 ESP-IDF
最新特性：ESP32 的新特性首先在 ESP-IDF 中提供

权衡

虽然 ESP-IDF 提供了许多好处，但也有一些需要考虑的权衡：

编译时间：初始编译大约需要多 25% 的时间
组件兼容性：某些组件可能需要替换为 ESP-IDF 兼容的替代品
库差异：不会提供 Arduino 特定的库

做出选择

选项 1：迁移到 ESP-IDF（推荐）

在您的 ESP32 配置中添加以下内容：

esp32:
  board: esp32dev  # 您的板类型
  framework:
    type: esp-idf

选项 2：继续使用 Arduino

如果您希望继续使用 Arduino（这将保持支持），请显式指定：

esp32:
  board: esp32dev  # 您的板类型
  framework:
    type: arduino

迁移步骤

备份您的配置：在做出更改之前，始终保留您的工作配置的备份。
检查组件兼容性：当您使用 ESP-IDF 编译时，ESPHome 将自动通知您如果有任何组件不兼容，并建议替代方案。
更新您的配置：添加上述框架规范。
清理构建文件：更改框架后，清理您的构建文件：
- 使用 ESPHome CLI
  esphome clean your-config.yaml
- 使用 ESPHome 仪表板
  1. 点击您的设备的三个点菜单
  2. 选择“清理构建文件”
编译和测试：编译您的配置并进行彻底测试：
- 使用 ESPHome CLI
  esphome compile your-config.yaml esphome upload your-config.yaml
- 使用 ESPHome 仪表板
  1. 点击您的设备的“安装”
  2. 选择您喜欢的上传方法（USB、OTA 等）
  3. 仪表板将自动编译和上传

常见组件替换

迁移到 ESP-IDF 时，您可能需要替换一些组件。ESPHome 在可用时将自动建议替代方案：

具有 ESP-IDF 替代方案的组件：

Arduino 组件	ESP-IDF 替代方案
bme680_bsec	bme68x_bsec2
fastled_clockless	esp32_rmt_led_strip
fastled_spi	spi_led_strip
neopixelbus	esp32_rmt_led_strip

仅限 Arduino 的组件：

以下组件目前需要 Arduino 框架，且还没有 ESP-IDF 替代方案：

ac_dimmer - 交流调光控制
dsmr - 荷兰智能电表集成
heatpumpir - 基于红外线的热泵控制
midea - Midea 空调控制
WLED Effect - WLED UDP 实时控制集成

如果您需要这些组件，您应该继续使用 Arduino 框架。

ℹ️ Note
组件兼容性正在不断改进。检查组件文档或尝试使用 ESP-IDF 编译，看看是否出现了替代方案。

故障排除

编译错误

切换到 ESP-IDF 后如果您遇到编译错误：

检查错误消息中的组件兼容性问题
在错误输出中查找建议的替代方案
清理您的构建文件并重试
检查组件文档中的 ESP-IDF 特定说明

构建时间

ESP-IDF 编译比 Arduino 大约多 25% 的时间：

在现代桌面系统上：增加 15-30 秒的时间
在 Raspberry Pi 5 上：增加 1 分钟的时间
在 Raspberry Pi 4 或更旧的设备上：增加 3-5 分钟的时间
后续构建更快，但仍然按比例较慢
较长的构建时间是由于 ESP-IDF 更全面的优化过程

性能考虑

ESP-IDF 通常提供更好的性能，但：

初始启动时间可能会有所不同
某些时间敏感的操作可能需要调整
WiFi 和蓝牙行为可能有细微差别

常见问题

Q: Arduino 框架会被移除吗？ A: 不会，Arduino 框架将继续得到支持。只有默认设置正在更改。

Q: 我必须立即迁移吗？ A: 不需要，但您应该明确指定您的框架选择，以避免在 2026.1.0 中自动更改。

Q: 如果 ESP-IDF 不适合我，我可以切换回 Arduino 吗？ A: 是的，您可以在任何时候通过更改配置在框架之间切换。

Q: 我现有的设备会受到影响吗？ A: 只有在您重新编译时才会受到影响。已经运行的设备将继续正常工作。

Q: 我如何知道我的设备当前使用的是哪个框架？ A: 检查设备在启动期间的日志输出，或查看您的配置文件。

获取帮助

如果在迁移过程中遇到问题：

检查 ESPHome Discord 获取社区支持
审查特定组件的文档
搜索现有的 GitHub 问题
如果发现错误，请创建新问题

记住，迁移是可选的，并且两个框架都将继续得到支持。选择最适合您需求的选项！