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？

ESP-IDF（Espressif IoT 开发框架）是 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 仪表板

     1. 点击设备的三点菜单
     2. 选择”清理构建文件”

5. 编译和测试：编译你的配置并进行全面测试：

   • 使用 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 替代方案或原生 ESP-IDF 支持：

• heatpumpir - 基于红外线的热泵控制
• midea - 美的空调控制
• WLED 效果 - WLED UDP 实时控制集成

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

NOTE

组件兼容性在持续改进中。请查看组件文档 或尝试使用 ESP-IDF 编译，以查看是否有替代方案可用。

故障排除

编译错误

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

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

构建时间

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

性能考量

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

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

常见问题

问：Arduino 框架会被移除吗？ 答：不会，Arduino 框架将继续得到支持。只是默认值发生了变化。

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

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

问：我现有的设备会受到影响吗？ 答：仅在你重新编译时才会受影响。已经运行的设备将继续正常工作。

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

获取帮助

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

1. 查看 ESPHome Discord 获取社区支持
2. 查看组件特定的文档
3. 搜索现有的 GitHub 问题
4. 如果发现错误，请创建一个新问题

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

参见

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