ESP32 Arduino 到 ESP-IDF 迁移指南

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

NOTE

Arduino 框架作为 ESP-IDF 之上的 ESP-IDF 组件构建，在 ESP-IDF 构建系统内提供 Arduino API 兼容性。这意味着 Arduino 构建包含 ESP-IDF 框架和 Arduino 兼容层，导致与原生 ESP-IDF 相比构建时间更长、闪存使用更多、RAM 使用更多。

NOTE

此更改仅影响 ESP32、ESP32-S2、ESP32-S3 和 ESP32-C3 变体。 较新的变体（ESP32-C6、ESP32-H2、ESP32-P4 等）已默认使用 ESP-IDF，因为它们的 Arduino 支持有限或没有。

为什么要更改？

ESP-IDF（Espressif IoT Development Framework）是 ESP32 的官方开发框架。它提供几个优势：

• 更小的二进制文件：二进制大小减少高达 40%
• 更好的性能：针对 ESP32 硬件更优化
• 自定义构建：固件专门为您的设备配置构建
• 活跃开发：所有 ESPHome 开发者都使用 ESP-IDF 进行测试
• 最新功能：新 ESP32 功能首先在 ESP-IDF 中可用

权衡

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

• 组件兼容性：某些组件可能需要替换为 ESP-IDF 兼容的替代品
• 库差异：Arduino 特定的库将不可用

做出选择

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

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

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

选项 2：继续使用 Arduino

如果您希望继续使用 Arduino（将继续支持），请明确指定：

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

迁移步骤

1. 备份您的配置：在进行更改之前，始终保留工作配置的备份。

2. 检查组件兼容性：当您使用 ESP-IDF 编译时，ESPHome 将自动通知您是否有任何组件不兼容并建议替代品。

3. 更新您的配置：添加如上所示的框架规范。

4. 清理构建文件：更改框架后，清理构建文件：

   • 使用 ESPHome CLI

     esphome clean your-config.yaml

   • 使用 ESPHome Dashboard

     1. 点击设备的三点菜单
     2. 选择 “Clean Build Files”

5. 编译并测试：编译您的配置并彻底测试：

   • 使用 ESPHome CLI

     esphome compile your-config.yaml
     esphome upload your-config.yaml

   • 使用 ESPHome Dashboard

     1. 在您的设备上点击 “INSTALL”
     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 替代品或原生 ESP-IDF 支持：

• heatpumpir - 基于 IR 的热泵控制
• midea - 美的空调控制
• WLED Effect - WLED UDP 实时控制集成

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

NOTE

组件兼容性正在不断改进。查看组件文档或尝试使用 ESP-IDF 编译以查看是否有替代品可用。

故障排除

编译错误

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

1. 检查错误消息中的组件兼容性问题
2. 查看错误输出中的建议替代品
3. 清理构建文件并重试
4. 查看组件文档中的 ESP-IDF 特定说明

构建时间

ESP-IDF 和 Arduino 之间的构建时间相当。使用更多 Arduino 特定库的配置可能需要更长时间编译。

性能考虑

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

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

常见问题

问：Arduino 框架会被移除吗？ 答：不会，Arduino 框架将继续被支持。只是默认值正在更改。

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

问：如果 ESP-IDF 不适合我，我可以切换回 Arduino 吗？ 答：可以，您可以随时通过更改配置在框架之间切换。

问：我现有的设备会受影响吗？ 答：仅在您重新编译时。已经运行的设备将继续像以前一样工作。

问：我怎么知道我的设备当前使用的是哪个框架？ 答：检查设备启动时的日志输出，或查看您的配置文件。

获取帮助

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

1. 查看 ESPHome Discord 获取社区支持
2. 查看特定组件的文档
3. 搜索现有的 GitHub issues
4. 如果发现 bug，创建新 issue

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

另见

• ESP32 平台
• 常见问题
• ESP-IDF 文档
• Arduino-ESP32 文档