新物先选一个完成物，再安装一套环境
四条路线都能让 ESP32 运行程序，但读者每天面对的工作不同。Arduino 常从一份 C++ sketch 开始，IDF 面向完整项目与系统配置，MicroPython 在设备上的解释器里执行 Python，ESPHome 通过 YAML 描述设备并生成固件。它们没有“全部依次学完”这个统一顺序。
先给这次尝试设一个很小的验收点：在串口看到自己改过的版本标记、在 hello_world 工程重建并读日志、在 REPL 读按钮、或在 Home Assistant 看见按钮实体。只安装支持这个验收点的一套工具；以后切换时保留当前源文件与版本记录。
参考：[1] Arduino-ESP32 3.3.12：安装文档与稳定版索引[2] ESP-IDF v5.5.5 / S3：Get Started[3] MicroPython v1.26.0：ESP32 快速参考、REPL 与 Pin[4] ESPHome 2026.9.1：项目说明与发布来源[5] ESPHome 官方：首个设备与命令行流程
想用短程序理解外设：从 Arduino 开始
如果想亲手写点灯、读按钮和打印传感器值，Arduino 提供较短的起步路径。你编辑 sketch，选择 board/core 与库版本，再编译成设备固件。Arduino 是框架与工具生态，不限定必须购买某一种 Arduino 品牌开发板。
本站起步组合固定 core 3.3.12、IDE 2.3.8，命令行复验用 CLI 1.5.1。先完成 F05 的官方 GetChipID 编译，再做 F06 的两次上传与日志标记。这样以后外接 LED 不亮时，能够区分上传链路与电路问题。IDE 里能找到一个库，不代表它与你的芯片、core 大版本或板引脚自动匹配。
- 做到这里，你应该看到
- 第一次任务是编译和上传可识别版本的串口程序；不是同时做 Wi-Fi、屏幕和语音。
要理解系统配置与调试：直接选 ESP-IDF
如果任务涉及组件依赖、menuconfig、任务调度、分区、底层调试或较完整的工程管理，可以直接选乐鑫 ESP-IDF。工具包含指定芯片的编译器、CMake/Ninja 与框架；一个工程的源码、sdkconfig 和组件版本共同决定构建结果。会一点 C/C++ 和命令行会有帮助，Arduino 不是硬性前置。
从 v5.5.5 的 S3 Get Started 入口进入与你系统对应的安装说明，以 hello_world 为首个工程，按 set-target、build、flash、monitor 走完整链路。成功判据包括重新打开终端后能重建，以及实板出现该工程的日志；只安装完扩展不算完成。本文只核对路线与入口，不代替后续完整安装教程，也没有把这个工程算为已构建。
Arduino-ESP32 自身基于特定 ESP-IDF 组合；用 Arduino 并不要求另装一份 IDF。但也不能从两者有关联，推导任意 IDF API 或网上配置都能在当前 core 直接使用。本文后面的 Arduino 示例以 core 3.3.12 实际携带的版本为准。
已有 Python 基础：从解释器、REPL 与文件开始
MicroPython 适合想快速输入一条语句、立即观察 GPIO 的读者。先为正确芯片和板配置刷入对应解释器固件，再通过 REPL 交互或上传 .py 文件。你编辑的是运行于设备上的脚本；Arduino 的 .ino 和桌面 Python 包不能原样复制到这里。
以 v1.26.0 的 ESP32 快参为阅读基线，首作选择读取一个低压按钮：REPL 里确认 Pin 输入，再保存为 main.py，复位后确认自动执行。选择 S3 固件时还需核对 Flash/PSRAM 等目标变体，不从通用 ESP32 名称猜下载文件。本文没有替你选择一个未经复验的 S3 二进制，也不声称已有 Arduino 示例都能平移。
如果你需要的传感器库只支持 Arduino，先检查 MicroPython 驱动是否存在、协议是否相符；不因为语法同为 Python，就假设 CPython 的每个模块都有。遇到资源限制时记录固件版本和可用内存，再决定优化或换框架。
目标是 Home Assistant：从 ESPHome 的实体开始
如果已经有 Home Assistant，希望把传感器、按钮、灯做成家庭实体，ESPHome 的 YAML 配置往往更贴近任务。工具会生成并编译设备固件；这不是无需编译，也不是让 YAML 文件直接在芯片上解释执行。你仍要核对器件、GPIO、电平、网络凭据和 OTA 恢复方式。
起点用一个按钮或低压 LED，不把整屋设备配置一次搬进来。完整成功链路应包括配置校验、指定板的编译、首次 USB 写入、日志、Home Assistant 实体出现，以及之后一次可恢复的 OTA 更新。设备联网与实体可用是不同检查点；HA 不在同一网络或密钥不一致时，串口程序正常也可能无法集成。
这里阅读了 ESPHome 2026.9.1 项目来源与官方安装流程，只用来说明路线。后续实操应按其单篇教程锁定安装版本与平台工具链，不能把本篇资料阅读称为配置已编译或实体已接入。
用四个任务复查选择，并保留回退方法
“写一个每秒打印计数的小程序”可从 Arduino 的安装与上传入手；“看任务栈和系统配置”从 IDF hello_world 开始；“输入 Python 语句试按钮”从 MicroPython REPL 开始；“把实体按钮加进 HA”从 ESPHome 的安装与首个实体开始。这四个完成物各有直接入口，不必先经过其他三条路线。
切换路线通常会改写 Flash 中的固件；先保存源码、依赖与必要配置，网络凭据不要放到公开仓库。要回退到 Arduino，重新烧入已保存版本的 sketch；要回到 MicroPython，重新刷入已记录的解释器目标再恢复脚本。仅恢复源码目录不等于设备固件已恢复。
路线选定后，所有方案都要做板级引脚和供电核对。四条路线比较的是工作方式，本文没有跑耗时、内存或功耗基准，不能用这张路线图作性能排名。
参考：[1] Arduino-ESP32 3.3.12：安装文档与稳定版索引[2] ESP-IDF v5.5.5 / S3：Get Started[3] MicroPython v1.26.0：ESP32 快速参考、REPL 与 Pin[4] ESPHome 2026.9.1：项目说明与发布来源[5] ESPHome 官方：首个设备与命令行流程[6] 乐鑫 DevKitC-1 v1.1 用户指南：固定文档提交 927ed7e
资料来源与版本说明
本文依据下列官方文档与上游资料独立整理，适用范围与版本以本文所列组合为准。资料核对日期：。资料核对、程序构建与实板测试分别记录，不互相替代。
